Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.tablepro.app/llms.txt

Use this file to discover all available pages before exploring further.

​
Managing Connections

​
Supported Databases

Natively supported:

MySQL

Full support including MySQL 5.7+ and MySQL 8.0+. Default port: 3306

MariaDB

Compatible with MariaDB 10.x and later. Default port: 3306

PostgreSQL

PostgreSQL 12+ with full feature support. Default port: 5432

Amazon Redshift

Redshift data warehouses via PostgreSQL wire protocol. Default port: 5439

SQLite

File-based databases, no server required

MongoDB

MongoDB 4.4+ with MQL shell queries. Default port: 27017

Redis

Redis 6.0+ with key-value browsing and CLI. Default port: 6379

Microsoft SQL Server

SQL Server 2017+ via FreeTDS. Default port: 1433

Oracle Database

Oracle 12c+ via Oracle Call Interface. Default port: 1521

ClickHouse

ClickHouse OLAP database via HTTP API. Default port: 8123

Cassandra / ScyllaDB

Cassandra 3.11+ and ScyllaDB 4.0+ via CQL native protocol. Default port: 9042

DuckDB

DuckDB embedded OLAP database. File-based, no server required

DynamoDB

Amazon DynamoDB via AWS SDK. NoSQL key-value and document database

BigQuery

Google BigQuery analytics warehouse via REST API. Service account or OAuth

Etcd

Etcd distributed key-value store via gRPC API. Default port: 2379

Cloudflare D1

Cloudflare D1 serverless SQLite database via Cloudflare API

libSQL / Turso

libSQL open-source SQLite fork. Works with Turso and self-hosted sqld via Hrana protocol

​
Creating a Connection

​
From the Welcome Screen

The Welcome screen appears on first launch or when no connections are active.
  1. Click New Connection
  2. Pick a database type from the chooser sheet
  3. Fill in connection details in the form
  4. Click Test Connection in the General pane
  5. Click Save & Connect in the toolbar
The chooser sheet groups drivers by category (Relational, Document, Key-Value, Analytical, Wide-Column, Cloud Native, Coordination). Each row shows the driver icon, name, and a one-line description. Use the search field to filter, or just click and Continue. Drivers that aren’t installed yet show a “Not Installed” badge; selecting one prompts to install before the form opens.
Welcome screen
Database type chooser

​
From the Menu Bar

Create a new connection at any time:
  • File > New Connection (Cmd+N)

​
From a Connection URL

Paste a connection string and let TablePro fill in the form:
  1. Click New Connection on the welcome screen
  2. In the chooser sheet footer, click Import from URL…
  3. Paste your URL. The sheet detects the database type and previews host, user, and database
  4. Click Import. The form opens with everything pre-filled
  5. Review and click Save & Connect
