URL Scheme

The tablepro:// URL scheme drives the TablePro GUI from outside the app. Use it from the shell with open, from another app with NSWorkspace.shared.open(url:), or from a Raycast extension with open() from @raycast/api. The scheme covers two kinds of actions:

Navigate: open a connection, table, or query tab.
Pair: bootstrap an MCP token for an extension.

Data exchange is not part of the URL scheme. For that, use MCP.

Connection IDs are UUIDs

Connection paths use the connection’s UUID, not its display name.

tablepro://connect/9f1f0c3e-2e3d-4b14-9c3a-1d2f4ad1f6f1

There is no UI action that copies a connect link. To find a connection’s UUID, call the MCP list_connections tool or read the tablepro://connections resource; both return the UUID for each saved connection. The welcome screen’s Copy TablePro Link context menu item copies a tablepro://import?... link for sharing the connection, not a connect link.

Pre-0.38 builds accepted tablepro://connect/<name>/... paths. Name-based paths were removed in 0.38.0. Bookmarks built against older versions must be regenerated with UUID-keyed paths.

Open a connection

tablepro://connect/<connection-uuid>

Opens the saved connection. If the connection is already open in a window, that window comes to front. If the UUID does not match a saved connection, an error sheet appears. If the connection has a pre-connect script, TablePro shows the script text in a confirmation dialog before connecting. Cancelling the dialog cancels the whole deep link. This applies to every connect/... link: connection, table, and query.

open "tablepro://connect/9f1f0c3e-2e3d-4b14-9c3a-1d2f4ad1f6f1"

Open a table

tablepro://connect/<connection-uuid>/table/<table-name>
tablepro://connect/<connection-uuid>/database/<db>/table/<table-name>
tablepro://connect/<connection-uuid>/database/<db>/schema/<schema>/table/<table-name>

The first form opens the table in the connection’s current database and schema. The second selects a database first. The third (Postgres-style) selects both. Table and schema names with spaces or special characters must be percent-encoded.

# Open a table in the current database
open "tablepro://connect/9f1f0c3e-2e3d-4b14-9c3a-1d2f4ad1f6f1/table/users"

# Open a table in a specific database
open "tablepro://connect/9f1f0c3e-2e3d-4b14-9c3a-1d2f4ad1f6f1/database/analytics/table/events"

# Postgres: select database and schema
open "tablepro://connect/9f1f0c3e-2e3d-4b14-9c3a-1d2f4ad1f6f1/database/app/schema/reporting/table/daily_events"

Run a query

tablepro://connect/<connection-uuid>/query?sql=<percent-encoded-sql>

Opens a new query tab with the SQL pre-filled. TablePro always shows a confirmation dialog first, previewing the first 300 characters of the SQL. The query does not auto-execute; the user runs it from the editor. The SQL has a 51,200-character cap. To run SQL from a script and read rows back, use the MCP execute_query tool instead. The URL scheme is for handing SQL into the GUI, not for headless execution.

open "tablepro://connect/9f1f0c3e-2e3d-4b14-9c3a-1d2f4ad1f6f1/query?sql=SELECT%20*%20FROM%20users%20LIMIT%2010"

Parameter	Required	Description
`sql`	yes	Percent-encoded SQL. Max 51,200 characters.

Start pairing

tablepro://integrations/pair?client=<name>&challenge=<base64url>&redirect=<url>&scopes=<scope>&connection-ids=<csv>

Starts a pairing flow. TablePro presents an approval sheet, the user picks scopes and connections, and TablePro returns a one-time code via the redirect URL.

Parameter	Required	Description
`client`	yes	Display name shown in the approval sheet, e.g. `Raycast on macbook-pro`.
`challenge`	yes	Base64url-encoded SHA-256 hash of the verifier (PKCE).
`redirect`	yes	URL to receive the `code` query parameter on success.
`scopes`	no	Requested scope, a single value: `readWrite` or `fullAccess`. Matching is case-insensitive and accepts `read_write`, `read-write`, `full_access`, `full-access`, and `full`. Any other value, or omitting the parameter, requests `readOnly`.
`connection-ids`	no	Comma-separated UUIDs to preselect in the allowlist. Defaults to all.

The user can change scopes and connections in the approval sheet. The query parameters are a request, not a grant. Example invocation from a Raycast extension:

import { open } from "@raycast/api";

const params = new URLSearchParams({
  client: "Raycast on macbook-pro",
  challenge: challengeB64Url,
  redirect: "raycast://extensions/ngoquocdat/tablepro/pair-callback",
  scopes: "readWrite",
});
await open(`tablepro://integrations/pair?${params}`);

See Pairing for the full sequence and the exchange step.

Lazy-start the MCP server

tablepro://integrations/start-mcp

