Connections

Everything starts in the Connections tab, the first tab of the window: the list of your connections on the left, the connection form on the right. File → Open Connection… (mod+O) brings you back to it from anywhere.

The connection list

Finding a connection

Type in Find a connection to filter the list. It matches the name, the engine, the host and the SSH host.

Sections of the list

Sort and group

The ⇅ Sort and group menu changes how the list is ordered and split:

• Sort by default (drag & drop order), Sort by name, Sort by engine
• Group by default (your groups), Group by engine, No grouping (everything under All connections)

The button beside it folds every section to its name, or opens them all again (Collapse all / Expand all); it shows when there are two or more sections and you are not filtering.

The choice is remembered for the window. Dragging to reorder only makes sense in the default order: if you drag while sorted by name or engine, a hint asks you to switch back to Sort by default.

What a row shows

Each row has the connection’s colour accent, the engine logo with a presence dot (Connected, Service stopped or Not connected), the name and a star. The second line tells you how it connects — engine · host:port, the file for SQLite, via SSH user@host, · AWS IAM as user, · credentials from Vault, or · SSL.

Chips on the row:

• the safety mode — Normal, Production or Read-only (see Production safety);
• the method when it is not plain TCP — SocketNamed pipe, SSH, AWS IAM or Vault;
• Connected, Stopped (a DevCatz service that is not running), DevCatz not installed, or Stopped · start it in DoCatz (a DoCatz service whose container is stopped).

Hover a row for quick buttons: Disconnect (when connected), Open in a new tab (+) and More (⋯).

The row menu

Press ⋯ or right-click a row:

• Open · Open in a new tab · Disconnect (when connected)
• Add to Favorites / Remove from Favorites
• Move to group — each of your groups (✓ marks the current one), New group…, and Remove from “<group>”
• Edit… · Delete… — saved connections only

Deleting asks first, and says what it means: Only the connection is removed; the server and its data are untouched.

Groups and drag & drop

• New group… asks for a name in the New group prompt; Create & move makes it and moves the connection in.
• The ⋯ on a group’s head (or a right-click on it) has Rename group…, Move up, Move down and Delete group (keeps the connections).
• Drag a connection onto a row to put it just before that row, in that row’s section.
• Drag it onto a section head to move it into that group, or into Favorites.

Colour per connection

Each connection has a Tab colour — six swatches in the form. It shows as the accent on its row and its tab, so a production server can look different at a glance.

The connection form

Press + in the tab strip or File → New Connection… (mod+N). The form is titled New connection (or Edit <name> when you edit one), with the line Local, behind SSH, on AWS RDS or with credentials from Vault. It has two setups, as tabs: Set up by hand and From a URL.

Connect from a URL

Switch to From a URL and paste into Connection URL:

• Connect (or enter in the field) opens it right away, for this session only — it lands under Opened from a URL and is gone when DBCatz quits.
• Fill in the form moves everything into Set up by hand, so you can name it, pick a safety mode and save it.

A whole DATABASE_URL=… or REDIS_URL=… line copied from a .env works too. Special characters in the password must be %-encoded.

URL schemes DBCatz reads

A jdbc: prefix is dropped, so a JDBC URL works as well.

Query parameters DBCatz reads

Opening a URL from a link

dbcatz://url?u=<the URL, encoded> opens a URL connection the same way — useful from scripts or notes. See Deep links.

Set up by hand

Name, colour and safety

• Name — anything you like (e.g. Shop production).
• Tab colour — one of six swatches.
• Safety — Normal (Edit freely; risky changes still ask.), Production (Asks before every write; marked PROD.) or Read-only (Only reads; the server session is read-only too.). What each does is on Production safety.

Engine

Pick MySQL, MariaDB, PostgreSQL, SQLite, Redis, Valkey, MongoDB or Elasticsearch. The port fills in with the engine’s default (3306, 5432, 6379, 27017 or 9200).

Connection methods per engine

The Server section has a tab per method. Which ones you get depends on the engine:

TCP/IP

Host and port. That is all — the login comes below.

Unix socket or named pipe

SSH tunnel

Through an SSH host — DBCatz opens the tunnel itself. No separate tunnel to start first.

• SSH host, Port (22) and User.
• Sign in with: Private key, Password or ssh-agent.
• Private key — the keys found in ~/.ssh%USERPROFILE%\.ssh are suggested, ed25519 first; or Choose… another file. A Passphrase field takes the key’s passphrase, if it has one.
• ssh-agent uses the agent behind SSH_AUTH_SOCK, so it needs a running agent with your key added. On Windows, when SSH_AUTH_SOCK is not set (it usually is not), DBCatz talks to the OpenSSH Authentication Agent service on \\.\pipe\openssh-ssh-agent, and the form reads Keys from the OpenSSH agent.

With SSH on, the host field becomes Database host, as seen from the SSH host — often 127.0.0.1. DBCatz keeps the tunnel alive with a keepalive every 15 seconds, and Disconnect closes the tunnel too.

AWS IAM (RDS and Aurora)

A 15-minute token signs in; SSL with Amazon’s RDS certificates is always on.

• RDS endpoint — the host field gets this label. Region is guessed from the endpoint; change it if needed.
• Credentials — default profile / environment, profile <name> (every profile in ~/.aws/credentials and ~/.aws/config%USERPROFILE%\.aws\credentials and %USERPROFILE%\.aws\config), or the access key below.
• Access key ID and Secret access key — only for the access key below.
• Database user with IAM auth — the user field gets this label: a database user set up for IAM authentication.

DBCatz signs a SigV4 auth token on your computer, valid for 15 minutes, and reopens the connection with a fresh token after 10 minutes, so a long session keeps working. For SSL it uses Amazon’s RDS certificate bundle, downloaded once from truststore.pki.rds.amazonaws.com on the first IAM connect and kept in DBCatz’s data folder.

