# 2. Connections

*Tabellum for desktop, chapter 2. On the web: https://tabellum.dudko.dev/manual/desktop/connections*

A connection is the address of one database and how to log in to it. Tabellum keeps as many as you like and can have several open at once.

## 2.1 Adding a connection

1. Click **+** next to **CONNECTIONS** in the sidebar.
2. Pick the **Driver** (1): PostgreSQL, MySQL / MariaDB, SQL Server, BigQuery, SQLite or MongoDB.
3. Fill in the host, port, database, user and password.
4. Click **Test** (4). When the test passes, click **Save**.

![A new connection](https://tabellum.dudko.dev/manual/desktop/img/connection.jpg)

*A new connection*

Marked on the screenshot: (1) The database type; (2) Fill the form from a connection string; (3) Refuse every write on this connection; (4) Try the connection before saving.

Three switches decide what may happen on the connection:

- **Read-only** (3): every session opens read-only. The server refuses writes, and Tabellum refuses them before they reach it.
- **Sensitive**: the connection is drawn in a warning color, and the AI agent gets only its schema.
- **Agent may see rows**: off by default. While it is off, the agent sees tables, columns and row counts, never values.

## 2.2 Cloud databases

For a hosted database, pick its provider under **Cloud preset** (1). The preset fills in the port, TLS mode and driver settings the provider needs and explains what is special about it (2) — for example, that a transaction pooler has no prepared statements.

![A cloud preset](https://tabellum.dudko.dev/manual/desktop/img/connection-preset.jpg)

*A cloud preset*

Marked on the screenshot: (1) A cloud provider's settings; (2) What the provider needs.

## 2.3 Pasting a connection string

If you have a connection string (`postgres://…`, `mysql://…`, `mongodb+srv://…`, a JDBC URL), click the clipboard button (2) in the first picture and paste it. Tabellum fills in the form, puts the password into the keychain and lists what it set and what it could not (1).

![The form filled from a pasted string](https://tabellum.dudko.dev/manual/desktop/img/connection-paste.jpg)

*The form filled from a pasted string*

Marked on the screenshot: (1) What the string set, and what it could not.

## 2.4 SQLite files

An SQLite database is a file, so its connection has no host or login. **Browse…** (2) picks an existing file and **New…** (3) creates an empty one. On the Mac App Store version a picked file is copied into the workspace’s `sqlite/` folder, because the app may only keep access to its own folder.

![An SQLite connection](https://tabellum.dudko.dev/manual/desktop/img/connection-sqlite.jpg)

*An SQLite connection*

Marked on the screenshot: (1) The database file; (2) Pick an existing file; (3) Create a new database file.

## 2.5 Editing a connection

Each connection in the sidebar has a pencil button, **Edit**, that opens the same form. The other buttons on the row refresh the schema and connect or disconnect. A connection that cannot connect shows one line saying what failed and what to check — a refused port, a timeout, a wrong password or a TLS problem. **Copy details** copies the full message.

After the computer sleeps, Tabellum reconnects the open connections by itself. A read that failed because the connection dropped is retried once; anything else offers **Run again**.

## 2.6 SSH and WireGuard tunnels

When a database is only reachable through a server or a VPN, add a tunnel and choose it in the connection’s **Tunnel** field.

![A new tunnel](https://tabellum.dudko.dev/manual/desktop/img/tunnel.jpg)

*A new tunnel*

Marked on the screenshot: (1) SSH, or a WireGuard peer; (2) How the server's key is checked; (3) Reach it through another tunnel.

- **SSH** (1) logs in with a private key (and its passphrase) or a password. **WireGuard** connects as a peer; paste a `wg-quick` configuration and the fields are filled in. Neither needs a system VPN or administrator rights.
- **Host key** (2) decides how the server’s key is checked. With **Ask on first connection**, Tabellum shows the key’s fingerprint the first time and remembers it.
- **Via (jump host)** (3) reaches the server through another tunnel.

![The first connection to an SSH server: compare the fingerprint, then trust it](https://tabellum.dudko.dev/manual/desktop/img/host-key.jpg)

*The first connection to an SSH server: compare the fingerprint, then trust it*

> **Note:** The Mac App Store version cannot use the SSH agent; paste the private key into the tunnel instead. It is kept in the keychain.

## 2.7 Sharing connections

Connections and tunnels move to another window or device with a code. Choose **Share connections…** in the Tabellum menu (**⋯** at the foot of the sidebar, the File menu on a Mac) or the command palette, or **Share…** in a connection’s menu or in **Tunnels…**.

![A connection as a QR code, a text, and a file](https://tabellum.dudko.dev/manual/desktop/img/share.jpg)

*A connection as a QR code, a text, and a file*

Marked on the screenshot: (1) Pick the connections; their tunnels come along; (2) Passwords and keys, encrypted, only if you ask; (3) A QR code for a phone's camera; (4) The same code as text; (5) Or saved as a file.

Tick what to send (1) a connection’s tunnel comes along by itself. Then send it whichever way suits: scan the QR code (3) with a phone, copy it as text (4) into another window, or save it as a file (5) and send it by mail or AirDrop.

Passwords and keys stay on this computer unless you turn on **Include passwords and keys** (2). Then you type a passphrase twice, at least 6 characters, and the code carries them encrypted with it.

> **Warning:** Anyone who has the code and the passphrase can reach those databases. Send the passphrase another way than the code: say it, don’t paste it next to the code.

On the other side, choose **Import connections…**.

![Importing a code that carries passwords](https://tabellum.dudko.dev/manual/desktop/img/import.jpg)

*Importing a code that carries passwords*

Marked on the screenshot: (1) Paste the code; (2) Or open the file; (5) Or a photo or screenshot of the QR code; (3) The passphrase, when the code carries passwords; (4) What is added, and what to do with a name taken here.

Paste the code (1) or open the file (2). The first panel reads the QR code: hold it up to the camera on a Mac, or choose a photo or screenshot of it (5). If the code carries passwords, type the passphrase (3) and choose **Unlock**, or **Skip the passwords** to type them later. The list (4) shows what will be added. When a connection or tunnel of that name is already here, choose **Import as a copy**, **Replace mine** or **Skip, keep mine** nothing is written until **Import**.