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.
What's on the screen
| No. | Name | Description |
|---|---|---|
| 1 | Tab bar | The 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. |
| 2 | Connection name and Description | The name shown in the explorer and a note. The name is required. |
| 3 | DBMS field | The connection's DBMS. You cannot change the DBMS of a saved connection. |
| 4 | JDBC Driver | The JDBC driver used to connect. The gear button next to it opens the JDBC Driver Manager dialog (Driver management). |
| 5 | Connection fields | Host, 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. |
| 6 | JDBC URL | The JDBC URL built from the connection fields. You can also edit it directly. |
| 7 | Test Connection button | Tries to connect with the current input and, if it works, fetches the schema list. The result shows as an icon next to the button. |
| 8 | Reset button | Clears the input after a confirmation. See 'Things to keep in mind' below. |
| 9 | Save, Cancel and Delete Connection buttons | Save or close. The Delete Connection button appears only for a saved connection; the effect of deleting is explained in Object explorer. |
Tabs
| Tab | What it does | Available |
|---|---|---|
| Connection | DBMS and connection details | Always |
| SSL/SSH | SSL/TLS, SSH Tunnel and proxy. Explained in SSL/TLS and SSH tunnels | After you click Connect to DB |
| Schema | The schemas shown in the explorer | After the Test Connection button has fetched the schema list |
| Properties | Properties passed to the driver when connecting | After you click Connect to DB |
| Profile | Environment, Color, Background watermark and Protection mode. Explained in Connection profiles | Always |
| Table Template | The columns pre-filled when you create a new table on this connection | Always |
| Renamer | Rules that turn table and column names into class and field names when generating source code. Explained in Generating source code | Always |
| Data Dictionary | The domains and dictionary this connection uses. Explained in Assigning to a connection | Saved 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 forBIGINT, 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
- 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.
- Choose the DBMS in the DBMS field (3). If you save at this point, you get a connection for drawing ERDs without connection details.
- 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.
- Enter the connection details. The JDBC URL field (6) follows along.
- 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).
- In the Schema tab, choose the schemas to show in the explorer ('Schema tab' below).
- 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 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.
| DBMS | Different fields |
|---|---|
| DBMSs with several connection methods | Connection Type and Driver appear. Your choice changes the shape of the URL |
| Oracle | Choose Normal, SYSDBA or SYSOPER in Role |
| PostgreSQL | Has the Supabase mode option. If the host is a Supabase address, the Switch to Supabase link appears |
| Databricks | The 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 |
| Snowflake | Has Warehouse and Role fields. The Refresh lists button loads the database and warehouse lists. Both values go into the URL as parameters |
| BigQuery | The 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 Embedded | A 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 URL | Properties tab | |
|---|---|---|
| Holds | The Host, Port and Database fields and the parameters you typed at the end of the URL yourself | A list of keys and values |
| Built from | Rebuilt when you edit the connection fields. Parameters you typed stay as they are | Filled with the DBMS's default properties (such as connection timeouts) when you choose the DBMS. You can edit or delete them |
| When connecting | Passed to the driver as is | Not 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. | Name | Description |
|---|---|---|
| 1 | Use Schema Prefix | Makes templates put the schema name in front of table names when generating source code. |
| 2 | Refresh Schemas button | Fetches the schema list from the database again. Click it after creating a schema in the database. |
| 3 | Schema Pattern line | The schemas checked now. |
| 4 | Schema list | Only 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.
| Dialog | When it appears | Where |
|---|---|---|
| Saving without connection details | When you save without clicking Connect to DB. It confirms that you can add connection details later | All projects |
| Change connection target | When you change the target of a saved connection (below) | All projects |
| Credentials will not be encrypted | When you entered secrets but this computer's OS secure storage is not available. If you continue, the secrets are stored in plain text | Local projects |
| Desktop-only Connection | When you save or test a SQLite, H2 Embedded or localhost connection in the web app. It does not proceed | Web app |
| Switch to Private Connection, Switch to Public Connection | When changed connection details move the connection between public and private. If team ERDs become personal ERDs, they are listed | Account 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. | Name | Description |
|---|---|---|
| 1 | Notice | Tables 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. |
| 2 | Keep ERDs | When 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. |
| 3 | Cancel and OK buttons | Cancel 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
- Right-click a connection in the explorer and choose . The Duplicate Database Connection dialog opens filled with the original's settings, and (Copy) is added to the name.
- Change the name and anything else that differs.
- 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.
- 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 .
- 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.
Related screens
- Connections and execution targets: what a connection holds, the levels of execution targets, and where connection details are stored.
- SSL/TLS and SSH tunnels: the options in the SSL/SSH tab.
- Connection profiles: the options in the Profile tab.
- Driver management: adding and removing JDBC drivers.
- Object explorer: opening, refreshing and deleting saved connections.
- Database reference: connection fields and defaults that differ by DBMS.