# TablePro for Raycast

URL: https://www.raycast.com/ngoquocdat/tablepro

> Search TablePro database connections, schemas and tables, run SQL queries and search query history, and query databases with AI.

- Install: raycast://extensions/ngoquocdat/tablepro
- Author: [Ngô Quốc Đạt](https://www.raycast.com/ngoquocdat)
- Installs: 141
- Platforms: macOS
- Categories: Developer Tools, AI Extensions
- Updated: 2026-11-17
- Source: https://github.com/raycast/extensions/tree/c4e0f79975a011e16032382f2d1263f712f8b43c/extensions/tablepro/

## Commands

- **Search Connections**: Search and open saved TablePro connections.
- **Open Connection**: Open a connection by name.
- **TablePro Menu Bar**: Show connections in the menu bar.
- **Search Schema**: Search databases and schemas across your connections.
- **Search Tables**: Search tables in a connection.
- **Recent Tabs**: Show recently opened tabs in TablePro.
- **Run Query**: Run a SQL query against a connection.
- **Search Query History**: Search the TablePro query history.
- **Pair with TablePro**: Pair this extension with TablePro to issue an API token.

## AI tools

- **List Connections**: List all saved TablePro database connections with their id, name, type (postgresql, mysql, sqlite, etc.), host, and port. Call this first when the user names a connection so you can pass its id to other tools. Returns an empty list when no connections are saved; throws when the user has not paired the extension with TablePro.
- **List Databases**: List database names on a TablePro connection. Use for engines that group objects under a database (MySQL, PostgreSQL, MS SQL, ClickHouse). Skip for SQLite, Redis, MongoDB.
- **List Schemas**: List schema names in a database. Use for engines that have schemas inside a database (PostgreSQL, MS SQL, Oracle, Redshift). Pass the database for engines that need it; omit for engines that do not separate database and schema.
- **List Tables**: List tables in a connection, optionally scoped to a database or schema. Returns name, schema, database, type (table or view), and approximate row count. Call describe-table next when you need column types.
- **Describe Table**: Return the column list, data types, nullability, primary-key flags, defaults, and comments for a table. Always call this before generating queries against a table you have not seen so the SQL matches the real schema. Do not call to list tables (use list-tables) or to get the CREATE TABLE statement (use get-table-ddl).
- **Get Table DDL**: Return the CREATE TABLE statement for a table, including indexes and constraints when the engine supports it. Use this when the user asks how a table is defined or wants to copy the structure. Do not call for a column-level overview (use describe-table) or to actually create or modify the table (use run-query, which will route through confirmation).
- **Run Query**: Execute a SQL query against a connection and return columns and rows. Only read-only statements (SELECT, SHOW, EXPLAIN, DESCRIBE, and WITH clauses that resolve to SELECT) skip confirmation. Every other statement routes through user confirmation; never bypass it and never claim a mutation succeeded before the tool returns. Result rows are capped at 200 by default; pass rowLimit to lower that. The connection's external-access setting can reject the query as read-only; surface that error verbatim. Do not call this tool to inspect schema (use describe-table or get-table-ddl) or to run plans (use explain-query).
- **Explain Query**: Wrap a query with EXPLAIN and return the execution plan. Use when the user asks why a query is slow or how the database will run it. Plain EXPLAIN does not execute the underlying query; EXPLAIN ANALYZE on MySQL or PostgreSQL does, and the tool routes that case through user confirmation. Do not call to actually fetch rows (use run-query) or for engines without an EXPLAIN equivalent such as Redis.
- **Open Connection in TablePro**: Open the TablePro window for a connection so the user can continue interactively. Prefer this over streaming large result sets in chat when the user wants to inspect, edit, or filter data.
- **Search Query History**: Full-text search the saved TablePro query history. Returns query text, connection id, executed-at timestamp, duration, and row count. Use to find prior work the user is referencing. Do not call to re-run a past query (copy the text into run-query) or to list tables and schemas (use list-tables and list-schemas).
- **Get Connection Status**: Return the live status of a TablePro connection: connected, connecting, disconnected, or error. Includes current database and schema, server version, and the most recent error message when the connection has failed. Use to answer 'is X up?' style questions before suggesting queries.
- **List Recent Tabs**: List the tabs currently open in TablePro across windows: the connection name, tab type (query, table, structure), display title, and the table or database the tab is scoped to. Use to answer 'what was I just working on?' or to point the user at an existing tab instead of opening a new one.

## README

### TablePro

[TablePro](https://tablepro.app) is a native macOS database client. This extension talks to a running TablePro app over a local MCP server, so you can search saved connections, browse schema, and run queries from Raycast and Raycast AI. Database credentials stay in TablePro's Keychain.

#### Setup

1. Install TablePro 0.37.0 or later from [tablepro.app](https://tablepro.app). The External API and pairing flow this extension uses landed in 0.37.
2. Run the **Pair with TablePro** command in Raycast.
3. TablePro shows an approval sheet. Choose the scope (read-only by default), pick which connections this token can reach, and approve.
4. The token lands back in Raycast automatically. You're done.

The MCP server starts on demand. You don't need to enable it manually.

The extension finds TablePro by its bundle ID, `com.TablePro`, so it works wherever the app is installed.

#### Preferences

- **MCP Port**: the port of TablePro's MCP server. The default is `23508`. If that port is taken, TablePro runs the server on another port and shows it in its settings. Copy that port here.

#### Commands

- **Search Connections**: list saved connections, open one in TablePro, copy a deep link.
- **Open Connection**: `Open Connection prod` from the Raycast root.
- **TablePro Menu Bar**: show recent connections and quick actions in the menu bar.
- **Search Schema**: drill into databases and schemas across connections.
- **Search Tables**: pick a connection, list tables, copy DDL, open a table tab.
- **Recent Tabs**: show tabs currently open in TablePro and reopen one.
- **Run Query**: paste SQL, pick a connection, preview up to 50 of 200 fetched rows in Raycast or open the full grid in TablePro. Mutating queries ask before running.
- **Search Query History**: full-text search across the TablePro query history.
- **Pair with TablePro**: issue or refresh the API token. Use `cmd+shift+k` on the form to sign out and clear the local token.

#### AI tools

The extension exposes 12 tools to Raycast AI:

- `list-connections`, `list-databases`, `list-schemas`, `list-tables`, `describe-table`, `get-table-ddl`
- `run-query`, with mutating SQL routed through `Tool.Confirmation` showing connection name and SQL preview
- `explain-query`, `open-connection-window`, `search-history`, `get-connection-status`, `list-recent-tabs`

Try `@tablepro show me users in prod` or `@tablepro how big is the orders table on staging`.

#### Permissions and access control

Each TablePro connection has an external-access setting (Blocked, Read-only, Read & Write). Tokens are issued with their own scope. The actual permission is the minimum of the two. A full-access token against a read-only connection cannot mutate.

If TablePro denies a query, the extension shows TablePro's message as Access denied. Change the connection's external access in TablePro under the connection editor.

#### Pairing flow

The pairing flow uses PKCE so the local TablePro app and the extension agree on a token without ever sharing it through a URL.

1. Raycast generates a verifier (32 random bytes) and a SHA-256 challenge.
2. Raycast opens `tablepro://integrations/pair?...` with the challenge and a `raycast://` callback.
3. TablePro shows the approval sheet. On approve, TablePro mints a one-time code and opens the callback.
4. The extension POSTs the code plus verifier to the local exchange endpoint at `127.0.0.1:<MCP Port>/v1/integrations/exchange` and receives the token.
5. The token is stored in Raycast's encrypted extension storage.

The exchange endpoint takes no auth. The single-use code is the auth.

Before the extension sends the code or the token, it checks without credentials that TablePro answers on the MCP Port. If another program answers there, nothing is sent.

#### Privacy

- Connection metadata (`name`, `host`, `port`, `type`) is read from `~/Library/Application Support/TablePro/connections.json`.
- The TablePro version is read from the app's `Info.plist` with `/usr/bin/plutil`. No other TablePro file is read.
- Passwords are never read by the extension. They live in the TablePro Keychain.
- Query results are fetched on demand from the local MCP server at `127.0.0.1`.
- The extension makes no third-party network requests.

#### Troubleshooting

- **TablePro is not installed**: install from tablepro.app. The extension looks the app up by bundle ID, not by path.
- **Update TablePro**: install TablePro 0.37.0 or later.
- **TablePro is not running**: open TablePro. The MCP server starts on first request, you don't need to enable it.
- **No answer on port 23508**: TablePro's MCP server runs on a different port. Copy the port TablePro shows in its settings into the MCP Port preference.
- **The connection list is empty**: open TablePro at least once so it loads `~/Library/Application Support/TablePro/connections.json`. Connections you create later show up after the next list refresh.
- **API token was revoked** or **API token expired**: run Pair with TablePro again. Tokens revoked from inside TablePro (Settings > Integrations > Tokens) need a fresh pairing.
- **Pairing got stuck**: close the Pair window and run the command again. Each run generates a fresh verifier, and verifiers expire after 5 minutes if the approval sheet is left open.
- **"This connection is read-only" on a write query**: the connection's External Access is set to Read-only or Blocked, or your token's scope is read-only. Change either in TablePro under the connection editor or under Settings > Integrations > Tokens.
- **A query times out**: TablePro hasn't connected to the database yet. Run **Open in TablePro** first, confirm the connection is live, then retry from Raycast.
- **Run Query says the result was capped**: TablePro applies a row safety cap (default 10,000 rows). Add an explicit `LIMIT` to your query, or open it in TablePro and click Fetch All.
- **Old plugins broken after a TablePro update**: separately distributed plugins ship per-version. Open TablePro > Settings > Plugins to update them. The Raycast extension keeps working even when a specific driver plugin is being updated.
