Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions developers/mcp-prompts.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -134,6 +134,8 @@ Anything else returns an empty list rather than an error.

`database`, `schema` and `table` need to know which connection to read. Pass it in `context.arguments` under `connection`, `connection_id`, or `id`. Without one, the result is empty.

They also need that connection approved for this client, and completion never asks. It reads the connection once the user has allowed this client at **Ask Once for Each Connection**, under **Never Ask**, or on a connection whose AI policy is **Always Allow**. Otherwise the result is empty. A forgotten or revoked approval applies from the next request.

For a `ref/resource` completion TablePro fills the context from the URI itself, so completing `table` in `tablepro://connections/{id}/tables/{table}` already knows the connection, and the `database` and `schema` query parameters if the URI carries them. Anything you pass in `context.arguments` wins.

### Matching and limits
Expand Down
2 changes: 1 addition & 1 deletion developers/mcp-resources.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -140,7 +140,7 @@ This is the only subscribable resource. See [Subscriptions](/developers/mcp-subs
}
```

`executed_at` is ISO 8601. `schema_name` appears when the entry has one, and `error_message` when `was_successful` is false, redacted.
`executed_at` is ISO 8601. `schema_name` appears when the entry has one, and `error_message` when `was_successful` is false, redacted. On a connection with masking rules, `query` and `error_message` can hold a fixed sentence and `search` skips some entries: see [Masking rules](/developers/mcp-tools#masking-rules).

## Errors

Expand Down
22 changes: 20 additions & 2 deletions developers/mcp-tools.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ In the tables below, required arguments come first and optional ones follow in p
- The result comes back twice: as JSON text in `content[0]`, and as a typed object in `structuredContent`. Read `structuredContent`.
- Timestamps are ISO 8601, error text is redacted, and "a result set" means `columns[]`, `rows[][]`, `row_count`, `rows_affected`, `execution_time_ms`, `is_truncated`, plus `status_message`, `database` and `schema` when they apply.

A column a [masking rule](/features/data-masking) matches comes back masked in every tool that returns rows, `browse_table`, `execute_query` and `export_data` included. The mask replaces the value in `rows[][]`; `columns[]` and `row_count` are unchanged. A filter or sort in the request still runs on the stored values.
A column a [masking rule](/features/data-masking) matches comes back masked in every tool that returns rows, `browse_table`, `execute_query` and `export_data` included. The mask replaces the value in `rows[][]`; `columns[]` and `row_count` are unchanged. A filter or sort in the request still runs on the stored values. A connection with rules also changes errors, plans and some text fields: see [Masking rules](#masking-rules).

Row limits default to the server's **Default row limit** setting (500) and are capped by **Maximum row limit** (10,000). Timeouts default to **Query timeout** (30 seconds) and are capped at 300. Both live in **Settings > MCP**.

Expand All @@ -41,12 +41,30 @@ Past the scope, a call clears three more gates:
2. **Connection policy.** **External Clients** set to **Blocked** hides the connection: `list_connections` omits it and any tool that names it is refused. An AI policy of **Never** does the same, except that [`purpose: "display"`](#listing-for-display) still lists it. Otherwise the first call that touches a connection asks the user, as often as **Settings > MCP > Approval** says. That question is always a dialog on the user's Mac, never an elicitation: a client that could answer it could also grant itself the connection. It has no deadline, so the client owns the timeout, and a refusal stands for 60 seconds before the question can be put again.
3. **Safe Mode.** A write goes through the connection's Safe Mode, which may ask the user to confirm it or to authenticate. See [Approvals](/developers/mcp-protocol#approvals-and-input-required).

`completion/complete` clears the same connection policy without asking: on a connection this client is not approved for, it completes nothing. See [Context matters](/developers/mcp-prompts#context-matters).

A call that opens a connection may also need approval on the Mac for a pre-connect script, environment variables, or [local sign-in credentials](/connections/connection-form#sign-ins-from-this-mac). A refusal returns `denied`; an unanswered prompt returns `timeout`.

`confirm_destructive_operation` needs `admin` as well, so it takes a Full Access token, and **Read Only** refuses it outright whatever the token carries. No token skips the user's approval.

**Read Only** refuses a statement classified as a write with `denied`. Reads also use the driver's read-only mode where supported. [What Read Only allows](/developers#what-read-only-allows) lists engine limits and the statements refused at every access level. Multiple statements return `invalid_argument`, except for SQL Server scripts sent to [`execute_query`](#execute_query) or [`confirm_destructive_operation`](#writing-data).

## Masking rules

On a connection with [masking rules](/features/data-masking#masking-for-ai-and-scripts), PostgreSQL, MySQL, MariaDB and local SQLite mask a cell by the table column it reads, so an alias is masked too. A column that reads no column of a user table comes back masked whole, whatever its name, and `status_message` names it. On engines that cannot trace a column, that is every column of a query. Schema tools such as `describe_table` return the structure as usual.

The rules also withhold text that can repeat a stored value:

| Tool | On a connection with rules |
|------|----------------------------|
| A failed statement, in any tool that runs one | `query_failed`, with the error code and SQLSTATE when the driver reports them and the withheld-message sentence in place of the server's text. A failure before the driver takes the statement keeps its text |
| `explain_query` | The plan masked whole, `plan_text` and `plan` included, except on PostgreSQL and SQLite. `status_message` says why |
| `get_server_dashboard` | The withheld-statement sentence as the `query` of every session and slow query |
| `search_query_history`, the history resource | The withheld-message sentence as every `error_message`. An entry whose `source` is `row_edit` or `import` has the withheld-statement sentence as its `query`, and a search with text leaves it out |
| `browse_table`, `export_data` | A system table masked whole |

The withheld-message sentence reads `The statement failed with error 1146, SQLSTATE 42S02. Its message is withheld because this connection has masking rules, and the message can repeat a masked value.`, without the codes when there are none. The withheld-statement sentence reads `The statement text is withheld because this connection has masking rules, and it can repeat a masked value.`

## Connections

| Tool | Arguments | Returns |
Expand Down Expand Up @@ -163,7 +181,7 @@ On SQL Server, send the whole script instead. A variable exists only in the batc

The top-level fields describe the first result set, with `rows_affected` counting the whole script. When the script returns more than one result set, `result_sets[]` lists every one in order, each with `columns`, `rows`, `row_count` and `is_truncated`. `max_rows` caps each result set on its own. `status_message` says when the script left a transaction open.

A batch that raises an error fails the call with the server's message and line number. The batches after it do not run, and the error says what stays applied.
A batch that raises an error fails the call with the server's message and line number. The batches after it do not run, and the error says what stays applied. On a connection with [masking rules](#masking-rules), the whole message is withheld.

### `explain_query`

Expand Down
2 changes: 1 addition & 1 deletion development/plugin-development.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ A plugin is a macOS loadable bundle target with `WRAPPER_EXTENSION = tableplugin

