Connection form

The four sections of the connection editor and the fields each driver adds

The editor’s sidebar lists the same four sections whatever the driver. Only Network is ever absent, and only for a driver that connects directly and cannot negotiate TLS.

A PostgreSQL connection on the General tab

Section	Contents
General	Name, database type, host, port, database, credentials
Network	How the connection reaches the server, and how it is encrypted
Options	Driver options, startup SQL, Safe Mode, external and AI access, iCloud
Appearance	Color, tags, group

The bar along the bottom carries Test Connection, Cancel and Save. When Save is dimmed, the reason sits to its left, prefixed with the tab that holds the empty field.

General

Field	Description
Name	Display name in the connection list
Type	The database type. Change… retypes the connection and resets the fields the old type owned
Host	Empty falls back to the driver’s own default, usually localhost
Port	Pre-filled from the database type
Database	Optional on drivers that browse every database from one session. PostgreSQL and Redshift do not connect without one
Username	Not pre-filled. Empty means the driver’s own default
Password	Stored in the macOS Keychain
Prompt for password	Stores nothing, asks on every connect. Reads Prompt for API token on API-only drivers
Use Password File	PostgreSQL, Redshift, and CockroachDB. Reads ~/.pgpass, and reports underneath whether the file exists, has chmod 0600, and holds a matching line

SQLite, DuckDB, and Beancount replace the host fields with a file path picker.

Network

Connect via is a single choice, and the fields under it belong to whichever transport is selected. A connection uses one transport or none.

Choice	What it does
Direct	Connects straight to the host and port on General
SSH Tunnel	Forwards a local port through an SSH server. See SSH Tunneling
Remote Database File	SQLite only. Copies the file from an SSH server and opens the copy read-only. See Remote Database Files
Cloudflare Tunnel	Runs cloudflared access tcp. See Cloudflare Tunnel
Cloud SQL Auth Proxy	MySQL, PostgreSQL, and SQL Server. See Cloud SQL Auth Proxy
SOCKS Proxy	Routes through a SOCKS5 proxy, which also resolves the hostname. See SOCKS Proxy
Tunnel Command	Holds a kubectl port-forward, an AWS SSM session, or a command of your own. See Tunnel Command

Leave it on Direct unless the database is unreachable from this Mac. Switching to another transport keeps what you typed into the previous one, so switching back costs nothing.

Socket Path, under SSH Tunnel, forwards to a unix socket instead of Host and Port, which are then unused. See Forwarding to a unix socket.

Encryption sits below the transport. SSL/TLS covers the modes and the certificate fields.

Options

Field	Description
Startup Commands	SQL to run after every connect. See Startup commands
Pre-Connect Script	Shell script run before connecting. A non-zero exit aborts the connect
Safe Mode	Confirmation prompts before writes. See Safe Mode
AI Policy	Per-connection override for the in-app AI agents. Never also refuses external clients
AI Rules	Guidance the AI reads on every chat turn for this connection: table conventions, columns to avoid, join hints. See AI Assistant
External Clients	Blocked, Read Only (the default), or Read & Write for MCP clients such as Raycast, Cursor, and Claude Desktop, and for AppleScript. A token’s own scope cannot raise it. See External API
Local only	Keeps this connection off iCloud Sync. See iCloud Sync
Plugin fields	Driver-specific options, such as MongoDB’s replicaSet

A pre-connect script never runs unprompted. A Pre-Connect Script alert shows the script itself and waits for Run Script, every time. At launch it is not prompted for at all: a restored window whose connection carries a script waits with a Connect button.

Appearance

Color marks the connection in the connection list and its window. Tags and Group decide where it sits in the welcome window’s tree.

Startup commands

Statements split on semicolons and newlines and run in order on the connection that just opened, after every connect including an automatic reconnect. They all run on one connection, so write one dialect.

MySQL

SET time_zone = '+00:00';
SET NAMES utf8mb4;

A statement that fails is logged and skipped, and the connection still opens.

Connection health

Every active connection is pinged every 30 seconds, skipping the ping while one of your own queries is running. A failed ping starts a reconnect at 2s, then 4s, 8s, doubling to a 120-second ceiling, and keeps going until the connection comes back or you close it. An authentication failure stops the retries and leaves the session in error. A reconnect rebuilds the tunnel, restores the selected database and schema, and re-runs the startup commands; the session reads as connecting throughout.

SQLite, DuckDB, Beancount, Snowflake, and Teradata are not monitored.

Which drivers get which transports

Database	Default port	SSH tunnel	SSL/TLS	Cloudflare Tunnel	Cloud SQL Proxy	SOCKS Proxy	Tunnel Command
MySQL	3306	Yes	Yes	Yes	Yes	Yes	Yes
MariaDB	3306	Yes	Yes	Yes	No	Yes	Yes
PostgreSQL	5432	Yes	Yes	Yes	Yes	Yes	Yes
Amazon Redshift	5439	Yes	Yes	Yes	No	Yes	Yes
CockroachDB	26257	Yes	Yes	Yes	No	Yes	Yes
PGlite	5432	No	No	No	No	No	No
Microsoft SQL Server	1433	Yes	Yes	Yes	Yes	Yes	Yes
Oracle	1521	Yes	Yes	Yes	No	Yes	Yes
Dameng DM8	5236	Yes	No	Yes	No	Yes	Yes
ClickHouse	8123	Yes	Yes	Yes	No	Yes	Yes
Teradata	1025	Yes	Yes	Yes	No	Yes	Yes
Trino	8080	Yes	Yes	Yes	No	Yes	Yes
MongoDB	27017	Yes	Yes	Yes	No	Yes	Yes
Redis	6379	Yes	Yes	Yes	No	Yes	Yes
Cassandra / ScyllaDB	9042	Yes	Yes	Yes	No	Yes	Yes
etcd	2379	Yes	Yes	Yes	No	Yes	Yes
SurrealDB	8000	Yes	Yes	Yes	No	Yes	Yes
Elasticsearch	9200	No	Yes	No	No	No	No
Typesense	8108	No	Yes	No	No	No	No
Snowflake	443	No	No	No	No	No	No
SQLite	File	No	No	No	No	No	No
DuckDB	File	No	No	No	No	No	No
Beancount	File	No	No	No	No	No	No
DynamoDB	AWS API	No	No	No	No	No	No
BigQuery	Cloud API	No	No	No	No	No	No
Cloudflare D1	Cloud API	No	No	No	No	No	No
libSQL / Turso	URL	No	No	No	No	No	No

SQLite is the one driver offering Remote Database File; it reaches an SSH server without forwarding a port. A driver with no SSL/TLS column is either a local file or an HTTPS API that manages its own encryption. SSL/TLS has the per-driver defaults.