Screens: Connections and explorer

Create and edit a connection

The Database Connection dialog sets a connection's DBMS and connection details, the schemas shown in the explorer, and the properties passed when connecting. What a connection holds and where SQL and ERDs are bound is explained in Connections and execution targets. This page goes through the dialog's tabs and fields one by one.

Where you can use itWebDesktopWithout signing inSigned inLocal projectsAccount projects

What's on the screen

No.NameDescription
1Tab barThe tabs in the 'Tabs' table below. A number next to a tab is how many secure connection options are on, schemas are selected, or properties are set.
2Connection name and DescriptionThe name shown in the explorer and a note. The name is required.
3DBMS fieldThe connection's DBMS. You cannot change the DBMS of a saved connection.
4JDBC DriverThe JDBC driver used to connect. The gear button next to it opens the JDBC Driver Manager dialog (Driver management).
5Connection fieldsHost, Port, Username, Password and Database fields. A file database such as SQLite has a single Database File field. Fields that differ by DBMS are explained under 'Connection fields' below.
6JDBC URLThe JDBC URL built from the connection fields. You can also edit it directly.
7Test Connection buttonTries to connect with the current input and, if it works, fetches the schema list. The result shows as an icon next to the button.
8Reset buttonClears the input after a confirmation. See 'Things to keep in mind' below.
9Save, Cancel and Delete Connection buttonsSave or close. The Delete Connection button appears only for a saved connection; the effect of deleting is explained in Object explorer.

Tabs