HashiCorp Vault

HashiCorp Vault — the user name and password are read from the secret each time.

• Address — your Vault server.
• Namespace — optional.
• Secret path — for example database/creds/readonly for dynamic database credentials, or a KV v2 secret.
• Token — a Vault token (hvs.…).

The credentials are fetched every time you connect; they are never stored in DBCatz.

SQLite: a file or a folder

Database file or folder with Choose… (.sqlite, .sqlite3, .db, .db3, .s3db). Pick a folder and each file in it becomes a database in the database picker.

MongoDB Atlas

Tick Atlas / mongodb+srv (the host is an SRV record) for an Atlas cluster or any SRV host.

Login

• User — optional for Redis, Valkey, MongoDB and Elasticsearch.
• Password — with Show / Hide. A password already saved shows as •••• (kept).
• Database — PostgreSQL: opened first; others from the sidebar, default postgres. MongoDB: also the auth database. MySQL: optional: opened first.

Advanced options

Advanced is folded, with a one-line summary such as no SSL · server time zone · 15 s timeout. Only the options the engine and method take are shown:

Save, test and connect

• Test connection — tries every step without opening a tab.
• Save — keeps the connection in the list.
• Connect (new) / Save & connect (edit) — saves and opens it.
• Cancel — when editing.

Saving a URL connection

A connection opened from a URL shows a Save… button on its row (Keep it as a saved connection). Its menu has Open, Disconnect, Save… and Forget. Save… opens the form as Save <name> so you can name it and choose its safety mode.

What Test and Connect show

Test and Connect list every step as they take it, with Cancel:

1. Reading credentials from Vault
2. Creating an AWS IAM auth token
3. Opening an SSH tunnel through user@host
4. Reaching host:port (through the tunnel)
5. Signing in (over SSL)

SQLite has one step: Opening the database file. The step that fails is the one to look at.

Readable errors

DBCatz turns the usual failures into plain words, with a hint where one helps:

The failure and disconnect screens

When a tab cannot connect, it says Could not connect to <name> with Close tab, Try again, and Edit connection (saved connections) or Open in DevCatz (DevCatz services, with the line Start the service in DevCatz (Database page), then try again.).

After Disconnect, the tab says Disconnected from <name> with Close tab and Reconnect.

DevCatz services

When DevCatz is installed, the databases it runs show up under DevCatz services on their own — no setup. Each has a live status dot (connected, Service stopped). DBCatz picks up changes as they happen and checks for DevCatz again whenever its window comes back into focus.

DevCatz services are a little different from saved connections:

• They are always Normal mode.
• They cannot be edited or deleted here — their menu has no Edit… or Delete…. Change them in DevCatz.
• When a service is stopped, its tab offers Open in DevCatz so you can start it.

If DevCatz is not installed, a card says Local databases with DevCatz with Install DevCatz. If DevCatz was removed but its services file is still there, the card says DevCatz is not installed with Install DevCatz again, and its services are shown dimmed. Install opens DevCatz’s download page for your computer — the Mac build for your chip (Apple silicon or Intel), or the Windows installer.

DoCatz services

DoCatz gives every database container on its engine — PostgreSQL, MySQL, MariaDB, Redis, Valkey, MongoDB, Elasticsearch or OpenSearch — an address on this computer, 127.0.0.1:<port> (the engine’s own port plus 10000: 15432, 13306, 16379 …), and hands them to DBCatz the way DevCatz hands its services: a dbcatz/services.json in DoCatz’s data folder, readable by you only, with the engine, version, address and the user, password and database the container was started with.

The database services running in DoCatz show up here by themselves under DoCatz services (with DoCatz’s icon on the heading, as DevCatz’s on its own group), next to DevCatz services, with a live status — nothing to add or type. Each row reads engine · project · 127.0.0.1:<port>. With DoCatz but no database container yet, the group says No database container yet. Start a project with PostgreSQL, MySQL, Redis, MongoDB … in DoCatz.

• Open in DBCatz on a database in DoCatz opens that very service here, signed in (dbcatz://open?docatz=<id> — the link carries no password).
• Open in DoCatz — in a DoCatz service’s right-click menu, and on its error screen when the container is stopped (Start <project> in DoCatz, then try again.) — opens that container’s page in DoCatz (docatz://container/<name>; an older DoCatz just comes to the front). Without DoCatz, DBCatz says it is not installed.

With DevCatz, DialCatz and DoCatz

• DevCatz → DBCatz: Open in DBCatz in DevCatz opens the service’s database here (and installs DBCatz first when it is missing).
• DBCatz → DevCatz: Open in DevCatz on a service’s error screen, and the Open DevCatz step of Ask DBCatz, open that service in DevCatz. Without DevCatz, its download page opens.
• DoCatz → DBCatz: Open in DBCatz on a database in DoCatz opens that service here — see DoCatz services.
• DBCatz → DoCatz: Open in DoCatz on a DoCatz service opens its container’s page in DoCatz.
• DialCatz → DBCatz: DialCatz can see your DBCatz connections — their name, engine, host, port and database only; no users, passwords or URLs, and no session connections. Check in DBCatz after a request opens the table the call touched, filtered to the row. DBCatz builds that filter itself, quoted (MongoDB {col: val}, Elasticsearch a match query, Redis the exact key) — nothing from the link runs as SQL. If the table does not exist, DBCatz stays at the database and says so.

How the apps find each other is explained in What the cats share.

Deep links

DBCatz opens dbcatz:// links:

Parameters are trimmed and length-limited, and control characters are rejected.

Last updated 2026-11-03