| Key | Type | Required | Purpose |
|-----|------|----------|---------|
| `TableProPluginKitVersion` | integer | Yes | The PluginKit ABI the plugin was built against. Current value: 42 |
| `TableProPluginKitVersion` | integer | Yes | The PluginKit ABI the plugin was built against. Current value: 43 |
| `TableProProvidesDatabaseTypeIds` | array of strings | Recommended | Database type IDs the plugin serves, which is what makes lazy loading possible |
| `CFBundleShortVersionString` | string | Yes | Plugin version shown in **Settings > Extensions** |
| `CFBundleVersion` | string | Yes | Build number. Of two copies of a plugin the higher build loads, and a registry update needs a higher build |
Expand Down
4 changes: 3 additions & 1 deletion features/ai-assistant.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,8 @@ With no preference, start with Claude or OpenAI on an API key: both take a key,

Install Claude Code, run `claude /login` in Terminal, then pick Opus, Sonnet, or Haiku. Replies bill against your Claude subscription instead of an API key. The provider answers from your schema when the MCP server is on in **Settings > MCP**, and falls back to plain chat when it is off.

Whatever the chat mode, its tools only read, and reach only the chat's connection: each reply runs on a [**Read Only**](/developers/tokens) MCP token limited to that connection. At **Ask Once for Each Connection** in **Settings > MCP**, one **Allow** covers every later reply on the connection until you click **Forget** on its **Claude Agent** row, or end its token with **Revoke**, **Delete** or **Disconnect** while a reply runs.

