> ## Documentation Index > Fetch the complete documentation index at: https://ngquct-feat-ai-sql-walkthroughs.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # 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](/external-api/mcp-tools). ## 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`](/external-api/mcp-tools) tool or read the [`tablepro://connections`](/external-api/mcp-resources) 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//...` 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/ ``` 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. ```bash theme={null} open "tablepro://connect/9f1f0c3e-2e3d-4b14-9c3a-1d2f4ad1f6f1" ``` ## Open a table ``` tablepro://connect//table/ tablepro://connect//database//table/ tablepro://connect//database//schema//table/ ``` 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. ```bash theme={null} # 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//query?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`](/external-api/mcp-tools) tool instead. The URL scheme is for handing SQL into the GUI, not for headless execution. ```bash theme={null} 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=&challenge=&redirect=&scopes=&connection-ids= ``` 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: ```ts theme={null} 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](/external-api/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. ```bash theme={null} open "tablepro://integrations/start-mcp" ``` ## Import a connection ``` tablepro://import?name=&host=&port=

&type=&username=&database= ``` 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`. ```bash theme={null} 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**.