Connection URL Reference

TablePro parses standard database connection URLs for importing connections, opening them directly from a browser or terminal, and configuring SSH tunnels.

URL Schemes

Scheme	Database
`postgresql://`	PostgreSQL
`postgres://`	PostgreSQL (alias)
`mysql://`	MySQL
`mariadb://`	MariaDB
`sqlite://`	SQLite
`mongodb://`	MongoDB
`mongodb+srv://`	MongoDB (SRV)
`redis://`	Redis
`rediss://`	Redis with TLS
`redshift://`	Amazon Redshift
`cockroachdb://`	CockroachDB
`cockroach://`	CockroachDB (alias)
`mssql://`	Microsoft SQL Server
`sqlserver://`	Microsoft SQL Server (alias)
`jdbc:sqlserver://`	Microsoft SQL Server (JDBC)
`oracle://`	Oracle Database
`jdbc:oracle:thin://`	Oracle Database (JDBC thin)
`cassandra://`	Cassandra
`cql://`	Cassandra (alias)
`scylladb://`	ScyllaDB
`scylla://`	ScyllaDB (alias)
`clickhouse://`	ClickHouse
`ch://`	ClickHouse (alias)
`duckdb://`	DuckDB
`etcd://`	etcd
`etcds://`	etcd with TLS
`d1://`	Cloudflare D1
`libsql://`	libSQL / Turso
`surrealdb://`	SurrealDB

Append +ssh to any scheme (except SQLite) to use an SSH tunnel:

postgresql+ssh://
mysql+ssh://
mariadb+ssh://

Standard Format

scheme://[username[:password]@]host[:port][/database][?param=value&...]

Examples:

postgresql://alice:secret@db.example.com:5432/myapp
mysql://root@localhost/shop
mongodb://user:pass@mongo.host:27017/analytics?authSource=admin
redis://:password@cache.host:6379/1
sqlite:///Users/alice/data/local.db