The `claude` tool runs headless here. Claude Code is built for you to use directly rather than as a backend for other apps, so this path can break with any Claude Code release. Your subscription is governed by Anthropic's [Consumer Terms](https://www.anthropic.com/legal/consumer-terms) and [Usage Policy](https://www.anthropic.com/legal/aup), which TablePro cannot grant rights under. Replies also count against the limits you share with claude.ai and your own Claude Code sessions, so running out here stops your work there. For a metered path on commercial terms, add the **Claude** provider with an API key.

## Apple Intelligence
Expand Down Expand Up @@ -140,7 +142,7 @@ Start with **Review with AI** when you are unsure what to ask: it checks correct
<img className="hidden dark:block" src="/images/ai-query-review-dark.png" alt="Query bar with the Review button, and the assistant answering a review of a JOIN" />
</Frame>

The request carries the structure of the tables the statement names, read from the tab's own database and schema: columns and types, keys, indexes with their predicates, foreign keys, and estimated row counts. Up to 12 tables go, in the order the statement names them. The chip above your message lists them; hover it to see any table that could not be read or was not found. If the tab already shows an EXPLAIN plan for the same statement, the plan goes too. Building this reads only the database's catalog: your statement never runs, and no rows are sent. Turn off **Include database schema** in **Settings > AI** to send the statement alone.
The request carries the structure of the tables the statement names, read from the tab's own database and schema: columns and types, keys, indexes with their predicates, foreign keys, and estimated row counts. Up to 12 tables go, in the order the statement names them. The chip above your message lists them; hover it to see any table that could not be read or was not found. If the tab already shows an EXPLAIN plan for the same statement, the plan goes too, unless [masking rules](/features/data-masking#on-a-connection-with-rules) hold it back. Building this reads only the database's catalog: your statement never runs, and no rows are sent. Turn off **Include database schema** in **Settings > AI** to send the statement alone.

With no provider set up and Apple Intelligence off, the actions are dimmed. With Apple Intelligence on, they are dimmed while it cannot run, and the tooltip says why. With AI turned off, or on a connection whose AI policy is **Never**, they are hidden.

Expand Down
41 changes: 40 additions & 1 deletion features/data-masking.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,33 @@ One rule covers every place a value leaves TablePro:

A query result has no source table for most engines, so a `table.column` rule matches a query result by its column name alone. `users.ssn` then also masks an `ssn` column a query reads from another table.

## Masking for AI and scripts

Results for MCP clients, the AI assistant, Claude Agent, AppleScript and Shortcuts are masked by the table column each result column reads, as well as by its name. On PostgreSQL, MySQL, MariaDB and local SQLite, `SELECT email AS contact FROM users` comes back masked by a `*.email` rule.

On a connection with at least one rule, a column that reads no column of a user table comes back as `••••`, whatever its name. The result's status message names the columns masked this way. That covers:

- An expression or an aggregate, such as `lower(email)` or `count(*)`.
- A system table or catalog, such as `pg_stat_activity`, in a query, a browse or an export. Schema lookups such as `describe_table` still return the structure.
- Every column of a statement the driver does not trust: a subquery, a CTE or a `UNION` on MySQL and MariaDB, a compound `SELECT` or `VALUES` on SQLite. One of those words inside a value, such as a filter on `'union'`, counts too.

These cannot trace a column: ClickHouse, Redis, CockroachDB, Redshift, TiDB, Databend, OceanBase, a SQLite [remote file](/connections/remote-database-files) opened **On the Server**, and every engine from the plugin registry. On a connection with rules, every column of a query on them comes back masked, and a browsed or exported table is matched by column name, as in the grid.

### On a connection with rules

