Managing Connections

TablePro connects to 23 databases through its plugin system. This page covers creating and organizing connections. Driver-specific fields and quirks live on each database’s own page.

Supported Databases

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

Transport details: SSH Tunneling, SSL/TLS, Cloudflare Tunnel, Cloud SQL Auth Proxy, SOCKS Proxy.

Creating a Connection

The Welcome window appears on launch. The left panel has Create Connection, Import from Other App, and Try Sample Database; saved connections are on the right, with a search field in the header (Cmd+F focuses it).

Welcome window with actions panel and connection list — Welcome window

Click Create Connection (or press Cmd+N anywhere)
Pick a database type from the chooser sheet
Fill in connection details
Click Test Connection. A green Connected pill confirms success
Click Save & Connect

The chooser groups drivers by category: Relational, Document, Key-Value, Analytical, Wide-Column, Cloud Native, Coordination & Config, and Other. Drivers that aren’t installed show a Not Installed badge; selecting one prompts to install the plugin first. See Plugins.

Import from URL

Paste a connection string and let TablePro fill in the form. In the chooser sheet footer, click Import from URL…, paste the URL, review the parsed preview, and click Import. The form opens pre-filled so you can review and save. See Connection URL Reference for schemes and formats.

Special characters in passwords (@, #, %) need percent-encoding. p@ssword becomes p%40ssword.

Open a URL Directly

Opening a database URL from a browser or terminal skips the form:

open "postgresql://user:pass@host:5432/dbname"

TablePro registers these URL schemes with macOS: postgresql, postgres, mysql, mariadb, sqlite, mongodb, mongodb+srv, redis, rediss, redshift, cockroachdb, cockroach, mssql, sqlserver, oracle, clickhouse, ch, cassandra, cql, scylladb, scylla, duckdb, etcd, etcds, d1, libsql, and surrealdb. What happens on open:

A confirmation alert shows the connection target before anything connects. For loopback hosts you can pick Always Allow, which trusts that exact combination of type, host, database, username, and the URL’s name parameter for future opens
If a saved connection matches the host, port, database, and username, TablePro reuses it. Otherwise it creates a temporary session that is not added to your connection list
The URL password stays in memory for the session. It is never written to the Keychain
If the connection has a pre-connect script, TablePro shows the script and asks before running it
URLs can target a table or apply a filter via query parameters; filters also require confirmation. See Connection URL Reference

Connection Form

The form is a sidebar with up to nine panes. Tunnel and SSL panes appear only for drivers that support them (see the matrix above). A warning triangle on a sidebar item marks missing required fields.

Pane	Contents
General	Name, host, port, database, credentials, Test Connection
SSH Tunnel	Reach databases behind a bastion host. See SSH Tunneling
Cloudflare Tunnel	Connect through `cloudflared`. See Cloudflare Tunnel
Cloud SQL Auth Proxy	Google Cloud SQL proxy for MySQL, PostgreSQL, SQL Server. See Cloud SQL Auth Proxy
SOCKS Proxy	Route the connection through a SOCKS5 proxy. See SOCKS Proxy
SSL/TLS	Encryption mode and certificates. See SSL/TLS
Customization	Color, tags, group, Safe Mode
Advanced	Startup commands, pre-connect script, external access, plugin-specific fields
AI Rules	Per-connection guidance the AI assistant sees on every chat turn. See AI Assistant

General

Field	Description
Name	Display name in the connection list
Host	Server address. Defaults to `localhost`
Port	Pre-filled per database type
Database	Default database. Optional for service-level access
Username	Optional and not pre-filled. Empty means the driver’s own default
Password	Stored in the macOS Keychain
Prompt for password	Skip saving. TablePro asks on every connect
Use Password File	PostgreSQL, Redshift, and CockroachDB. Reads credentials from `~/.pgpass`

File-based drivers (SQLite, DuckDB, Beancount) replace the host section with a file path picker.

Advanced

Field	Description
Startup Commands	SQL that runs after every connect. See Startup Commands
Pre-Connect Script	Shell script run before connecting. A non-zero exit aborts
AI Policy	Per-connection override for in-app AI agents
External Clients	Access level for MCP clients: Blocked, Read Only (default), or Read & Write. See External API
Local only	Excludes this connection from iCloud Sync. See iCloud Sync
Plugin fields	Driver-specific options like MongoDB `replicaSet`

Organizing Connections

The Customization pane sets a color, tags, and a group per connection. The color tints the toolbar when connected, so production and development are easy to tell apart.

Red for production, green for development. Set Safe Mode to Read Only on production to block accidental writes. See Safe Mode.

Groups

Groups are folders in the connection list, nested up to 3 levels. Right-click empty space or a group to create, move, or delete one. Deleting a group removes its subgroups; the connections inside are ungrouped, not deleted.

Favorites

Hover a connection row and click the star, or right-click and choose Add to Favorites. Favorites gather in a section at the top of the list, sorted alphabetically, while the connection stays in its group below. Favorites sync through iCloud unless the connection is marked local only.

Switching Connections and Databases

Switch Connection (Cmd+Control+C): a toolbar popover lists active sessions and saved connections. Type to filter, arrow keys to move, Return to switch
Open Database (Cmd+K): switch databases on the same server without reconnecting

Leave the Database field empty when creating a connection to browse every database your user can access (MySQL, MariaDB, MongoDB, SQL Server, ClickHouse). PostgreSQL and Redshift need an initial database; connect to postgres (Redshift: dev) and switch with Cmd+K. When the sidebar is in tree layout, the filter button in the sidebar footer limits the tree to checked databases. The choice is saved per connection. Right-click the TablePro Dock icon and pick a saved connection under Open Connection.

Connection Health Monitoring

TablePro pings every active connection every 30 seconds and skips the ping while one of your queries is running. File-based drivers (SQLite, DuckDB, Beancount) and Snowflake are not monitored. When a ping fails, TablePro reconnects with exponential backoff: 2s, 4s, 8s, doubling up to a 120-second cap, and keeps retrying until the connection recovers or you close it. Authentication failures stop the retries, since an expired credential never recovers on its own. Reconnecting rebuilds the SSH tunnel if there is one, restores the selected database and schema, and re-runs startup commands. The session shows as connecting while this happens.

Startup Commands

SQL statements that run after every connect, including auto-reconnects. Configure them in the Advanced pane; statements are split on semicolons and newlines and run in order.

SET time_zone = '+00:00';
SET NAMES utf8mb4;
SET search_path TO myschema, public;

A failed statement is logged and skipped; the connection still opens.

Editing, Deleting, and Storage

Right-click a connection to edit or delete it. Changes apply on the next connect; deleting removes the saved settings only. Connections are stored in ~/Library/Application Support/TablePro/connections.json. Passwords live in the macOS Keychain, so a copied file restores connections but not passwords.

Getting Started

Database Connections

Features

Customization

External API

Managing Connections

Managing Connections

Supported Databases