Passwords containing special characters (@, #, %, :) must be percent-encoded. For example, p@ss#word becomes p%40ss%23word.

SSH Tunnel Format

SSH tunnel URLs encode both SSH and database credentials in a single string:

scheme+ssh://[ssh_user@]ssh_host[:ssh_port]/[db_user[:db_pass]@]db_host[:db_port][/database][?params]

Examples:

postgresql+ssh://deploy@bastion.host:22/dbuser:dbpass@internal-pg:5432/mydb
mysql+ssh://ec2-user@jump.host/root:secret@10.0.0.5/shop
mariadb+ssh://admin@ssh.host/maria_user@db.internal/store?usePrivateKey=true

If db_host is omitted, it defaults to 127.0.0.1.

Query Parameters

Connection

Parameter	Description	Example
`name`	Override the connection name shown in the sidebar	`?name=Production+DB`
`safeModeLevel`	Set Safe Mode for the connection: 0=silent, 1=alert, 2=read-only	`?safeModeLevel=2`

SSL / TLS

Parameter	Values	Description
`sslmode`	`disable`, `prefer`, `require`, `verify-ca`, `verify-full`	SSL mode (standard PostgreSQL names)
`tlsmode`	`0`-`4`	SSL mode as integer: 0=disable, 1=prefer, 2=require, 3=verify-ca, 4=verify-full
`tls` / `ssl`	`true`	Sets SSL mode to Required

Example:

postgresql://user:pass@host/db?sslmode=require
postgresql://user:pass@host/db?tlsmode=2

These parameters open a specific table, view, or schema immediately after connecting.

Parameter	Description	Example
`table`	Open the named table	`?table=users`
`view`	Open the named view	`?view=active_orders`
`schema`	Switch to this schema before opening	`?schema=reporting`

On databases that support schema switching (PostgreSQL, Redshift, SQL Server, Oracle), schema switches the schema. On databases that don’t, the value is treated as a database name and switches the database instead. Example:

postgresql://user:pass@host/mydb?schema=reporting&table=monthly_sales

Filtering

Apply a filter to the opened table automatically.

Parameter	Description	Example
`column`	Column name to filter on	`?column=status`
`operation`	Filter operator (e.g. `=`, `!=`, `LIKE`)	`?operation=LIKE`
`value`	Filter value	`?value=active`
`condition`	Raw SQL WHERE condition (overrides column/operation/value)	`?condition=status%3D'active'+AND+role%3D'admin'`

operator is accepted as an alias for operation. raw and query are accepted as aliases for condition. Example:

postgresql://user:pass@host/mydb?table=orders&column=status&operation==&value=pending
postgresql://user:pass@host/mydb?table=orders&condition=total%3E1000

Appearance

Parameter	Description	Example
`statusColor`	Assign a color to the connection (hex, matched to nearest palette color)	`?statusColor=FF3B30`
`env`	Assign an existing tag by name (`environment` also accepted)	`?env=production`

Example:

postgresql://user:pass@host/db?statusColor=FF3B30&env=production

MongoDB

Parameter	Description
`authSource`	Authentication database (defaults to `admin`)
`authMechanism`	Authentication mechanism (e.g. `SCRAM-SHA-256`)
`replicaSet`	Replica set name

Any other query parameter on a MongoDB URL passes through to the driver unchanged. Multi-host URIs with comma-separated hosts are supported. Example:

mongodb://user:pass@host:27017/mydb?authSource=admin
mongodb://user:pass@host1:27017,host2:27017,host3:27017/mydb?replicaSet=rs0

Redis

The path component sets the database index (0-15). The rediss:// scheme automatically enables TLS.

redis://:password@host:6379/2       # database index 2
rediss://:password@host:6380        # TLS, default index 0

Cassandra / ScyllaDB

The path component sets the default keyspace. Both cassandra:// and scylladb:// schemes use the same format.

cassandra://user:pass@host:9042/my_keyspace
scylladb://user:pass@host:9042/my_keyspace
cassandra://host:9042                        # no auth, no default keyspace

DuckDB

DuckDB uses file-based connections. The path after :// is the file path, same as SQLite.

duckdb:///Users/me/data/analytics.duckdb
duckdb:///path/to/database.db

ClickHouse

ClickHouse uses HTTP on port 8123 by default. ch:// is accepted as an alias.

clickhouse://user:password@host:8123/mydb
ch://default@localhost/analytics

etcd

The etcds:// scheme automatically enables TLS. Default port is 2379.

etcd://host:2379
etcds://host:2379

libSQL / Turso

The URL host maps to the database URL. The auth token goes in the password field of the connection form.

libsql://your-database.turso.io

Cloudflare D1

The host maps to the Cloudflare Account ID. The path sets the database name or UUID.

d1://account-id/database-name

SSH Tunnel

Parameter	Description
`usePrivateKey`	`true` to use key-based SSH authentication instead of password
`useSSHAgent`	`true` to use SSH agent for authentication
`agentSocket`	Custom SSH agent socket path

Example:

postgresql+ssh://ubuntu@bastion/dbuser@10.0.0.5/mydb?usePrivateKey=true

Opening URLs from Browser or Terminal

Launch and connect from a browser or terminal:

open "postgresql://user:pass@localhost:5432/mydb"
open "mysql://root@localhost/shop?table=products"

Uses a saved connection if it matches, otherwise creates a temporary session. To save permanently, click New Connection on the welcome screen and pick Import from URL… in the chooser footer.

Import from URL sheet with a pasted connection URL — The Import from URL sheet accepts every scheme in this reference

+ssh schemes are not registered with macOS, so open and browser links cannot route them to TablePro. Use the Import from URL… sheet for SSH tunnel URLs.

To force TablePro when another client also handles the scheme, use open -b com.TablePro "mysql://...". See Terminal and DDEV for the tablepro command and a ddev tablepro host command.

Confirmation and Trusted Links

Every URL opened from outside the app shows a confirmation alert with the database type, host, user, and database before TablePro connects. Connect only if you trust the source of the link. For connections to this machine (localhost, 127.x.x.x, ::1) the alert also offers Always Allow. A trusted link is matched by database type, host, database, username, and the URL’s name parameter, never the port. Only loopback hosts can be trusted; remote hosts always prompt. Review trusted links under Settings > General > Trusted Links, where you can forget them one at a time or all at once.

Getting Started

Database Connections

Features

Customization

External API

Connection URL Reference

Connection URL Reference

URL Schemes

Standard Format

SSH Tunnel Format

Query Parameters

Connection

SSL / TLS

Navigation

Filtering

Appearance

MongoDB

Redis

Cassandra / ScyllaDB

DuckDB

ClickHouse

etcd

libSQL / Turso

Cloudflare D1

SSH Tunnel

Opening URLs from Browser or Terminal

Confirmation and Trusted Links

​Connection URL Reference

​URL Schemes

​Standard Format

​SSH Tunnel Format

​Query Parameters

​Connection

​SSL / TLS

​Navigation

​Filtering

​Appearance

​MongoDB

​Redis

​Cassandra / ScyllaDB

​DuckDB

​ClickHouse

​etcd

​libSQL / Turso

​Cloudflare D1

​SSH Tunnel

​Opening URLs from Browser or Terminal

​Confirmation and Trusted Links

Connection URL Reference

URL Schemes

Standard Format

SSH Tunnel Format

Query Parameters

Connection

SSL / TLS

Navigation

Filtering

Appearance

MongoDB

Redis

Cassandra / ScyllaDB

DuckDB

ClickHouse

etcd

libSQL / Turso

Cloudflare D1

SSH Tunnel

Opening URLs from Browser or Terminal

Confirmation and Trusted Links