The rules also withhold text that can repeat a stored value:

| Where | What comes back |
|-------|-----------------|
| A statement that fails | The error code and SQLSTATE where the driver reports them, and a sentence saying the message is withheld |
| **Fix with AI** | The failed statement, without the server's message |
| A query plan | The plan masked whole, except PostgreSQL's and SQLite's. **Review with AI**, **Explain with AI** and **Optimize with AI** attach no plan on other engines |
| History entries the app wrote from row data, under **Row Edits** and **Imports** | A sentence in place of the statement. A history search with text leaves them out |
| The error of any history entry | A sentence in place of the message |
| Session and slow-query text from the server dashboard | A sentence in place of the statement |

A refusal, a timeout or a cancel from TablePro itself keeps its text.

## Editing and Reveal

A grid that shows a masked column is read-only, since a mask cannot be written back or used to find its row. To see or edit the real values, right-click a masked column's header and choose **Reveal Masked Values…**. TablePro asks for Touch ID, or your macOS password on a Mac without it, and reloads the tab unmasked. A query tab whose statement is not a read reveals on its next run instead.
Expand All @@ -67,5 +94,17 @@ Reveal lasts until the tab closes or opens another table. Other tabs, exports fr
Masking hides values inside TablePro. It does not replace database permissions: anyone with the connection's credentials can read the data with another client.

- Filters, sorts and `WHERE` clauses run on the server against the stored values, so a filter on a masked column finds the real matches.
- A rule matches the column name a result reports. A query that renames or computes the column, such as `SELECT email AS contact`, returns it unmasked, and that includes queries an MCP client or the AI assistant writes. A **Type** rule catches a renamed column that keeps its type.
- In the grid, a rule matches the column name a result reports. A query that renames or computes the column, such as `SELECT email AS contact`, shows it unmasked. A **Type** rule catches a renamed column that keeps its type. Results for AI and scripts are [masked by what each column reads](#masking-for-ai-and-scripts).
- **Copy To**, copying objects to another database and Compare move the stored values, not the masks.
- The **Edit Document** sheet shows a stored document's fields without Reveal. Query plans, and the sessions and slow queries on the server dashboard, are not masked in the app.

### Known limits for AI and scripts

A client that may run SQL can still learn a masked value these ways:

- A view, a generated column or a table copied with `CREATE TABLE … AS SELECT` holds the value under its own name. A rule that does not name that column leaves it unmasked, in the grid too. Making the copy is a write, which a **Read Only** token or connection refuses.
- `WHERE` and `ORDER BY` test a value without returning it, such as `WHERE email LIKE 'a%'`. Row counts and row order answer one guess at a time.
- How long a query takes, and whether it fails, can depend on a masked value. A client can probe both, even with the error text withheld.
- A statement a client or a person typed comes back as written, in history and in its own results. So do literals another session sent, wherever the database shows them outside the masked system views.
- On an engine that cannot trace columns, only the system databases and schemas the engine declares are masked whole, not system tables inside a user database. On a SQLite file opened **On the Server**, `sqlite_stat4` and a full-text table's `<name>_content` copy show their columns as your rules name them. CockroachDB's `crdb_internal`, whose lock and contention views print index keys with their values, is not masked whole either.
- Column names are never masked. On MySQL, a client that may prepare statements can build a column name from a value with `PREPARE`.
3 changes: 2 additions & 1 deletion features/mcp.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,8 @@ The first time a client reaches one of your connections, TablePro asks. **Approv

Leave it at **Ask Once for Each Connection** unless a client runs unattended, in which case **Never
Ask** stops the prompt from waiting for someone who is not there. Approvals already given are listed
underneath, each with **Forget**.
underneath, each with **Forget**. A row names the connection and the client it was given to: a
token's name, **Built-in CLI** for the bundled bridge, or [**Claude Agent**](/features/ai-assistant#claude-agent).

Approval decides only whether you are asked. It grants nothing: a connection **Blocked** for
external clients stays blocked, a **Read Only** one stays read only, a connection whose AI policy is
Expand Down
Loading