TabWhat it doesAvailable
ConnectionDBMS and connection detailsAlways
SSL/SSHSSL/TLS, SSH Tunnel and proxy. Explained in SSL/TLS and SSH tunnelsAfter you click Connect to DB
SchemaThe schemas shown in the explorerAfter the Test Connection button has fetched the schema list
PropertiesProperties passed to the driver when connectingAfter you click Connect to DB
ProfileEnvironment, Color, Background watermark and Protection mode. Explained in Connection profilesAlways
Table TemplateThe columns pre-filled when you create a new table on this connectionAlways
RenamerRules that turn table and column names into class and field names when generating source code. Explained in Generating source codeAlways
Data DictionaryThe domains and dictionary this connection uses. Explained in Assigning to a connectionSaved connections
  • In an account project, a member without permission to edit connections sees only the Profile tab, because the profile is a personal setting.
  • The Table Template tab starts with one primary key column, id (the DBMS's type for BIGINT, auto-increment, NOT NULL). Add common columns here so that you do not have to add them to every new table.

Creating a new connection

  1. Click the Connection... button above the explorer. If there are no connections yet, you can also click the Add connection button in the middle of the explorer.
  2. Choose the DBMS in the DBMS field (3). If you save at this point, you get a connection for drawing ERDs without connection details.
  3. To connect to a real database, click the Connect to DB button. The connection fields (5) appear, with the DBMS's defaults in the Host and Port fields.
  4. Enter the connection details. The JDBC URL field (6) follows along.
  5. Click the Test Connection button (7). When the Connection succeeded. notification appears, the Schema tab becomes available with the default schema checked (for MySQL and MariaDB, the database you entered).
  6. In the Schema tab, choose the schemas to show in the explorer ('Schema tab' below).
  7. Click the Save button (9). A confirmation may appear before saving ('Confirmations on save' below).
  • If a connection attempt with the Test Connection button fails, a red icon and the error returned by the database appear next to the button. After the error closes, click the icon to see it again.
  • To add connection details to a connection saved without them, reopen it with Explorer context menuEdit... and click the Connect to DB button. When you save, the Attach ERDs to this connection dialog asks which schema the ERDs you drew so far should attach to.
  • Set up SQLite and H2 Embedded file connections in the desktop app. Choose a file with the Browse... button or specify a new file with the New File... button.

Connection fields

Some DBMSs have extra or different fields. The details are in the Database reference.

DBMSDifferent fields
DBMSs with several connection methodsConnection Type and Driver appear. Your choice changes the shape of the URL
OracleChoose Normal, SYSDBA or SYSOPER in Role
PostgreSQLHas the Supabase mode option. If the host is a Supabase address, the Switch to Supabase link appears
DatabricksThe Database field appears as Catalog. The Load Warehouses button uses the host and a personal access token (in the Password field) to load the choices for the SQL Warehouse field, and you pick one
SnowflakeHas Warehouse and Role fields. The Refresh lists button loads the database and warehouse lists. Both values go into the URL as parameters
BigQueryThe Database field appears as Project. Put the service account key (JSON) in the Password field or load it with the Load key file (JSON) button. Location can be left empty
SQLite, H2 EmbeddedA single Database File field, with no host or port. The Browse... button picks an existing file. For SQLite, the New File... button sets the location and name of a new file, which is created on the first connection (for example, the Test Connection button)

The JDBC URL and properties

The JDBC URL field and the Properties tab have separate roles.

JDBC URLProperties tab
HoldsThe Host, Port and Database fields and the parameters you typed at the end of the URL yourselfA list of keys and values
Built fromRebuilt when you edit the connection fields. Parameters you typed stay as they areFilled with the DBMS's default properties (such as connection timeouts) when you choose the DBMS. You can edit or delete them
When connectingPassed to the driver as isNot appended to the URL; passed to the driver separately
  • If you edit the URL directly, the Host, Port and Database fields follow the URL. Parameters in the URL are not moved to the Properties tab.
  • Add a property by entering a key and value in the Connection Properties row and clicking the Add button.
  • If you put an SSL-related key in the URL or the properties, a hint and a warning icon tell you to manage it in the SSL/SSH tab. The value is not moved. When SSL is on in the SSL/SSH tab, that setting wins; when it is off, the value in the properties tab is passed as is.

Schema tab

No.NameDescription
1Use Schema PrefixMakes templates put the schema name in front of table names when generating source code.
2Refresh Schemas buttonFetches the schema list from the database again. Click it after creating a schema in the database.
3Schema Pattern lineThe schemas checked now.
4Schema listOnly checked schemas appear in the explorer and can be chosen as the execution target of SQL tabs and ERDs.
  • DBMSs with a database level (PostgreSQL, SQL Server, Snowflake, Databricks, BigQuery) group schemas by database. The database you connected to has a default badge; other databases fetch their schemas when you expand them.
  • PostgreSQL shows only the database you connected to at first. Turn on Show all databases to list every database you can access.
  • Other DBMSs group user schemas and system schemas separately. System schemas appear read-only in the explorer, and you can also mark a schema as a system schema from the explorer menu (Object explorer).
  • If a schema you chose before no longer exists in the database, it gets a Not in DB badge. Use the Schema Mapping button to move it onto another schema in the database, or the trash button to remove it from the connection.

Confirmations on save

When you click the Save button, the dialogs below may appear one after another depending on the situation. Cancelling any of them stops the save.

DialogWhen it appearsWhere
Saving without connection detailsWhen you save without clicking Connect to DB. It confirms that you can add connection details laterAll projects
Change connection targetWhen you change the target of a saved connection (below)All projects
Credentials will not be encryptedWhen you entered secrets but this computer's OS secure storage is not available. If you continue, the secrets are stored in plain textLocal projects
Desktop-only ConnectionWhen you save or test a SQLite, H2 Embedded or localhost connection in the web app. It does not proceedWeb app
Switch to Private Connection, Switch to Public ConnectionWhen changed connection details move the connection between public and private. If team ERDs become personal ERDs, they are listedAccount projects

The rules that decide public and private connections are explained in Connections and execution targets.

Changing the connection target

Changing the Host, Port, Database, JDBC Driver or JDBC URL field (apart from the URL's parameters) is treated as pointing at a different database. If the saved connection has tables or ERDs, the Change connection target dialog appears.

No.NameDescription
1NoticeTables that are not in the new database disappear. It also shows the connection the ERDs will be backed up to, and the tables whose changes not yet applied to the database will be discarded.
2Keep ERDsWhen on, the ERDs are redrawn against the new database (node layout is reset). When off, the ERDs are deleted and only the backup remains. Appears only when there are ERDs.
3Cancel and OK buttonsCancel does not save the connection.

After you confirm, the Schema Mapping dialog asks which schema in the new database each previously chosen schema should attach to. Schemas with the same name are preselected, and schemas left unselected are removed from the connection. Changing only SSL settings, properties or the password does not show the Change connection target dialog.

Copying a connection

  1. Right-click a connection in the explorer and choose Explorer context menuDuplicate.... The Duplicate Database Connection dialog opens filled with the original's settings, and (Copy) is added to the name.
  2. Change the name and anything else that differs.
  3. In an account project, enter the password and the SSL, SSH and proxy secrets again. The Secrets such as the password, SSL keys, and SSH/proxy credentials are not copied. Please enter them again. notice at the top reminds you.
  4. Fetch the schema list with the Test Connection button and click the Save button.
  • The copy does not take the original's AI settings, data dictionary assignment, or the tables loaded on the original (including virtual tables that are not in the database yet). It does take the connection profile.
  • In a local project, secrets are copied too.

Things to keep in mind

  • You cannot change the DBMS of a saved connection. To move to another DBMS, create a new connection.
  • If you change the host or database of an existing connection to use another database, tables that are not in the new database and changes not yet applied disappear. To use the same design on another database, copy the connection with Explorer context menuDuplicate....
  • The Reset button clears only the connection target (host, port, the JDBC Driver field, database, URL) and the credentials. The Connection name field and description, and the settings in the Properties, SSL/SSH and Table Template tabs are kept. If you click it by mistake, do not save; close the dialog with the Cancel button.