Import from URL
See Connection URL Reference for all supported schemes and formats.
Special characters in passwords (@, #, %) need percent-encoding. p@ssword becomes p%40ssword.

​
Connect Directly from a URL

Open a database URL from your browser or terminal. TablePro connects immediately, no form required. From a browser: paste the URL into your address bar and press Enter. From the terminal: 
open "postgresql://user:pass@host:5432/dbname"
open "mysql://root:secret@localhost:3306/myapp"
open "redis://:password@localhost:6379"
TablePro registers postgresql, postgres, mysql, mariadb, sqlite, mongodb, mongodb+srv, redis, rediss, redshift, mssql, sqlserver, oracle, clickhouse, cassandra, and scylladb as URL schemes on macOS, so the OS routes these URLs directly to the app. What happens:
  • If a saved connection already matches the host, port, database, and username, TablePro reuses it
  • Otherwise, a temporary session is created. Nothing is saved to your connection list
  • The password from the URL is stored in Keychain for the duration of the session
You can also target a specific table, schema, or apply a filter via query parameters. See Connection URL Reference for all supported query parameters.
This is different from Import from URL…, which opens the form so you can review and save. Direct URL opening skips the form entirely.

​
Connection Form Layout

The form is a sidebar with five panes. Drivers without networking (SQLite, DuckDB) hide the SSH and SSL panes.
PaneContents
GeneralName, host/port/database, username, password, Test Connection
SSH TunnelReach databases behind a bastion host
SSL/TLSEncryption mode and certificates
CustomizationColor, tag, group, Safe Mode
AdvancedStartup commands, pre-connect script, external access, plugin-specific fields
A red triangle on a sidebar item marks panes with missing required fields.
Connection form

​
General

FieldDescription
NameA friendly name shown in the connection list
HostServer address. Defaults to localhost
PortServer port. Pre-filled per database type
DatabaseDefault database. Optional for MySQL/MariaDB; leave empty for service-level access
UsernameDatabase username. Defaults to root (MySQL), postgres (PostgreSQL)
PasswordStored in Keychain
Prompt for passwordSkip saving the password. TablePro asks for it on every connect
Use Password FilePostgreSQL only. Reads credentials from ~/.pgpass
StatusTest Connection button. Turns into a green “Connected” pill on success
For SQLite and DuckDB, the host/port/database section is replaced with a file browser:
FieldDescription
File PathPath to the database file

​
SSL/TLS

Available for network drivers that support encryption (MySQL, MariaDB, PostgreSQL, ClickHouse, MongoDB, etc.).
FieldDescription
SSL ModeEncryption level (see table below)
CA CertificateCA file for Verify CA / Verify Identity
Client CertificateClient cert. Required only for mutual TLS
Client KeyClient private key. Required only for mutual TLS
SSL modes:
ModeDescription
DisabledNo encryption
PreferredUse SSL if the server supports it, otherwise fall back
RequiredRequire SSL but don’t verify certificates
Verify CARequire SSL and verify the server cert against a CA
Verify IdentityRequire SSL, verify CA, and verify the hostname matches
For production, use Verify CA or Verify Identity. Required gives you encryption without certificate files for quick dev setups.
SSL/TLS pane

​
Customization

FieldDescription
ColorTints the toolbar when connected. Useful for spotting prod vs. dev
TagA label that groups connections in the sidebar
GroupFolder for organizing connections. Supports nesting up to 3 levels
Safe ModePer-connection query gate. See Safe Mode
Red for production, green for development. Set Safe Mode to Read Only on production to block accidental writes.
Customization pane

​
Advanced

Open the Advanced pane for less common settings:
FieldDescription
Startup CommandsSQL that runs after every connect. See Startup Commands
Pre-Connect ScriptShell script run before connecting. A non-zero exit aborts
AI PolicyPer-connection override for in-app AI agents
External ClientsControls Raycast, Cursor, Claude Desktop, and other MCP clients: Blocked, Read Only (default), or Read & Write. Tokens can never exceed this level. See External API
Local onlyExcludes this connection from iCloud Sync. See iCloud Sync
Plugin fieldsDriver-specific options like MongoDB replicaSet, ClickHouse Secure

​
Organizing Connections

Colors tint the toolbar when you connect (red for production, green for development). Tags group connections in the sidebar. Create connection groups by right-clicking in the connection list or using the folder icon. Groups collapse/expand with native macOS disclosure triangles and persist between sessions.

​
Nested Groups

Groups support up to 3 levels of nesting. Right-click a group to create a subgroup, move it under another group, or delete it. Deleting a parent removes all subgroups. Connections inside are ungrouped, not deleted. The connection form shows the full hierarchy when picking a group.
Color picker

​
Quick Connection Switching

Switch connections from the toolbar:
  1. Click the connection name button in the toolbar
  2. A popover shows your active sessions and saved connections
  3. Click any connection to switch immediately
  4. Click Manage Connections… to open the full connection manager
Click the connection button again to dismiss the popover.

​
Switching Databases

One connection covers every database on the server. Switch with Cmd+K, or click the database name in the toolbar.

​
Service-level connections

Leave the Database field empty when creating the connection. Works for MySQL, MariaDB, MongoDB, SQL Server, and ClickHouse. The sidebar lists every database your user can access. PostgreSQL and Redshift need an initial database. Connect to postgres (Redshift: dev), then use Cmd+K to switch.
With a restricted user, the switcher only shows databases that user has been granted access to.
Database switcher in toolbar

​
Dock Menu Quick Connect

Right-click the TablePro icon in the Dock and select a saved connection under Open Connection. If it fails, you’ll fall back to the Welcome screen.

​
Creating Databases

To create a new database:
  1. Right-click on the connection in the sidebar
  2. Select Create Database
  3. Enter the database name
  4. Choose charset and collation (MySQL/MariaDB)
  5. Click Create
Database creation requires appropriate user privileges on the server.

​
Testing Connections

Before saving a connection, test it:
  1. Fill in all required connection details
  2. Click Test Connection
  3. Wait for the result:
    • Green checkmark: Connection successful
    • Red X: Connection failed (see error message)
Connection test
Most test failures are due to the server being down, wrong credentials, or network/firewall blocking the port. Verify the host is reachable and credentials are correct before contacting support.

​
Connection Health Monitoring

TablePro monitors active connections and auto-recovers from drops.

​
Automatic Health Checks

For MySQL, MariaDB, and PostgreSQL, TablePro pings (SELECT 1) every 30 seconds. SQLite is file-based and skips health checks.

​
Auto-Reconnect

When a connection drops, TablePro reconnects with exponential backoff:
  1. Attempt 1: waits 2 seconds, then reconnects
  2. Attempt 2: waits 4 seconds, then reconnects
  3. Attempt 3: waits 8 seconds, then reconnects
After three failures, the connection enters an error state. A Reconnect button appears in the toolbar. SSH tunnels have independent monitoring and are re-established automatically if the tunnel process dies.

​
Manual Reconnect

Click the Reconnect button in the toolbar to retry manually. For SSH connections, this also recreates the tunnel.
The toolbar status indicator shows connection state: green for connected, orange for reconnecting, red for error/disconnected.
SQLite connections are file-based and don’t require health monitoring or auto-reconnect.
Connection health status

​
Startup Commands

SQL statements that run automatically on every connection. Configure startup commands in the Advanced pane of the connection form. Enter one SQL statement per line.

​
Common Examples

SET time_zone = '+00:00';
SET NAMES utf8mb4;
SET sql_mode = 'STRICT_TRANS_TABLES';
SET search_path TO myschema, public;
SET statement_timeout = '30s';
Startup commands execute in order, top to bottom. If a command fails, the connection still proceeds, but the failed command is skipped.
Set a timezone here to ensure datetime results are consistent across team members, regardless of server defaults.
Startup commands run on every connection, including auto-reconnects.

​
Editing and Deleting Connections

Right-click a connection to edit or delete it. Changes take effect on the next connection. Deleting removes the saved settings only.

​
Backup and Restore

Connections are stored in ~/Library/Preferences/com.TablePro.plist. Passwords are in the macOS Keychain. Copy the .plist file to back up. You’ll need to re-enter passwords after restoring since Keychain entries don’t transfer.