Connect to Database

DbSchema connects to more than 100 SQL and NoSQL databases. It reads the tables of the database and shows them as diagrams. The list of databases has setup notes for each one.

Connecting needs no license: the free Community edition connects to every database.

Connect to a database for the first time

You connect once, and DbSchema saves the connection for the next time.

1. Choose File → New Model. The start window shows the same choice under Start New.
2. Keep Connect to Database selected at the top.
3. Click your database, such as PostgreSQL. Type in Search databases to find it.
4. Choose New Connection on the right, or a connection you saved before.
5. Press Connect. The connection dialog opens.
6. Fill in the dialog, as the next section shows, and press Connect.

DbSchema reads the schema into a new model. Connecting reads from the database and changes nothing in it.

If your database is in the list, choose it there. The New button of the JDBC Drivers Manager is meant for a database that DbSchema does not know yet.

Fill in the connection dialog

First choose the Method. The dialog shows no fields until you choose one. Then it asks three questions: where the database runs, how to sign in, and which database to open.

• Connection Name: the name DbSchema shows for this connection everywhere.
• Method: how DbSchema builds the connection. Standard fits most databases. To use a URL you already have, choose Paste a JDBC URL, the last entry. Some databases add their own entries, as Choose a connection method explains.
• Where is the database running?
  • This computer, default port: the database runs on your computer, on its usual port.
  • Remote computer or custom port: type the Server Host and the Port.
• Database User and Password: the login defined in the database. Tick Remember to keep the password.
• Database: the database to open. Create New creates one on the server.
• JDBC Driver: the driver file DbSchema talks to the database with. DbSchema downloads it the first time. The wrench button next to it opens the JDBC Drivers Manager.

Press Test Connection to check the settings before you connect. Tips & Help opens the setup notes for your database.

Paste a JDBC URL

A JDBC URL is the address of a database in one line, such as jdbc:postgresql://127.0.0.1:55432/shopdb. DbSchema builds it from the fields, so you only paste one when you already have it, for example from a cloud console.

1. Open the Method list and choose Paste a JDBC URL. It is the last entry.
2. Paste the URL into JDBC URL.
3. Type the Database User and Password.
4. Press Test Connection, then Connect.

The URL already holds the host, the port and the database, so the dialog hides their fields.

Add a connection to an open model

A model can keep several connections, for example one to a test database and one to production.

1. Click the connection button in the toolbar. It shows the name of the current connection.
2. Choose Add Connection. The same entry is in Database → Add Connection.
3. Choose the Method, fill in the dialog, and press Test Connection.
4. Press Connect.

To change the current connection, choose Edit Active Connection in the same menu, or Database → Manage → Edit Active Connection.

Choose a connection method

The Method list holds the ways DbSchema can connect to your database. Most entries come from the JDBC driver, so the list differs from one database to another.

• Standard: DbSchema builds the URL from the host, port and database you type.
• Paste a JDBC URL, the last entry: you paste the whole URL, as Paste a JDBC URL shows.
• SQL Server adds Windows Authentication, to sign in as a Windows user, and Windows Authentication, Current User, to sign in as the user running DbSchema. Both work on Windows only.
• Snowflake adds Single Sign-On in the Browser (Okta, Entra ID, Ping), which signs in through your browser and asks for no password, and Private Key File.

Add SSL and driver parameters

Each driver has its own settings, such as encryption and timeouts. DbSchema lists them for you, so you do not write them into the URL by hand.

1. Open the Advanced tab of the connection dialog.
2. Press the pencil next to SSL & Parameters.
3. Pick a group on the left, such as SSL / TLS, tick it, and choose the values.
4. Press OK.

A group you leave unticked stays out of the URL, so the driver keeps its own default. Each value has a short explanation under it.

For PostgreSQL, the SSL Mode decides how strictly DbSchema checks the server:

• Prefer: the driver default. It tries SSL, falls back to a plain connection, and checks no certificate.
• Require: always encrypt, without checking the certificate. Cloud databases usually need this one.
• Verify CA: encrypt, and check the server certificate against a CA Certificate File you choose.
• Verify Full: also check that the host name matches the certificate.

To see the URL DbSchema will connect with, press the eye button next to SSL & Parameters.

The rest of the Advanced tab:

• Properties: driver settings typed as key1=value1;key2=value2. They reach the driver as connection properties, not as part of the URL. Oracle with Kerberos sign-in is the usual example.
• Custom Time Zone: a fixed time zone for this connection. Set it when timestamps show shifted because your computer and the server use different time zones.

Connect through an SSH tunnel

An SSH tunnel reaches a database that only a jump host can talk to. DbSchema connects to the SSH server, and the SSH server connects to the database.

1. Open the Advanced tab of the connection dialog.
2. Press the pencil next to Configuration, under SSH Tunnel.
3. Press + to add a configuration.
4. Type a Name, the SSH server's Host, and its Port (22 by default).
5. Choose how to sign in, and fill in its fields.
6. Press Test Tunnel, then Close.
7. Choose the new configuration in the Configuration list.

The ways to sign in to the SSH server:

