> ## Documentation Index > Fetch the complete documentation index at: https://ngquct-worktree-statusbar-redesign.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 ``` You can copy the URL for any connection from the sidebar context menu: right-click the connection, **Copy Connection Deep Link**. Pre-0.37 builds accepted `tablepro://connect//...` paths. Those paths were removed in 0.37. Bookmarks built against old TablePro versions must be regenerated. Use **Copy Connection Deep Link** to get the new UUID-keyed URL. ## 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 alert appears. ```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 with a preview of the SQL before opening, so the user can verify the query is safe. 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 | Comma-separated requested scopes: `readOnly`, `readWrite`, `fullAccess`. Defaults to `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: "readOnly,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 first call starts the server on a free port in the `51000-52000` range and writes a handshake file at `~/Library/Application Support/TablePro/mcp-handshake.json`. ```bash theme={null} open "tablepro://integrations/start-mcp" ``` ## Import a connection ``` tablepro://import?name=&host=&port=

&type=&username=&database= ``` Creates a saved connection from query parameters and opens the connection editor for review. A confirmation dialog shows the connection details before adding, so you can reject unexpected imports. The user adds a password before connecting; passwords are never accepted in the URL. 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" ``` ### Core parameters | Parameter | Description | | --------------- | ------------------------------------------------------------------------------------------- | | `port` | Server port. Defaults to the database type's standard port. | | `username` | Database username. | | `database` | Default database name. | | `color` | Connection color in the sidebar. | | `tagName` | Tag to assign. | | `groupName` | Group to place the connection in. | | `safeModeLevel` | Safe Mode level: `silent`, `alert`, `alertFull`, `safeMode`, `safeModeFull`, or `readOnly`. | | `aiPolicy` | AI access policy: `useDefault`, `alwaysAllow`, `askEachTime`, or `never`. | ### 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`, `privateKey`, `agent`, or `keyboardInteractive`. | | `sshPrivateKeyPath` | Path to private key file. | | `sshUseSSHConfig` | Set to `1` to read `~/.ssh/config`. | | `sshAgentSocketPath` | Custom SSH agent socket path. | | `sshJumpHosts` | JSON array of jump hosts. | | `sshTotpMode` | TOTP mode for two-factor SSH auth. | ### SSL parameters | Parameter | Description | | ------------------- | ------------------------------------------------------------------- | | `sslMode` | `disabled`, `preferred`, `required`, `verify-ca`, or `verify-full`. | | `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. ## Errors Invalid UUIDs, missing connections, or malformed query parameters surface as error alerts. The error message names the failing field. Examples: * `Connection not found: 9f1f0c3e-2e3d-4b14-9c3a-1d2f4ad1f6f1` * `Invalid connection ID format` * `Missing required parameter: client` URL scheme errors are also written to the activity log under the `admin` category with outcome `error`.