URL Scheme

Every tablepro:// deep link action with parameters and examples

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.