Starts the MCP server if it is not already running, then returns. Used by the bundled tablepro-mcp CLI to bootstrap on cold launch. The user does not need to enable MCP in Settings beforehand. The server binds to the configured port (default 23508); if that port is taken, it falls back to a free port in the 51000-52000 range. Either way it writes a handshake file at ~/Library/Application Support/TablePro/mcp-handshake.json with the actual port.

open "tablepro://integrations/start-mcp"

Import a connection

tablepro://import?name=<n>&host=<h>&port=<p>&type=<t>&username=<u>&database=<db>

Adds a saved connection from query parameters. TablePro shows a review sheet with the parsed details before saving anything; the name is editable, everything else is read-only. Add Connection saves it, or Add as Copy when a connection with the same name, host, and type already exists. Passwords are never accepted in the URL; the user adds one in the connection editor before connecting. Required parameters: name, host, type. type accepts any registered database type name (case-insensitive). Examples: MySQL, PostgreSQL, MongoDB, Redis, ClickHouse, Oracle, DuckDB, Cassandra.

open "tablepro://import?name=Staging&host=db.example.com&port=5432&type=postgresql&username=admin&database=mydb"

Enum-valued parameters below must match the listed values exactly (they are raw values, not display names). Percent-encode values with spaces: sslMode=Verify%20CA.

Core parameters

Parameter	Description
`port`	Server port. Defaults to the database type’s standard port.
`username`	Database username.
`database`	Default database name.
`color`	Sidebar color: `Red`, `Orange`, `Yellow`, `Green`, `Blue`, `Purple`, `Pink`, or `Gray`.
`tagName`	Tag to assign. Repeat the parameter to assign more than one tag.
`groupName`	Group to place the connection in.
`safeModeLevel`	Safe Mode level: `silent`, `alert`, `alertFull`, `safeMode`, `safeModeFull`, or `readOnly`.
`aiPolicy`	AI access policy: `alwaysAllow`, `askEachTime`, or `never`. Any other value falls back to the app default.
`redisDatabase`	Redis database index to select on connect.
`startupCommands`	Statements to run after connecting.
`localOnly`	Set to `1` to exclude the connection from sync.

SSH parameters

Set ssh=1 to enable SSH tunneling.

Parameter	Description
`sshHost`	SSH server hostname.
`sshPort`	SSH port. Default `22`.
`sshUsername`	SSH username.
`sshAuthMethod`	`Password`, `Private Key`, `SSH Agent`, or `Keyboard Interactive`. Unrecognized values fall back to `Password`.
`sshPrivateKeyPath`	Path to private key file.
`sshAgentSocketPath`	Custom SSH agent socket path.
`sshJumpHosts`	JSON array of jump hosts.
`sshTotpMode`	TOTP mode for two-factor SSH auth: `none`, `auto_generate`, or `prompt_at_connect`.
`sshTotpAlgorithm`	TOTP hash algorithm: `SHA1`, `SHA256`, or `SHA512`. Default `SHA1`.
`sshTotpDigits`	TOTP code length. Default `6`.
`sshTotpPeriod`	TOTP period in seconds. Default `30`.

SSL parameters

Parameter	Description
`sslMode`	`Disabled`, `Preferred`, `Required`, `Verify CA`, or `Verify Identity`. Unrecognized values fall back to `Disabled`.
`sslCaCertPath`	CA certificate file path.
`sslClientCertPath`	Client certificate file path.
`sslClientKeyPath`	Client key file path.

Plugin-specific fields

Use the af_ prefix to pass driver-specific fields. For example, af_replicaSet=myrs passes replicaSet to the MongoDB plugin. af_preConnectScript is stripped on import. Imported connections cannot carry a pre-connect shell script; the user has to add one by hand in the connection editor.

Errors

Malformed URLs are dropped without any UI: an invalid UUID, unknown path, missing required parameter, or over-limit SQL is logged to the system log (subsystem com.TablePro) and nothing opens. Check Console.app when a link does nothing. Failures after parsing show an error sheet. Example: a valid UUID with no matching connection shows No saved connection with ID "9F1F0C3E-2E3D-4B14-9C3A-1D2F4AD1F6F1". under the title Connection Failed.

Getting Started

Database Connections

Features

Customization

External API

URL Scheme

URL Scheme

Connection IDs are UUIDs

Open a connection

Open a table

Run a query

Start pairing

Lazy-start the MCP server

Import a connection

Core parameters

SSH parameters

SSL parameters

Plugin-specific fields

Errors

​URL Scheme

​Connection IDs are UUIDs

​Open a connection

​Open a table

​Run a query

​Start pairing

​Lazy-start the MCP server

​Import a connection

​Core parameters

​SSH parameters

​SSL parameters

​Plugin-specific fields

​Errors

URL Scheme

Connection IDs are UUIDs

Open a connection

Open a table

Run a query

Start pairing

Lazy-start the MCP server

Import a connection

Core parameters

SSH parameters

SSL parameters

Plugin-specific fields

Errors