The "Discover Databases" window lists every database the Invantive products know: the ones found on the workstation and in the network, and the ones defined in the settings files described in [[Settings]]. From release 27.0 onwards that window also adds, changes and removes those definitions, so that a database on Microsoft SQL Server, PostgreSQL, Oracle or another supported platform is defined without opening a file. The window is reached from the log on screen, through the button beside the description of the selected database. That button and that screen are unchanged; everything described here lives inside the window it opens. ## What a Tile Shows Every database is a tile under the bar of its group. A tile carries the icon of the driver which reaches the platform, or the database icon when the database reads from several platforms. Beside it stands the tick box which leaves a database out without removing it. A mark and a sentence appear when something about the settings file matters: - Maintained by discovery. The definition is rebuilt by every discovery run. "Edit" stores a separate copy in the settings file of the user, which the products then prefer. The original stays where it is. - Read-only. The settings file holding the definition cannot be written. "Edit" does the same as above. - Also defined elsewhere. A second settings file defines the same database and that one wins. The "Settings Files" window says which. The menu button of a tile offers "Edit", "Test", "Duplicate", "Delete" and "Show in Settings Files". A database which is copied or newly defined while the window stands open appears as a tile at once. The refresh button of a group searches for databases again with the drivers which filled that group and reads the settings files after them. It stands on the bar of a group which a driver filled and on no other, since a group of definitions made by hand has nothing to search for. A database which has gone from the platform stays on the screen until the window is opened again. The bar of a group carries "Add Database", which opens the wizard with that group chosen, and "Edit", which changes the name, the descriptions and the sort order of the group in every settings file which can be written. Both stand in the bar of the group they act on, beside its refresh button. A group bar and a tile are dragged into an order of choice: press it and move the pointer, or press it and hold, and a line shows where it will land. A group bar dragged onto another group bar takes its place; a tile dragged onto another tile of its group takes that place; a tile dragged onto the bar of another group moves into that group. A press which does not move opens what was pressed, so a tile still opens the editor. The order is written into every settings file which can be written, so it survives closing the window. A database maintained by discovery or held in a settings file which cannot be written is not dragged, since the first is rebuilt by the next run and the second cannot be saved. A group in which nothing was ever dragged stays in alphabetical order. ## Defining a Database "Add Database" walks three steps: - The database: its name, the group it belongs under, its descriptions and where it stands among the others. A database is what a user logs on to. - The data container: one platform the database reads from, in four questions. Which of the two kinds it is, which driver reaches the platform, where the platform is and which account is used, and what the log on screen asks for. A database which reads from several platforms walks this step once per platform. - Save and test: what the database will hold, the settings file it goes into, and "Finish". The two kinds of data container are a platform reached directly with a driver, and the data containers of an Invantive Cloud database handed over by the Invantive Credentials Server. The first is the usual one; the second applies where an organisation manages its databases on Invantive Cloud. For the second kind the driver question is skipped, since the Invantive Credentials Server states the driver itself: the questions are the database as the cloud knows it, the server when it is not the standard one, and which of its data containers are wanted, where an asterisk is all of them. A driver which the licence does not cover is listed and greyed rather than hidden, with the module it needs, so that the platform is known to be reachable. A new database is written into the settings file of the user, `settings-user-<logon code>.json`, without a question; see [[Settings]]. A copy of that file is written to the backup folder before every change. ## Changing a Database The tile of a database, or "Edit" in its menu, opens the editor. On the left stands a tree of the database and its data containers, on the right the members of the selected node. Every member a settings file can hold is on one of those tabs; nothing is left to a text editor. The pages of the database itself are "Database", "Advanced" and "Audit". "Advanced" holds what a database rarely states: the data cache and the data dictionary it uses, and whether the statements of a data container are exchanged without handling by Invantive UniversalSQL. A connection string to a SQL platform is composed by "Build..." beside it, which asks for the platform and then for the keywords that platform states itself; what belongs in the field is shown in the field while it is empty. A data container handed over by the Invantive Credentials Server has a page of its own, which asks the three things that kind is made of: the database as the cloud knows it, the server when it is not the standard one, and which of its data containers are wanted. Its alias is the one the cloud states and is shown rather than offered. The first page of a data container reached directly with a driver is "Data Container": the driver which reaches the platform, in the name it is sold under, the alias a statement addresses it by, the order the data containers of the database are opened in, the account the log on screen offers and what that screen asks for. The driver is stated for reading and is not changed there. An alias which the product invents is the short name of the driver, as Invantive Cloud writes it. The second page is "Attributes". The connection of a data container is a form rather than a string. The form is built from what the driver states: the keywords of the platform, and for the Invantive layer the attributes which the log on screen shows. A keyword written under another name the platform knows, such as `Server` for `Host` or `User Id` for `Username` on PostgreSQL, fills the field of that keyword. The connection string stands under the form and is editable as text, after which the form is rebuilt from that text. A changed field rewrites only its own pair: every other pair keeps its text, its spelling and its place, and a keyword which neither source declares is kept and shown under "Other". "Save" refuses a definition which the log on screen would not offer, such as a database with several data containers of which one has no alias, and names the reason. "Save" also refuses a change to a part of the definition which was not edited, and then leaves the settings file as it was. The attributes on the page are the ones the log on screen asks for, together with whatever else the connection string already sets. What this data container sets stands first, in the order the log on screen asks it; the fields it leaves to the driver follow, sorted by their caption. That order is settled when the page opens, so a value typed into a field leaves the field where it stands. The remaining attributes a driver accepts are behind one link. In that window the attributes which have been set stand first, then the categories in a fixed order from where the platform is to what support needs. Only a value which has been set reaches the connection string, and "Clear" on a row is the way back to the value the driver uses. The tick box beside the search box hides the attributes which have no value. A value which equals the default of today is a value which has been set and stays written, so that a later release which changes that default leaves the connection as it is. ## Testing a Database "Test" opens every data container the way logging on opens it and closes it again, one at a time. Per data container it reports the duration and the state in a word, and the pane under the rows holds what the selected data container reported in full: either what the platform states about itself or the message code with the explanation of the product. A test is a log on. Against a production platform it leaves an audit row and takes a slice of the rate limit budget, exactly as logging on does. A failed test never keeps a definition from being saved: a definition can be correct while the network is unavailable. ## Removing a Database "Delete" names the consequences before anything happens: which database, from which settings file, how many data containers, and what that file keeps. The database always leaves the favourites and the recently used databases described in [[Favorite Databases]]. The credentials in [[Invantive Keychain]] leave with it unless the option is unticked. A copy of the settings file is written to the backup folder first. A database found by discovery is not removed, since it is rebuilt by the next run. The tick box on the tile leaves it out instead. ## Settings Files The "Settings Files" window lists every file the products read from the `Databases` folder. Per file it states how many databases and groups the file holds, whether it can be written and why not, and when it was last written in UTC. The first word of the state says whose the file is: "yours" or "from elsewhere". Selecting a file shows its databases with their identifiers and, per database, whether that definition is the one the products use and otherwise which file holds the definition which is. That is the one place where the precedence described in [[Settings]] is visible. A database of that list carries the same menu a tile carries: "Edit", "Test Connection", "Duplicate" and "Delete". Dragging it onto another file in the list above moves the definition into that file, which is what "Move Database" does without asking for the file; a file which cannot be written refuses the drop. The file of the user takes it before anything has ever been written into it, which is how a definition from elsewhere is made one's own. ## Definitions Imported from Other Tools Discovery reads the connection definitions which other tools on the workstation already hold, so that a server is not retyped: - SQL Server Management Studio: the registered servers. - Azure Data Studio: the connections of its settings file. - Visual Studio Code with the mssql extension: the connections of its settings file. - Office data connection files and data link files: the OLE DB connection per file. - PostgreSQL password file: the host, the port, the database and the account. - MySQL Workbench: the connections. - Oracle Net: the aliases of `tnsnames.ora`. - DBeaver: the data sources of every platform it reaches. - Oracle SQL Developer and Toad for Oracle: the connections. - SQuirreL SQL and JetBrains DataGrip: the JDBC URL per alias or data source. - HeidiSQL and Navicat: the sessions in the registry of the user. An imported database is a discovered database: ticked, excludable through the tick box, carrying the name the tool gave it and a description naming the tool and the moment of the import. A password is never imported, not even from a tool which keeps it readable. Whatever a definition lacks is asked at log on. ## Function Rights The window follows the function rights of the repository. Discovering, adding, editing and deleting a database and managing the settings files are five separate rights. A control for which a user has no right is not shown; a control which is shown but not applicable states in its tool tip why.