• Password authentication: the user and password on the SSH server.
• Public key authentication: the user, the Private key file in OpenSSH, PEM or PuTTY (.ppk) format, and its Passphrase if it has one.
• SSH agent authentication: the user alone. The keys stay in the running agent, such as ssh-agent or Pageant.
• No authentication: for a server that asks for none.

A configuration is saved once and shared: several connections through the same jump host use one entry.

On the Connection tab, type the database host and port as the SSH server sees them. That is often localhost, when the database runs on the SSH server itself. The Firewall, Proxy & SSH page has more on networks.

Protect a production connection

The Settings tab marks a connection so you do not change the wrong database by mistake.

• Read Only Connection: the database refuses every change made through this connection. Use it on production.
• Highlight: colors the connection as Production, Development or Test, so you see at a glance where you are.
• Schema Mapping: shows a schema of the model under another name in this database, so one model fits several databases.
• Included Schemas: the schemas that are ticked first when DbSchema imports from this connection, such as public, auth, tenant_*.
• Java Location: where the Java bundled with DbSchema lives. Some sign-in methods need files in it.

Manage your saved connections

The Connections Manager lists the saved connections for the database type of the open model. Open it with Database → Manage → Connections Manager, or from the connection button in the toolbar.

• The buttons on each row edit, clone, disconnect and delete the connection.
• The eye button lists the connection in the connection menu, or hides it there.
• Add creates a connection. Import and Export move connections between computers as a file.
• Connect opens the selected connection. A double-click edits it.

What leaves your computer when you connect?

Before you connect DbSchema to a database with real data, you want to know what leaves your computer.

• The connection is direct. The JDBC driver runs inside DbSchema on your computer and talks to the database server itself. No DbSchema server sits in between.
• Structure first, data only when you ask. Connecting reads the schema: tables, columns, keys. DbSchema reads table data when you open a table or run a query.
• The model is your file. DbSchema saves the design as a .dbs file on your computer.
• Credentials stay on your computer. DbSchema saves a password only when you tick Remember, and saves it locally.
• AI is optional. The AI assistant sends your question, and the tables or files you attach to it, to the AI provider you chose.

Wise Coders, the company behind DbSchema, is ISO 27001 certified.

Common problems

I can't find Connections in the menu

DbSchema 10.5 moved the connection entries into the Database menu:

• Database → Add Connection creates a connection.
• Database → Manage → Connections Manager lists the saved ones.
• Database → Manage → Edit Active Connection changes the current one.

The connection button in the toolbar holds the same entries.

SQL Server: Windows integrated authentication fails

Choose Windows Authentication or Windows Authentication, Current User as the Method. Both work only when DbSchema runs on Windows.

Windows sign-in needs Microsoft's mssql-jdbc_auth DLL. DbSchema downloads it with the SQL Server driver, into .DbSchema\drivers\SqlServer\native-win in your home folder. If the error says Native SSPI library not loaded, check that this folder holds the DLL.

On Linux and macOS, sign in with Kerberos instead. Open SSL & Parameters on the Advanced tab, then choose Authentication → Integrated Security Scheme → Java Kerberos.

SQL Server 2012: "The driver could not establish a secure connection"

An old server, such as SQL Server 2012 without its updates, offers only TLS 1.0 or TLS 1.1. The Java bundled with DbSchema refuses both, so the encrypted handshake fails.

• Best fix: install the latest service pack and Microsoft's TLS 1.2 update on the server.
• If the server cannot change: tick Edit → Settings → Network → SSL Certificates → Allow Legacy TLS Algorithms, and restart DbSchema. This lowers the security of every connection DbSchema makes, so keep it for this case.

SSH tunnel: the private key is refused

• "Cannot load the private key file": the file is not a private key. You probably chose the public key, such as id_ed25519.pub. Choose the file with the same name and no .pub.
• "Incorrect passphrase for the private key file", or "Auth cancel": the key has a passphrase. Type it in Passphrase in the SSH configuration.

Snowflake asks for a password, but I sign in with SSO

A password cannot sign in an account that uses single sign-on (Okta, Entra ID, Ping) or MFA. Edit the connection and choose Single Sign-On in the Browser (Okta, Entra ID, Ping) as the Method. DbSchema opens your browser for the sign-in.

I defined a new DBMS by mistake. How do I delete it?

DbSchema has no button for this. Close DbSchema, then delete the folder named after that DBMS in .DbSchema/drivers, in your home folder. The JDBC Drivers Manager explains the folders.

The connection still fails

When a connection fails, DbSchema shows the driver's error, with advice for the errors it recognizes. Then check that your computer reaches the server:

• ping dbserver.example.com checks that the server answers at all.
• telnet dbserver.example.com 5432 checks that the database port is open.
• openssl s_client -connect dbserver.example.com:5432 checks a port that uses SSL.

If the port does not answer, a firewall is in the way. See Firewall, Proxy & SSH.

Next steps

• Install or upload a JDBC driver
• Connect through a firewall, a proxy or an SSH tunnel
• Edit tables, columns and indexes
• Compare the model with the database