From 16c7f46e386417a40f1fffae29cee43bbca65256 Mon Sep 17 00:00:00 2001 From: Ngo Quoc Dat Date: Thu, 12 Nov 2026 07:02:26 +0700 Subject: [PATCH 1/2] docs(features): document Read-Only at the server, MCP answer limits and the assistant's narrower tools --- connections/connection-form.mdx | 2 +- developers/mcp-protocol.mdx | 4 ++-- developers/mcp-resources.mdx | 5 +++-- developers/mcp-tools.mdx | 35 ++++++++++++++++++++++++--------- features/ai-assistant.mdx | 16 +++++++++------ features/mcp.mdx | 8 +++++++- features/safe-mode.mdx | 8 +++++++- 7 files changed, 56 insertions(+), 22 deletions(-) diff --git a/connections/connection-form.mdx b/connections/connection-form.mdx index feaacf6..40347f9 100644 --- a/connections/connection-form.mdx +++ b/connections/connection-form.mdx @@ -82,7 +82,7 @@ Encryption sits below the transport. [SSL/TLS](/connections/ssl) covers the mode | **Timeout** | Seconds each connection script may run. Empty uses 10; valid values are 1 to 300 | | **Post-Disconnect Script** | Shell script run once the session ends, after a pre-connect script ran. See [Connection scripts](#connection-scripts) | | **Safe Mode** | Confirms, authenticates or refuses queries before they run. See [Safe Mode](/features/safe-mode) | -| **AI Policy** | Per-connection override for the in-app AI agents. **Never** also refuses external clients. Shown while **Enable AI Features** is on | +| **AI Policy** | Per-connection override for the in-app AI agents. **Never** also refuses external clients. Under it, each tool you gave **Always Allow** on an [assistant tool card](/features/ai-assistant#tool-calling) is listed by name as **Always allowed**, with **Forget**. After **Save**, a forgotten tool asks again on its next call. Shown while **Enable AI Features** is on | | **External Clients** | **Blocked**, **Read Only** (the default), or **Read & Write** for MCP clients such as Raycast, Cursor, and Claude Desktop, and for [AppleScript](/developers/applescript) and [Shortcuts](/integrations/shortcuts). A token's own scope cannot raise it. See the [integration security model](/developers#security-model) | | **AI Rules** | Guidance the AI reads on every chat turn for this connection: table conventions, columns to avoid, join hints. Shown while **Enable AI Features** is on. See [AI Assistant](/features/ai-assistant) | | **Local only** | Keeps this connection and its passwords off iCloud. Saving an existing synced connection as Local only removes its passwords from iCloud Keychain, so your other devices ask for them again. Shown while **Sync this Mac with iCloud** is on. See [iCloud Sync](/features/icloud-sync#keeping-a-connection-off-icloud) | diff --git a/developers/mcp-protocol.mdx b/developers/mcp-protocol.mdx index 2652980..fecc03c 100644 --- a/developers/mcp-protocol.mdx +++ b/developers/mcp-protocol.mdx @@ -241,7 +241,7 @@ Send `notifications/cancelled` with the `requestId` of a request that is still r { "jsonrpc": "2.0", "method": "notifications/cancelled", "params": { "requestId": 7, "reason": "user aborted" } } ``` -The notification is answered with `202` whether or not anything matched. The cancelled request finishes with `-33002`. +The notification is answered with `202` whether or not anything matched. The cancelled request finishes with `-33002`. A write the database had already started is not stopped: it runs to the end, and the `-33002` carries `data: { "outcome": "unknown" }`. It may have been applied, so check before sending it again. Cancellation is per principal: a token can only cancel its own requests. Revoking a token cancels everything it has in flight. @@ -359,7 +359,7 @@ Per-caller request rates, auth lockouts and pairing lockouts are counted separat A request with no `io.modelcontextprotocol/protocolVersion` in `_meta` is treated as legacy, and legacy still works the old way: 1. `POST /mcp` with `initialize` and a `protocolVersion` of `2025-11-25` or `2025-06-18`. Any other value is `-32022`. -2. The response carries `protocolVersion`, `capabilities`, `serverInfo` and `instructions`. +2. The response carries `protocolVersion`, `capabilities`, `serverInfo` and `instructions`. `capabilities` follows the token: `tools` needs `tools:read`, and `resources`, `prompts` and `completions` need `resources:read`. 3. Every later request carries `Mcp-Session-Id`. A session belongs to the token that created it; presenting it under another token is `-33001`. 4. A session lives until the server stops. The store holds at most 16 and evicts the least recently used past that. A session the server does not recognize is `-33001`, and the client has to `initialize` again. diff --git a/developers/mcp-resources.mdx b/developers/mcp-resources.mdx index b066823..bbb4fd9 100644 --- a/developers/mcp-resources.mdx +++ b/developers/mcp-resources.mdx @@ -136,11 +136,12 @@ This is the only subscribable resource. See [Subscriptions](/developers/mcp-subs "row_count": 142, "was_successful": true } - ] + ], + "is_truncated": false } ``` -`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). +`is_truncated` is true when the [size limit](/developers/mcp-tools#answer-size) left out matching entries. `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 diff --git a/developers/mcp-tools.mdx b/developers/mcp-tools.mdx index ff38a8b..31e9e71 100644 --- a/developers/mcp-tools.mdx +++ b/developers/mcp-tools.mdx @@ -13,11 +13,11 @@ In the tables below, required arguments come first and optional ones follow in p - `database` and `schema` default to whatever the connection is currently browsing, except that `search_schema` without `schema` looks in every schema. Passing them targets somewhere else **without moving the app's selection**. - An unknown argument is rejected with `-32602`. There is no silent ignoring. - 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. +- 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`, `notes`, `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 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**. +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**. Whatever the row limit, rows also stop at the [answer size limit](#answer-size). ## Tool index @@ -65,6 +65,17 @@ The rules also withhold text that can repeat a stored value: 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.` +## Answer size + +One answer holds at most 4 MB, measured after masking. The limit covers `browse_table`, `execute_query`, `confirm_destructive_operation`, `explain_query`, `export_data`, `stop_server_session`, `search_query_history` and the [history resource](/developers/mcp-resources#tablepro%3A%2F%2Fconnections%2F%7Bid%7D%2Fhistory%7B%3Flimit%2Csearch%2Cdate_filter%7D). `run_maintenance` applies it to each statement's result on its own. + +- A value longer than 64 KB keeps its first 64 KB and ends in ` [TablePro cut this value: N bytes in all]`, where N is its full size in bytes. A binary value counts its base64 length and keeps the base64 of its first 48 KB. `export_data` never cuts a value. +- Rows keep their order. The first row that does not fit is left out, and so is every row after it. +- `is_truncated` is true when the row limit or the size limit left rows out. +- A result set, `explain_query` and `export_data` carry `notes`, an array of sentences saying why rows were left out or values cut. It is absent when neither happened. + +To read a value that was cut, select part of it with a narrower query. To get more rows, ask for fewer columns. + ## Connections | Tool | Arguments | Returns | @@ -155,8 +166,8 @@ A lost connection, or a database where no schema could be read, fails the call i | `browse_table` | `connection_id`, `table` (`columns`, `filters`, `logic`, `sort`, `limit`, `offset`, `timeout_seconds`, `database`, `schema`) | A result set | | `count_rows` | `connection_id`, `table` (`exact`, `filters`, `logic`, `database`, `schema`) | `table`, `row_count`, `is_approximate`, `filter_count` | | `execute_query` | `connection_id`, `query` (`max_rows`, `timeout_seconds`, `database`, `schema`, `read_only`) | A result set, plus `result_sets[]` when a SQL Server script returns more than one | -| `explain_query` | `connection_id`, `query` (`analyze`, `variant`, `timeout_seconds`, `database`, `schema`) | `statement` as actually sent, `execution_time_ms`, `columns[]`, `rows[][]`, and where available `plan_text`, `plan` and `available_variants[]` (`id`, `label`, `sql_prefix`, `runs_statement`). On Oracle and SQL Server the driver builds the plan from several statements, so `statement` is the query alone and `sql_prefix` is empty | -| `export_data` | `connection_id`, `format` (`query` **or** `tables`, `sql_table`, `output_path`, `max_rows`, `database`, `schema`) | `format`, `rows_exported`, `is_truncated`, `path` when a file was written, and `exports[]` (`label`, `row_count`, `is_truncated`, `data`) | +| `explain_query` | `connection_id`, `query` (`analyze`, `variant`, `timeout_seconds`, `database`, `schema`) | `statement` as actually sent, `execution_time_ms`, `columns[]`, `rows[][]`, and where available `plan_text`, `plan` and `available_variants[]` (`id`, `label`, `sql_prefix`, `runs_statement`), plus `is_truncated` and `notes` when the [size limit](#answer-size) applied. On Oracle and SQL Server the driver builds the plan from several statements, so `statement` is the query alone and `sql_prefix` is empty | +| `export_data` | `connection_id`, `format` (`query` **or** `tables`, `sql_table`, `output_path`, `max_rows`, `database`, `schema`) | `format`, `rows_exported`, `is_truncated`, `path` when a file was written, `exports[]` (`label`, `row_count`, `is_truncated`, `data`), and `notes` when the size limit left rows out | | `quote_identifiers` | `connection_id` and at least one of `identifiers`, `literals` (`database`, `schema`) | `identifiers[]` as `{ input, quoted }` and `literals[]` as `{ input, escaped }`, in the order supplied | ### `browse_table` @@ -179,18 +190,22 @@ One statement, 100 KB at most. Destructive statements are refused here; use [`co On SQL Server, send the whole script instead. A variable exists only in the batch that declares it, so a `DECLARE` and the `SELECT`s that read it belong in one call. The script is cut into batches at its `GO` lines, as the query editor cuts it, and `GO 5` runs a batch five times. The gates judge the script by its worst statement: one write anywhere needs `tools:write` and Safe Mode, and any destructive statement refuses the call. `DECLARE` and `EXEC` of a procedure count as writes, `sp_help` included. `EXEC` of a string and `sp_executesql` run server-side code and are refused. -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. +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, while the [size limit](#answer-size) covers them all together. Once it is spent, the later batches still run, and their result sets come back with no rows and `is_truncated` set. `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. On a connection with [masking rules](#masking-rules), the whole message is withheld. ### `explain_query` -Pass the query with no `EXPLAIN` prefix. Without `variant` the engine's first variant runs, and every result lists them in `available_variants[]`. `analyze: true` picks the variant that runs the statement, so an analyzed write needs `tools:write` and Safe Mode approval, and it is refused when the engine has no such variant or the `variant` you pass only estimates. An engine missing from the [support table](/features/explain-visualization#database-support) is refused. +Pass the query with no `EXPLAIN` prefix. Without `variant` the engine's first variant runs, and every result lists them in `available_variants[]`. `analyze: true` picks the variant that runs the statement, so an analyzed write needs `tools:write` and Safe Mode approval, and it is refused when the engine has no such variant or the `variant` you pass only estimates. An analyzed write goes into query history the way an `execute_query` write does. An engine missing from the [support table](/features/explain-visualization#database-support) is refused. + +`plan_text` and the plan rows share one answer, `plan_text` first. `is_truncated` appears, set to true, only when the [size limit](#answer-size) left plan rows out. ### `export_data` Formats are `csv`, `json` and `sql`; pass exactly one of `query` or `tables[]`. Without `output_path` the text comes back inline in each export entry. With it, the file lands in the user's Downloads folder and never overwrites, so a name that is taken gets `-1`, `-2` and so on; the path must stay inside Downloads, end in the format's extension, and not name a hidden file. SQL output uses the connection's own quoting and literal rules, so exporting a query needs `sql_table` to name the target table. +Every table in one call shares one 4 MB [answer](#answer-size), with or without `output_path`, and each table gets what the ones before it left. Values stay whole: a row that does not fit is left out with every row after it, so a later table can come back with no rows. Export fewer tables, columns or rows per call when `is_truncated` is set. + ## Writing data | Tool | Arguments | Returns | @@ -256,13 +271,15 @@ These read and drive the TablePro app itself, and none of them bypasses the conn | `focus_query_tab` | `tab_id` | `status` (`focused`), `tab_id`, `connection_id`, `window_id` | | `open_connection_window` | `connection_id` | `status` (`opened`), `connection_id`, `tab_id`, `window_id`, `is_connected` | | `open_table_tab` | `connection_id`, `table_name` (`database_name`, `schema_name`) | `status` (`opened`), `connection_id`, `table_name`, `tab_id`, `window_id` | -| `search_query_history` | `query` (`connection_id`, `limit`, `since`, `until`) | `entries[]` carrying `id`, `query`, the connection and database it ran on, `source`, `statement_type`, `executed_at`, `execution_time_ms`, `row_count`, `was_successful` and `error_message`, newest first | +| `search_query_history` | `query` (`connection_id`, `limit`, `since`, `until`) | `entries[]` carrying `id`, `query`, the connection and database it ran on, `source`, `statement_type`, `executed_at`, `execution_time_ms`, `row_count`, `was_successful` and `error_message`, newest first, and `is_truncated` | + +`list_recent_tabs` and `search_query_history` without `connection_id` never ask the user. They cover only the connections this client reaches without a question, which depends on the [Approval](/features/mcp#connection-access) setting. With `connection_id`, the user is asked about that connection once, as for any call that names one. `focus_query_tab` asks about the tab's connection before it raises the tab. -Starred tables are a good hint at what matters in a database. `list_recent_tabs` covers every readable connection when `connection_id` is omitted, its `limit` runs 1 to 500, default 20, and `tab_type` is one of `query`, `table`, `createTable`, `erDiagram`, `serverDashboard`, `insights`, `tableHealth`, `usersRoles`, `objectSource`, `versionHistory`, `tableListing`. +Starred tables are a good hint at what matters in a database. `list_recent_tabs` takes `limit` from 1 to 500, default 20, and its `tab_type` is one of `query`, `table`, `createTable`, `erDiagram`, `serverDashboard`, `insights`, `tableHealth`, `usersRoles`, `objectSource`, `versionHistory`, `tableListing`. `open_connection_window` and `open_table_tab` connect first if they have to, and return once the window has a tab or fail after 8 seconds. `open_table_tab` without `database_name` or `schema_name` means the ones the connection is on, and its `tab_id` is that table's tab, never a table of the same name elsewhere. -`search_query_history` searches the history TablePro keeps on this Mac. Pass `""` to match everything and filter by date alone; `since` and `until` are Unix epoch seconds, and `limit` runs 1 to 500, default 50. Results cover only connections this client may reach, with or without `connection_id`. +`search_query_history` searches the history TablePro keeps on this Mac. Pass `""` to match everything and filter by date alone; `since` and `until` are Unix epoch seconds, and `limit` runs 1 to 500, default 50. `is_truncated` is true when the [size limit](#answer-size) left out matching entries. ## Annotations diff --git a/features/ai-assistant.mdx b/features/ai-assistant.mdx index dc8e5c4..4e29da9 100644 --- a/features/ai-assistant.mdx +++ b/features/ai-assistant.mdx @@ -47,7 +47,7 @@ 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. +Its tools never write and reach only the chat's connection: each reply runs on a [**Read Only**](/developers/tokens) MCP token limited to that connection. The token follows the [chat mode](#chat-modes). In **Ask** it reaches only the seven schema tools that mode lists. In **Edit** and **Agent** it reaches the MCP server's [read tools](/developers/mcp-tools#scopes-and-gates), so it reads rows but never changes them. 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. @@ -86,26 +86,30 @@ The mode picker in the composer footer controls which tools the AI can call. It | Mode | Tools available | When to use | |------|----------------|-------------| -| **Ask** | Read-only schema lookups: `list_connections`, `get_connection_status`, `list_databases`, `list_schemas`, `list_tables`, `describe_table`, `get_table_ddl`. | Questions, exploration, drafting queries you run yourself. | -| **Edit** | All Ask tools, plus `execute_query` for `SELECT`, `INSERT`, `UPDATE`, `DELETE`. Destructive statements stay blocked. See [external query rules](/developers#what-read-only-allows). | Letting the AI run the queries it proposes. | +| **Ask** | Read-only schema lookups: `list_connections` (this conversation's connection only), `get_connection_status`, `list_databases`, `list_schemas`, `list_tables`, `describe_table`, `get_table_ddl`. | Questions, exploration, drafting queries you run yourself. | +| **Edit** | All Ask tools, plus `execute_query` for any statement that is not destructive. The model is told to keep to `SELECT`, `INSERT`, `UPDATE` and `DELETE` and leave schema, privilege and session changes to Agent mode, but Edit refuses only destructive statements. See [external query rules](/developers#what-read-only-allows). | Letting the AI run the queries it proposes. | | **Agent** | All tools, plus `confirm_destructive_operation` for destructive statements. Runs tools in a loop. | Multi-step migrations and schema changes. | Mode and [Safe Mode](/features/safe-mode) are independent gates. Agent mode does not bypass Safe Mode. ### Tool calling -In Edit and Agent modes each tool call appears as a card in the reply. Read-only tools run immediately. Write tools wait for **Run**, for **Always for this connection** (which whitelists that one tool on that one connection and syncs with it over iCloud), or for **Cancel**, which hands the model an error result and lets it carry on. +In Edit and Agent modes each tool call appears as a card in the reply. Read-only tools run immediately. Write tools wait for **Run**, for **Always Allow** (which lets that one tool run on that one connection without asking from then on, and syncs with the connection over iCloud), or for **Reject**, which hands the model an error result and lets it carry on. To take an **Always Allow** back, click **Forget** beside the tool under **AI Policy** in the [connection form](/connections/connection-form#options), then **Save**. Per-card tool approval Per-card tool approval -Safe Mode **Silent** auto-approves write tools and **Read-Only** auto-denies them. Destructive operations are the exception: `confirm_destructive_operation` always needs a click, Silent does not auto-approve it, **Always for this connection** is refused for it, and the model must pass the verbatim phrase `I understand this is irreversible`. +Safe Mode **Silent** auto-approves write tools and **Read-Only** auto-denies them. Destructive operations are the exception: `confirm_destructive_operation` always needs a click, Silent does not auto-approve it, its card has no **Always Allow**, and the model must pass the verbatim phrase `I understand this is irreversible`. + +**Stop Generating** does not stop a write the database is already running. The write runs to the end, and the tool result in the reply says it may have been applied: check before you run it again. + +Rows from `execute_query` and `confirm_destructive_operation` reach the model held to 256 KB per call, cut the way an [MCP answer](/developers/mcp-tools#answer-size) is cut. `execute_query` follows the [external query rules](/developers#what-read-only-allows), including their SQL Server script exception. Text stored in the database can steer the model, so on a connection where an unwanted write matters, connect with a login that can only read: the database holds that limit whatever the model sends. -Every provider can call tools. Claude Agent reaches them through the MCP server, so that has to be on, and local models depend on the model. +Every provider can call tools. Claude Agent reaches them through the MCP server, so that has to be on, and it never writes in any mode: see [Claude Agent](#claude-agent). Local models depend on the model. A reply pauses after 25 tool calls, keeps everything it has done, and offers **Continue** for a fresh budget or **Adjust Limit** to change the number, 5 to 200, under **Agent** in **Settings > AI**. Every call is another request with the schema attached, so a higher limit costs tokens. diff --git a/features/mcp.mdx b/features/mcp.mdx index c7f7bb5..3552e76 100644 --- a/features/mcp.mdx +++ b/features/mcp.mdx @@ -32,7 +32,7 @@ The default HTTP port is **23508**. If it is taken, the server binds a free port | Query timeout | 30 seconds | 1 to 300 seconds | | Log MCP queries in history | on | | -A tool can ask for fewer rows or a shorter timeout, never for more than the maximum. +A tool can ask for fewer rows or a shorter timeout, never for more than the maximum. Rows also stop at the [answer size limit](/developers/mcp-tools#answer-size), whatever the row limit. ## Connecting a client @@ -56,6 +56,12 @@ Ask** stops the prompt from waiting for someone who is not there. Approvals alre 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). +A call that spans connections never asks. Searching query history or listing open tabs without +naming a connection covers only the connections the client reaches without a question: every one at +**Never Ask**, and otherwise those whose AI policy is **Always Allow**, plus, at **Ask Once for Each +Connection**, the ones you already allowed for that client. A call that names the connection asks as +usual. + 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 **Never** is refused, and [Safe Mode](/features/safe-mode#external-clients) still confirms diff --git a/features/safe-mode.mdx b/features/safe-mode.mdx index f16f6ee..368ee92 100644 --- a/features/safe-mode.mdx +++ b/features/safe-mode.mdx @@ -52,6 +52,10 @@ It does not sit in front of reading metadata. Loading the sidebar, opening a tab A statement runs as a read only when TablePro can tell for certain that it reads. Anything it cannot tell counts as a write: confirmed at the Alert and Safe Mode levels, blocked at Read-Only. +A read can still call a function that writes, such as `SELECT purge_orders()`. At **Read-Only** on PostgreSQL, PGlite, CockroachDB, KingbaseES, MySQL, MariaDB, SQLite, DuckDB and ClickHouse, the server refuses that write. Every read TablePro runs for you there runs in the engine's own read-only mode: Run, Run Selection, Run All, Explain, opening a table or view with its row counts and page turns, Fetch All, exports, Transfer, Data Compare, Copy Objects and dashboard tiles. Run All then opens no transaction of its own, and a SQL export reads table by table with no snapshot across tables. DuckDB and KingbaseES do this once their plugin in **Settings > Extensions** is updated for this release. + +Oracle, Dameng and OceanBase have no such mode, and their functions can write. At **Read-Only** there, a query that calls a function outside TablePro's list of built-ins asks before it runs, and is refused when a [configuration profile](#managed-by-an-organization) holds the connection at Read-Only. A raw filter asks once, the filter of an export, a Transfer, a Data Compare or a Copy Objects asks before any row is read, and the automatic row count of such a browse shows no total. A function called without parentheses, which Oracle and Dameng allow, looks like a column and is not asked about. + `EXPLAIN` and `DESCRIBE` are reads until an option runs the statement. With `ANALYZE` they count as the statement they explain, so `EXPLAIN ANALYZE` of a `SELECT` is a read and of a `DELETE` is a write. An option TablePro does not recognize, or one in quotes, counts as running the statement, and an `EXPLAIN` whose statement cannot be found counts as a write. `ANALYZE` of a table stores statistics and is a write. On MongoDB, a read is one call on a collection or database with literal arguments, such as `db.orders.find({status: "open"}).sort({at: -1}).limit(50)`, an `aggregate` pipeline without `$out` or `$merge`, `countDocuments`, `distinct`, `explain`, `show collections` and `use`. Any other JavaScript counts as a write: a variable, a function, `forEach`, `runCommand`. Run several reads at once and each one is checked. Shell state lasts as long as the connection, so a function you redefine in one statement runs redefined in every later one. A read still cannot write through it: the MongoDB driver refuses any write while it runs a statement as a read, once the plugin in **Settings > Extensions** is updated for this release. @@ -79,7 +83,7 @@ There is no session-only override. A change here writes back to the saved connec ## Server read-only is not Safe Mode -Safe Mode runs inside TablePro. It cannot make a server accept a write the server itself refuses, and the wording tells you which one refused. "Cannot execute write queries: TablePro's Safe Mode is set to read-only for this connection" is the app. Anything else is the server, and the usual causes are these: +Safe Mode runs inside TablePro. It cannot make a server accept a write the server itself refuses, and the wording tells you which one refused. "Cannot execute write queries: TablePro's Safe Mode is set to read-only for this connection" is the app. "Safe Mode is set to Read-Only for this connection, and the database refused the statement" is the server refusing a write inside the read-only mode that [Read-Only](#what-counts-as-a-read) runs in, with the server's own message as the detail. Anything else is the server alone, and the usual causes are these: - You are connected to a read replica or a reader endpoint rather than the primary. - The server runs with `read_only` or `super_read_only` turned on. @@ -96,6 +100,8 @@ SHOW SESSION VARIABLES WHERE Variable_name IN `innodb_read_only` set to `ON` means you are on a replica. Connect to the primary to write. +Running in the engine's read-only mode changes a few things at **Read-Only**. PostgreSQL and MySQL refuse `SELECT ... FOR UPDATE` and `FOR SHARE`, and add a begin and a rollback round trip to each statement. A `SET` or `set_config` that a function runs is undone after the statement. While the session holds an open transaction, a read is refused until you roll it back; SQLite reads inside the transaction instead. + ## Execution log TablePro records each authorization decision, allowed or refused, to a local log: the time, the connection, the kind of operation, whether it was a write, and the outcome. The statement is stored as a SHA-256 digest, so the log is not a second copy of your data. Each record carries the hash of the one before it, so recomputing the chain shows whether a record was edited, reordered or removed. From d90f71efc306c78ec481146d5a13ca44da25c242 Mon Sep 17 00:00:00 2001 From: Ngo Quoc Dat Date: Fri, 13 Nov 2026 02:24:02 +0700 Subject: [PATCH 2/2] docs(features): Edit refuses schema and session statements, Read-Only blocks unclassifiable reads --- developers/mcp-tools.mdx | 2 ++ features/ai-assistant.mdx | 4 ++-- features/safe-mode.mdx | 4 ++-- ios/index.mdx | 2 +- 4 files changed, 7 insertions(+), 5 deletions(-) diff --git a/developers/mcp-tools.mdx b/developers/mcp-tools.mdx index 31e9e71..cfa637b 100644 --- a/developers/mcp-tools.mdx +++ b/developers/mcp-tools.mdx @@ -49,6 +49,8 @@ A call that opens a connection may also need approval on the Mac for a pre-conne **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). On SQL Server, an `IF`, `WHILE` or `BEGIN ... END` block holding one statement counts as one statement; a block holding more is multiple statements. +At Safe Mode **Read-Only**, a read that calls a function TablePro cannot tell from a write is refused with `denied` on the engines [Safe Mode](/features/safe-mode#what-counts-as-a-read) names, whatever the token carries and whoever approved the call. + ## 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. diff --git a/features/ai-assistant.mdx b/features/ai-assistant.mdx index 4e29da9..d7166fe 100644 --- a/features/ai-assistant.mdx +++ b/features/ai-assistant.mdx @@ -87,7 +87,7 @@ The mode picker in the composer footer controls which tools the AI can call. It | Mode | Tools available | When to use | |------|----------------|-------------| | **Ask** | Read-only schema lookups: `list_connections` (this conversation's connection only), `get_connection_status`, `list_databases`, `list_schemas`, `list_tables`, `describe_table`, `get_table_ddl`. | Questions, exploration, drafting queries you run yourself. | -| **Edit** | All Ask tools, plus `execute_query` for any statement that is not destructive. The model is told to keep to `SELECT`, `INSERT`, `UPDATE` and `DELETE` and leave schema, privilege and session changes to Agent mode, but Edit refuses only destructive statements. See [external query rules](/developers#what-read-only-allows). | Letting the AI run the queries it proposes. | +| **Edit** | All Ask tools, plus `execute_query` for queries and data changes: `SELECT`, `INSERT`, `UPDATE`, `DELETE`, `MERGE`. On a SQL database and on DynamoDB it refuses schema, privilege, session and transaction statements, such as `CREATE`, `ALTER`, `GRANT`, `SET` and `BEGIN`, and changes to the database's own tables, such as `pg_settings` or `mysql.user`; run those in Agent mode or a query tab. A function a query calls is not read, so it runs whatever it does. Destructive statements stay blocked. On an engine with a query language of its own, such as MongoDB, Redis, Neo4j, SurrealDB or Kafka, Edit refuses only destructive statements. See [external query rules](/developers#what-read-only-allows). | Letting the AI run the queries it proposes. | | **Agent** | All tools, plus `confirm_destructive_operation` for destructive statements. Runs tools in a loop. | Multi-step migrations and schema changes. | Mode and [Safe Mode](/features/safe-mode) are independent gates. Agent mode does not bypass Safe Mode. @@ -101,7 +101,7 @@ In Edit and Agent modes each tool call appears as a card in the reply. Read-only Per-card tool approval -Safe Mode **Silent** auto-approves write tools and **Read-Only** auto-denies them. Destructive operations are the exception: `confirm_destructive_operation` always needs a click, Silent does not auto-approve it, its card has no **Always Allow**, and the model must pass the verbatim phrase `I understand this is irreversible`. +Safe Mode **Silent** auto-approves write tools and **Read-Only** auto-denies them, an **Always Allow** one too. Destructive operations are the exception: `confirm_destructive_operation` always needs a click, Silent does not auto-approve it, its card has no **Always Allow**, and the model must pass the verbatim phrase `I understand this is irreversible`. **Stop Generating** does not stop a write the database is already running. The write runs to the end, and the tool result in the reply says it may have been applied: check before you run it again. diff --git a/features/safe-mode.mdx b/features/safe-mode.mdx index 368ee92..da67ccc 100644 --- a/features/safe-mode.mdx +++ b/features/safe-mode.mdx @@ -24,7 +24,7 @@ Four things the table cannot carry. The confirmation dialog shows the whole stat Confirmation dialog over a query tab, showing a fourteen line UPDATE with Cancel and Execute Confirmation dialog over a query tab, showing a fourteen line UPDATE with Cancel and Execute - **Silent** is not a free pass: `DROP`, `TRUNCATE`, `CREATE OR REPLACE` of a table, schema or database, and a `DELETE` with no `WHERE` still raise the built-in dangerous query warning even there. So does a [Structure](/features/table-structure#saving-changes) save that drops a column, changes a column's type or character set, adds NOT NULL, changes the primary key, adds or rewrites a check constraint, converts a table's existing columns to another character set, or removes a MongoDB field. And **Read-Only** goes past queries to the interface itself, disabling inline cell editing, adding, deleting and duplicating rows, table truncate and drop, and import. + **Silent** is not a free pass: `DROP`, `TRUNCATE`, `CREATE OR REPLACE` of a table, schema or database, `INSERT OVERWRITE`, and a `DELETE` with no `WHERE` still raise the built-in dangerous query warning even there. So does a [Structure](/features/table-structure#saving-changes) save that drops a column, changes a column's type or character set, adds NOT NULL, changes the primary key, adds or rewrites a check constraint, converts a table's existing columns to another character set, or removes a MongoDB field. And **Read-Only** goes past queries to the interface itself, disabling inline cell editing, adding, deleting and duplicating rows, table truncate and drop, and import. ## Connections that are always read-only @@ -54,7 +54,7 @@ A statement runs as a read only when TablePro can tell for certain that it reads A read can still call a function that writes, such as `SELECT purge_orders()`. At **Read-Only** on PostgreSQL, PGlite, CockroachDB, KingbaseES, MySQL, MariaDB, SQLite, DuckDB and ClickHouse, the server refuses that write. Every read TablePro runs for you there runs in the engine's own read-only mode: Run, Run Selection, Run All, Explain, opening a table or view with its row counts and page turns, Fetch All, exports, Transfer, Data Compare, Copy Objects and dashboard tiles. Run All then opens no transaction of its own, and a SQL export reads table by table with no snapshot across tables. DuckDB and KingbaseES do this once their plugin in **Settings > Extensions** is updated for this release. -Oracle, Dameng and OceanBase have no such mode, and their functions can write. At **Read-Only** there, a query that calls a function outside TablePro's list of built-ins asks before it runs, and is refused when a [configuration profile](#managed-by-an-organization) holds the connection at Read-Only. A raw filter asks once, the filter of an export, a Transfer, a Data Compare or a Copy Objects asks before any row is read, and the automatic row count of such a browse shows no total. A function called without parentheses, which Oracle and Dameng allow, looks like a column and is not asked about. +Oracle, Dameng and OceanBase have no such mode, and their functions can write. At **Read-Only** there, a query that calls a function outside TablePro's list of built-ins is blocked, and so is a raw filter or the filter of an export, a Transfer, a Data Compare or a Copy Objects, before any row is read. The message names the level to switch to: **Alert**, or the lowest level a [configuration profile](#managed-by-an-organization) or Agent mode still offers, and it says the level is held when nothing below Read-Only is offered. Below Read-Only the query counts as a read, so only the two Full levels ask before it runs. The automatic row count of such a browse shows no total. A function called without parentheses, which Oracle and Dameng allow, looks like a column and is not blocked. `EXPLAIN` and `DESCRIBE` are reads until an option runs the statement. With `ANALYZE` they count as the statement they explain, so `EXPLAIN ANALYZE` of a `SELECT` is a read and of a `DELETE` is a write. An option TablePro does not recognize, or one in quotes, counts as running the statement, and an `EXPLAIN` whose statement cannot be found counts as a write. `ANALYZE` of a table stores statistics and is a write. diff --git a/ios/index.mdx b/ios/index.mdx index cbb1477..f0baee0 100644 --- a/ios/index.mdx +++ b/ios/index.mdx @@ -283,7 +283,7 @@ The **Status** row in **Info** uses the same words: **Connected**, **Not Connect Turn on Face ID, Touch ID, or Optic ID under **Settings > Security**. A cold launch always asks, and the connection from your last session waits behind that question: no connecting screen, no host key prompt, nothing dialed until you authenticate. After that **Auto-Lock** relocks immediately or after 1, 5, 15, or 60 minutes idle, starting at 5. The lock covers open sheets and connections, and the app switcher shows a locked card instead of your data; a connection open underneath stays connected. Turning the lock off asks you to authenticate first. -Each connection carries its own [safe mode](/features/safe-mode) level, synced from the Mac. Set it with **Safe Mode** under **Organization** in the connection's form. iOS has three: **Off**, **Confirm Writes**, and **Read-Only**, which refuses writes outright. **Default Safe Mode** under **Settings > New Connections** sets the level a new connection starts at. +Each connection carries its own [safe mode](/features/safe-mode) level, synced from the Mac. Set it with **Safe Mode** under **Organization** in the connection's form. iOS has three: **Off**, **Confirm Writes**, and **Read-Only**, which refuses writes outright. On PostgreSQL, MySQL, MariaDB, OceanBase and Oracle, Read-Only also refuses a query that calls a function outside TablePro's list of built-ins, since such a function can write; switch to **Confirm Writes** to run it. **Default Safe Mode** under **Settings > New Connections** sets the level a new connection starts at. SSH tunnels authenticate with a password, a private key or **Keyboard Interactive**. A tunnel set to **SSH Agent** on the Mac signs in here with a private key on this device and stays **SSH Agent** on the Mac. When the server asks for more, after the password or key or through keyboard-interactive, a password prompt gets the SSH password and a code prompt gets the code from **Two-Factor Authentication**. Any other question, or a code in **Prompt at Connect** mode, appears on the connection's screen for you to answer. **Auto Generate** takes the Base32 secret from your authenticator setup with its algorithm, digits and period, and shares them with the Mac; a tunnel that follows a Mac SSH profile uses the profile's. A private key on a security key does not work here, and the **SSH Sign-In Unavailable** alert says so. An unknown host key, the SSH server's or a jump host's, prompts with its fingerprint first, on the connection's own screen. The question waits there until you answer it, and leaving the screen ends that attempt. A key pasted under **Paste Key**, or picked as a text file, is kept in the Keychain beside the connection's passwords, never in the saved connection list. A key file that is not text is copied into the app and read from there. Setting **Auth Method** to **Password**, choosing **Import File**, or turning **SSH Tunnel** off deletes the saved key when you tap **Save**. A tunnel the Mac forwards to a unix socket on the server forwards to the same socket here. Turning the tunnel off keeps its other settings, here and on the Mac, for when you turn it back on. A tunnel that drops while the connection is open reconnects it, as returning to the app does; see [When the connection drops](#when-the-connection-drops).