diff --git a/connections/connection-form.mdx b/connections/connection-form.mdx index 28e4310..4ae77c4 100644 --- a/connections/connection-form.mdx +++ b/connections/connection-form.mdx @@ -83,7 +83,7 @@ Encryption sits below the transport. [SSL/TLS](/connections/ssl) covers the mode | **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) | | **Manual Commit** | Off by default. On, the first change opens a transaction and nothing is saved until you commit it. **Database > Manual Commit** is the same setting. Dimmed on engines that commit schema changes on their own. See [Manual Commit](/features/sql-editor#manual-commit) | -| **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 ef2468b..a698534 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,7 +190,7 @@ 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 statement runs on the user's own session, inside any transaction it holds. `execute_query`, `confirm_destructive_operation` and [`insert_rows`](#writing-data) follow these rules about it: @@ -194,12 +205,16 @@ A batch that raises an error fails the call with the server's message and line n ### `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 | @@ -267,13 +282,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 00284d4..81b5dca 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.