dsh-db-mcp 0.6.5 → 0.6.9

package/README.md

@@ -2,6 +2,8 @@
 
 [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
 
+English | [中文](README.zh.md)
+
 DSH plugin that adds a **Database** entry to the sidebar with a data-source
 management panel, backed by a Python MCP server that lets the agent query those
 databases through tools (not through the page).
@@ -11,39 +13,44 @@ databases through tools (not through the page).
   and never come back to the page.
 - Import the connections DBeaver already has, including its encrypted passwords.
 - Read-only by default, with two independent write gates and an audit log.
-- The agent gets seven MCP tools, not a SQL editor in the UI.
+- The agent gets eight MCP tools, not a SQL editor in the UI.
 
 Requirements and staged plan: [`docs/requirements.md`](docs/requirements.md).
 
 ## What exists today (P7)
 
-- **Host half** (`index.js` 鈫?`src/host.js`): a Cordis plugin serving
+- **Host half** (`index.js` → `src/host.js`): a Cordis plugin serving
   `/plugins/db-mcp/api` from the DSH web server.
+
   | Route | Purpose |
   | ----- | ------- |
   | `GET /health` | plugin version, Host facts, Python discovery, runtime paths, registry state, MCP status, settings |
   | `GET /datasources` | registry, credentials projected away |
   | `GET /schema?datasource=…&table=…[&schema=…]` | read-only structure: tables, or the columns of one table |
+  | `GET /groups` | declared groups plus every group label in use |
   | `GET /dbeaver/scan` | connections already configured in DBeaver |
   | `GET /mcp/status` | Python server phase, tool list, last error, stderr tail |
-  | `GET /settings` 路 `POST /settings` | global write switch and audit switch |
+  | `GET /settings` · `POST /settings` | global write switch and audit switch |
   | `GET /audit?limit=N` | the tail of the tool-call audit log |
   | `GET /python/env` | interpreter, venv path, installed driver versions |
   | `POST /python/setup` | create the venv and `pip install -r server/requirements.txt` |
   | `POST /datasources/save` | create or update a source (`id` is immutable) |
   | `POST /datasources/delete` | remove a source and its stored secret |
   | `POST /datasources/test` | real login probe: SQLite over `node:sqlite`, the rest through the Python drivers |
+  | `POST /datasources/bulk` | test / read-only / group / delete a set of sources |
+  | `POST /groups/save` · `POST /groups/delete` | create, rename or delete a group |
   | `POST /dbeaver/import` | copy selected DBeaver connections into the registry |
-  | `POST /mcp/start` 路 `POST /mcp/restart` | start or restart the Python MCP server |
+  | `POST /mcp/start` · `POST /mcp/restart` | start or restart the Python MCP server |
   | `POST /mcp/call` | dev helper: call one MCP tool through the panel |
   | `POST /reload` | dev helper: re-import `src/host.js` without restarting DSH |
+
 - **Client half** (`client.js`): sidebar entry (`db-mcp`, order 25) plus the main
   panel with the source list, the minimal create/edit form (one connection string),
   test/delete/default actions, a read-only *structure* browser, the DBeaver import
   flow, a *Restart MCP* button, the runtime diagnostics card (tool count, global
   write switch, venv and package versions with a one-click install) and an
   *audit log* card. Copy is localized (zh/en) through the client `locale` service.
-- **Python server** (`server/`): `main.py` (FastMCP, seven tools), `engines.py`
+- **Python server** (`server/`): `main.py` (FastMCP, eight tools), `engines.py`
   (per-engine connect/introspect/query), `store.py` (reads the registry).
   The plugin spawns it over stdio and publishes its tools as `mcp__db__*` on the
   host `tools` service — it does not go through a `dsh-mcp-client` Loader row.
@@ -65,7 +72,7 @@ Requirements and staged plan: [`docs/requirements.md`](docs/requirements.md).
 
 ### Python environment
 
-Interpreter discovery order: plugin config `pythonPath` 鈫?`<DSH_HOME>/db-mcp/.venv/Scripts/python.exe` 鈫?that venv on POSIX 鈫?`python` 鈫?`python3`. Dependencies live in the runtime venv, not in the package:
+Interpreter discovery order: plugin config `pythonPath` → `<DSH_HOME>/db-mcp/.venv/Scripts/python.exe` → that venv on POSIX → `python` → `python3`. Dependencies live in the runtime venv, not in the package:
 
     python -m venv C:\Users\<you>\.dsh\db-mcp\.venv
     C:\Users\<you>\.dsh\db-mcp\.venv\Scripts\python.exe -m pip install -r server\requirements.txt
@@ -81,14 +88,14 @@ panel row then shows the server banner, the connected user and database, and how
 long the login took, for example:
 
 ```
-Oracle AI Database 26ai Free Release 23.26.3.0.0 路 DEMO@FREEPDB1 路 select 1 from dual ok
-PostgreSQL 15.19 路 demo@demo 路 select version() ok
-MySQL 8.0.46 路 demo@%@demo 路 select version() ok
+Oracle AI Database 26ai Free Release 23.26.3.0.0 · DEMO@FREEPDB1 · select 1 from dual ok
+PostgreSQL 15.19 · demo@demo · select version() ok
+MySQL 8.0.46 · demo@%@demo · select version() ok
 ```
 
 A wrong password or an unreachable listener now surfaces the driver's own
 message (`ORA-01017`, `DPY-6005`, `password authentication failed` — instead of
-"port reachable". Testing an unsaved form works too: `test_connection` accepts
+"port reachable"). Testing an unsaved form works too: `test_connection` accepts
 `kind` + `config` + `password` without writing the registry first. When the
 Python server cannot start, the probe degrades to a TCP check and says so.
 
@@ -149,9 +156,9 @@ file path), and a DBeaver entry that matches one of them comes back with
 its checkbox and says *already added as …*; `POST /dbeaver/import` reports such
 ids under `skipped` instead of creating a second copy.
 
-The panel navigates with a tab bar (`数据源列表 / 新建数据源 / 从 DBeaver 导入`): the trailing step
-is plain text, every earlier step is a link back, and no page needs a separate
-"back to list" button.
+The panel navigates with a tab bar (*Data source list / New data source /
+Import from DBeaver / Runtime / Audit log*): the active step is plain text, every
+earlier step is a link back, and no page needs a separate "back to list" button.
 
 ## Test databases in Docker
 
@@ -191,8 +198,14 @@ Then create a source in the panel with the matching connection string, e.g.
 plugin_manager install_bundle  target=<absolute path to this directory>
 ```
 
+or, from npm:
+
+```
+dsh plugin add dsh-db-mcp@latest
+```
+
 The bundle patch (`cordis.patch.yml`) inserts one Loader row with id `db-mcp`.
-The profile links this directory, so file edits are live; the Host module is
+A profile that links this directory keeps file edits live; the Host module is
 imported once per process, hence `POST /plugins/db-mcp/api/reload` (or an app
 restart) after changing `src/host.js`.
 
@@ -200,18 +213,21 @@ restart) after changing `src/host.js`.
 
 The page follows the same chrome as the other first-party panels:
 
-- a masthead with **‹ 返回会话** (closes the panel through `ctx.layout.selectPanel(null)`),
-  the `数据库` title, and the connection/version pills;
-- a tab row — **数据源列表 / 新建数据源 / 从 DBeaver 导入 / 运行时诊断 / 审计日志** — with
-  the active tab underlined;
+- a masthead with **‹ Back to chat** (closes the panel through
+  `ctx.layout.selectPanel(null)`), the **Database** title, and the
+  connection/version pills;
+- a tab row — **Data source list / New data source / Import from DBeaver /
+  Runtime / Audit log** — with the active tab underlined.
 
-Picking **新建数据源** or **从 DBeaver 导入** swaps only the card below the tabs — the
-masthead and the tabs stay put. Editing reuses the **新建数据源** tab; the structure
-browser is a sub-view of **数据源列表** with its own `← 数据源` link. There is no second
-action bar: **刷新** and **重启 MCP** sit in the source-list card header, and the list
-itself owns the group tools.
+Picking **New data source** or **Import from DBeaver** swaps only the card below
+the tabs — the masthead and the tabs stay put. Editing reuses the **New data
+source** tab; the structure browser is a sub-view of **Data source list** with
+its own `← Sources` link. There is no second action bar: **Refresh** and
+**Restart MCP** sit in the source-list card header, and the list itself owns the
+group tools.
 
 ## Schema overview
+
 The **Structure** button on a source row opens a read-only browser: the tables
 (or views) of that source on the left, and the columns of the selected table on
 the right — name, type, nullability, default value and primary-key marker. It is
@@ -223,19 +239,20 @@ open reads the live catalog.
 
 Every source carries an optional **group** label (`group` in the registry,
 editable under *More settings*). Groups are user-owned: type a name in the
-**新建分组** box to create one, **double-click a group name to rename it** (or the
-trash button to delete the group), and drag a source row onto a group to move it
-there (drag it onto **未分组** to clear the label). Double-clicking a source name
-renames just that source — its id never changes. The list renders one section per
-group, sorted by name with the ungrouped sources last; while no group exists the
-list keeps its flat look.
-
-Each group header carries a select-all box, so sources inside a group take part in
-bulk work exactly like loose ones. Tick any row (or click its text) to open the
-bulk bar: test all selected sources, flip them to read-only or writable, move them
-into a group, or delete them (two-step confirmation). Bulk moves go through
-`POST /datasources/bulk` with `{ action: 'test' | 'readOnly' | 'group' | 'delete', ids: [...], … }`,
-while group CRUD uses `GET /groups`, `POST /groups/save` and `POST /groups/delete`.
+**New group** box to create one, **double-click a group name to rename it** (or
+the delete button to drop the group), and drag a source row onto a group to move
+it there (drag it onto **Ungrouped** to clear the label). Double-clicking a
+source name renames just that source — its id never changes. The list renders one
+section per group, sorted by name with the ungrouped sources last; while no group
+exists the list keeps its flat look.
+
+Each group header carries a select-all box, so sources inside a group take part
+in bulk work exactly like loose ones. Tick any row to open the bulk bar: test all
+selected sources, flip them to read-only or writable, move them into a group, or
+delete them (two-step confirmation). Bulk moves go through
+`POST /datasources/bulk` with
+`{ action: 'test' | 'readOnly' | 'group' | 'delete', ids: [...], … }`, while group
+CRUD uses `GET /groups`, `POST /groups/save` and `POST /groups/delete`.
 
 ## Releasing
 
@@ -257,17 +274,22 @@ release, before a trusted publisher exists for the package.
 ## Development
 
 ```
-node dev/selftest.mjs     # mounts src/host.js on a throwaway port, 42 checks
+node dev/engines.test.mjs # 11 checks: engines.py commit/rollback + affectedRows, stub connection
+node dev/selftest.mjs     # mounts src/host.js on a throwaway port, 46 checks
 node dev/shims.test.mjs   # mounts index.js, checks routes, /reload, tool publication
 node dev/parse.test.mjs   # 24 checks: connection-string parser (DSN/JDBC/TNS/paths)
-node dev/render.test.mjs  # 37 checks: components render with a stub React
+node dev/render.test.mjs  # 40 checks: components and the result renderer, stub React
 node dev/i18n.test.mjs    # 12 checks: en/zh parity, no dead keys, no stray copy
 node dev/p5.test.mjs      # 15 checks: settings, audit log, python environment
 node dev/mcp.test.mjs     # 19 checks: real Python server over stdio, real SQLite + Oracle logins
 ```
 
 `npm test` runs everything except `mcp.test.mjs`, which needs the venv and the
-Oracle container. `node dev/bump.mjs 0.6.2` updates both version strings.
+Oracle container. `dev/engines.test.mjs` needs a Python interpreter (the plugin
+venv, else `python` on PATH) but no database: it drives `server/engines.py`
+against a stub DB-API connection, covering the commit/rollback and
+`affectedRows` contract of `run_query`. `node dev/bump.mjs 0.6.6` updates both
+version strings.
 
 ## Safety switches
 
@@ -278,6 +300,9 @@ Two independent gates decide whether a statement may write:
    with `user_error` and a hint pointing at the switch.
 2. **Per-source flag** — `readOnly` on the data source, on by default. A source
    stays read-only even when the global switch is on until you clear its flag.
+   Click the *read-only* / *writable* pill on a source row to flip it in one
+   click; the pill turns amber while that source accepts writes, and the notice
+   reminds you when the global switch is still off.
 
 The Python server reads the global flag from `DB_MCP_ALLOW_WRITE` at start-up; the
 host restarts it whenever the switch flips. Read-only is also enforced by the
@@ -285,13 +310,30 @@ driver itself where the engine allows it (`mode=ro` for SQLite,
 `default_transaction_read_only` for PostgreSQL, `SET SESSION TRANSACTION READ ONLY`
 for MySQL).
 
+### What the plugin runs, and with what
+
+- The Python server is started with a fixed interpreter path, a fixed script and a
+  fixed argument list — never through a shell, so no string is ever re-parsed by
+  `cmd.exe` or `/bin/sh`.
+- The child does **not** inherit the host environment. It gets a short allowlist
+  (`PATH`, `TEMP`, `HOME`, `PYTHON*`, and similar) plus the three `DB_MCP_*` flags
+  the plugin sets. Tokens or cloud credentials in the DSH process are not passed
+  down.
+- Connections to PostgreSQL, MySQL and Oracle are opened by that child; only SQLite
+  is read in-process. The raw TCP probe is a fallback used when the child cannot
+  start, and it never sends credentials.
+- Passwords live in `secrets.json` (mode `0600`) and are never returned by any HTTP
+  route; the panel only learns `hasSecret`.
+
 ## Audit log
 
 Every MCP tool call appends one JSON line to `<runtime>/logs/audit.jsonl` (0600):
 time, tool, source, duration, row count, the SQL truncated to 2000 characters and
 the error when it failed. Result rows are never logged. The file rotates to
 `audit.1.jsonl` at 512 KiB and logging can be turned off with `auditLog: false` in
-`settings.json`. The panel shows the last dozen entries.
+`settings.json`. The panel shows the last dozen entries on **your own clock** —
+the file keeps UTC so it stays comparable across machines, the card converts each
+stamp to the viewer's time zone and prints the offset it used.
 
 `dev/shims.test.mjs` also asserts that `package.json` has no UTF-8 BOM: the host
 parses it with `JSON.parse`, which rejects a BOM, and the plugin then shows up as
@@ -309,7 +351,7 @@ first.
 | P4 | PostgreSQL / MySQL / Oracle dialects (done) |
 | P5 | diagnostics, one-click venv, reload, audit log, global write switch (done) |
 | P6 | i18n polish and docs (done) |
-| P7 | read-only schema overview (done) |
+| P7 | read-only schema overview, groups, bulk actions (done) |
 
 ## License
 

package/README.zh.md

@@ -0,0 +1,252 @@
+# dsh-db-mcp
+
+[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+
+[English](README.md) | 中文
+
+一个 DSH 插件：在侧边栏加一个 **数据库** 入口，配一个数据源管理面板，背后是 Python 写的 MCP 服务——让智能体通过工具查询这些数据库，而不是在页面里执行 SQL。
+
+- 一个面板管四种引擎：SQLite、PostgreSQL、MySQL、Oracle。
+- 一条连接串填满整张表单；口令只存在本机，永不回传给页面。
+- 可以把 DBeaver 里已有的连接（连同它加密保存的口令）直接导入。
+- 默认只读，两道互相独立的写闸门，加一份审计日志。
+- 给智能体的是 8 个 MCP 工具，界面里没有 SQL 编辑器。
+
+需求与阶段计划见 [`docs/requirements.md`](docs/requirements.md)。
+
+## 现在有什么（P7）
+
+- **Host 半边**（`index.js` → `src/host.js`）：一个 Cordis 插件，通过 DSH 的 web server 提供 `/plugins/db-mcp/api`。
+
+  | 路由 | 用途 |
+  | ---- | ---- |
+  | `GET /health` | 插件版本、Host 信息、Python 探测、运行时路径、注册表状态、MCP 状态、设置 |
+  | `GET /datasources` | 注册表，口令字段已剔除 |
+  | `GET /schema?datasource=…&table=…[&schema=…]` | 只读结构：表清单，或某张表的列 |
+  | `GET /groups` | 已声明的分组，加上所有正在使用的分组名 |
+  | `GET /dbeaver/scan` | DBeaver 里已配置的连接 |
+  | `GET /mcp/status` | Python 服务所处阶段、工具清单、最后的错误、stderr 尾部 |
+  | `GET /settings` · `POST /settings` | 全局写开关与审计开关 |
+  | `GET /audit?limit=N` | 工具调用审计日志的末尾若干条 |
+  | `GET /python/env` | 解释器、venv 路径、已安装的驱动版本 |
+  | `POST /python/setup` | 建 venv 并 `pip install -r server/requirements.txt` |
+  | `POST /datasources/save` | 新建或更新数据源（`id` 不可改） |
+  | `POST /datasources/delete` | 删除数据源及其口令 |
+  | `POST /datasources/test` | 真实登录探测：SQLite 走 `node:sqlite`，其余走 Python 驱动 |
+  | `POST /datasources/bulk` | 对一批数据源做 测试 / 只读 / 分组 / 删除 |
+  | `POST /groups/save` · `POST /groups/delete` | 新建、重命名、删除分组 |
+  | `POST /dbeaver/import` | 把选中的 DBeaver 连接复制进注册表 |
+  | `POST /mcp/start` · `POST /mcp/restart` | 启动或重启 Python MCP 服务 |
+  | `POST /mcp/call` | 开发辅助：经面板调用某个 MCP 工具 |
+  | `POST /reload` | 开发辅助：不重启 DSH 重新导入 `src/host.js` |
+
+- **Client 半边**（`client.js`）：侧边栏入口（`db-mcp`，order 25）加主面板——数据源列表、极简的新建/编辑表单（一条连接串）、测试/删除/设为默认、只读的「结构」浏览、DBeaver 导入流程、「重启 MCP」按钮、运行时诊断卡（工具数、全局写开关、venv 与依赖版本及一键安装）、以及「审计日志」卡。文案经客户端 `locale` 服务做中英本地化。
+- **Python 服务**（`server/`）：`main.py`（FastMCP，8 个工具）、`engines.py`（按引擎连接/内省/查询）、`store.py`（读注册表）。插件用 stdio 拉起它，把它的工具以 `mcp__db__*` 发布到 Host 的 `tools` 服务上——**不**经过 `dsh-mcp-client` 的 Loader 行。
+
+### 智能体拿到的工具
+
+| 工具 | 用途 |
+| ---- | ---- |
+| `mcp__db__list_datasources` | 已登记的数据源（id、类型、目标、是否只读） |
+| `mcp__db__list_tables` | 某个数据源的表/视图 |
+| `mcp__db__describe_table` | 列、类型、是否可空、主键 |
+| `mcp__db__sample_rows` | 某张表的少量样本 |
+| `mcp__db__run_query` | 执行一条语句；只读源拒绝写 |
+| `mcp__db__explain_query` | 查询计划 |
+| `mcp__db__get_ddl` | `CREATE TABLE` 语句（SQLite 取原文，其余按目录重建） |
+| `mcp__db__test_connection` | 真实登录、执行 `select 1`、回报服务器/用户/模式 |
+
+`datasource` 处处可选：不填就用默认数据源。
+
+### Python 环境
+
+解释器探测顺序：插件配置 `pythonPath` → `<DSH_HOME>/db-mcp/.venv/Scripts/python.exe` → POSIX 上的同一个 venv → `python` → `python3`。依赖装在运行时 venv 里，不随包分发：
+
+    python -m venv C:\Users\<you>\.dsh\db-mcp\.venv
+    C:\Users\<you>\.dsh\db-mcp\.venv\Scripts\python.exe -m pip install -r server\requirements.txt
+
+`mcp` 必须固定在 1.x（2.x 把 `FastMCP` 改名成了 `MCPServer`）。
+
+## 「测试」按钮是真的登录吗？
+
+是。PostgreSQL、MySQL、Oracle 的 **测试** 走 `mcp__db__test_connection`，经 Python MCP 服务执行一次真实认证登录加 `select 1`（Oracle 用 `select 1 from dual`）。列表行随后显示服务器横幅、登录用户与库名、以及登录耗时，例如：
+
+```
+Oracle AI Database 26ai Free Release 23.26.3.0.0 · DEMO@FREEPDB1 · select 1 from dual ok
+PostgreSQL 15.19 · demo@demo · select version() ok
+MySQL 8.0.46 · demo@%@demo · select version() ok
+```
+
+口令错误或端口不通时，显示的是驱动自己的信息（`ORA-01017`、`DPY-6005`、`password authentication failed`），而不是笼统的「端口可达」。未保存的表单也能测：`test_connection` 接受 `kind` + `config` + `password`，不需要先写注册表。Python 服务起不来时，探测退回 TCP 检查，并明确说明这一点。
+
+## 一条连接串填完整张表单
+
+新建/编辑表单刻意做得和 DBeaver 的连接对话框一样小：**连接串**、**用户**、**口令**（带「保存密码」勾选），就这些。粘贴 JDBC URL、DSN、Oracle TNS 描述符或 `.db` 路径，类型、主机、端口、库名/服务名、名称与标识符都会自动带出；推导出来的值默认收在「更多设置」里，与模式、SID、SSL 模式、字符集、只读开关放在一起。
+
+支持的写法（完整矩阵见 `dev/parse.test.mjs`）：
+
+```
+postgresql://alice:secret@db.example.com:6543/orders?sslmode=require
+jdbc:postgresql://localhost:5432/appdb
+mysql://root:pw@127.0.0.1:3306/shop?charset=utf8mb4
+jdbc:mariadb://10.0.0.5:3307/legacy
+oracle://system:oracle@localhost:1521/XEPDB1
+jdbc:oracle:thin:@//ora:1521/ORCLPDB1        # 服务名
+jdbc:oracle:thin:@ora:1521:ORCL              # SID
+(DESCRIPTION=(ADDRESS=(HOST=tns-host)(PORT=1522))(CONNECT_DATA=(SERVICE_NAME=svc1)))
+jdbc:sqlite:C:\data\app.db
+sqlite:///C:/data/chinook.db
+C:\data\app.db          /  /var/lib/app.sqlite3
+```
+
+连接串里的口令只发送一次给 `POST /datasources/save`，之后只存在 `secrets.json` 里，永不回显。
+
+写操作一律用 `POST`（同源校验比较 `Origin` 与 `Host`）。口令不会进 `datasources.json`，只存在 `secrets.json`，页面拿到的唯一信号是 `hasSecret`。
+
+## 从 DBeaver 导入
+
+`GET /dbeaver/scan` 会在 `%APPDATA%\DBeaverData\workspace*\General\.dbeaver\` 下找 `data-sources.json`（同时兼容 `General` 布局与 Linux/macOS 位置）。同级存在 `credentials-config.json` 时，用 DBeaver 内置的密钥解密（AES-128-CBC、零 IV、前 16 字节前缀，参考 `Tatsh/dbeaver-creds`）。从未保存过口令的工作区，导入出来的连接口令为空，界面显示「无密码」。
+
+通过 DBeaver 驱动对话框建的连接，往往只有一条 JDBC URL（`configurationType: URL`），既没有 `database` 字段也没有 `user` 字段。导入器因此会自己解析 `jdbc:mysql://host:port/db`、`jdbc:postgresql://…`、`jdbc:oracle:thin:@…`，补上表单字段缺的部分，并在解密凭据里存了用户名时从那里取。导入的数据源按 DBeaver 连接名命名（再 slug 成 id），保持 `readOnly: true`，已存的口令会复制进 `secrets.json`；仍然缺的东西写进 `warnings`。
+
+已经配置过的连接不会被导入两次：每个数据源用 类型 + 主机 + 端口 + 库名/服务名/SID + 用户 做身份（SQLite 用文件路径），命中的 DBeaver 条目会带上 `alreadyImported: true`、`duplicateId`、`duplicateName` 返回。面板把它的复选框禁用并标注「已作为 … 添加」，`POST /dbeaver/import` 则把这类 id 放进 `skipped`，不会建出第二份。
+
+面板用标签栏导航（*数据源列表 / 新建数据源 / 从 DBeaver 导入 / 运行时诊断 / 审计日志*）：当前步骤是纯文本、可回退的步骤是链接，任何页面都不需要额外的「返回列表」按钮。
+
+## 用 Docker 起测试库
+
+宿主机什么都不用装，下面每个引擎都是用完即弃的容器，演示账号 `demo` / `dbmcp-demo`。
+
+```
+# PostgreSQL —— 镜像最小、启动最快，推荐第一个试
+docker run -d --name dbmcp-pg -p 5432:5432 \
+  -e POSTGRES_USER=demo -e POSTGRES_PASSWORD=dbmcp-demo -e POSTGRES_DB=demo \
+  postgres:15-alpine
+
+# MySQL
+docker run -d --name dbmcp-mysql -p 3306:3306 \
+  -e MYSQL_USER=demo -e MYSQL_PASSWORD=dbmcp-demo -e MYSQL_DATABASE=demo \
+  -e MYSQL_ROOT_PASSWORD=dbmcp-root mysql:8.0-debian
+
+# Oracle Free —— 镜像好几个 GB，要一两分钟才就绪
+docker run -d --name dbmcp-oracle -p 1521:1521 -e ORACLE_PASSWORD=dbmcp-demo \
+  gvenzl/oracle-free:23-slim
+```
+
+Windows 上 1521 常常落在 Hyper-V 的保留端口段里，`docker run` 会报「尝试访问套接字的方式被其访问权限禁止」。用 `netsh interface ipv4 show excludedportrange protocol=tcp` 查一下，换一个宿主端口发布即可，例如 `-p 11521:1521`，数据源里填 11521。
+
+然后在面板里用对应的连接串建数据源，例如
+`postgresql://demo:dbmcp-demo@127.0.0.1:5432/demo`、
+`mysql://demo:dbmcp-demo@127.0.0.1:3306/demo` 或
+`oracle://system:dbmcp-demo@127.0.0.1:1521/FREEPDB1`。
+
+## 装进一个 profile
+
+```
+plugin_manager install_bundle  target=<本目录的绝对路径>
+```
+
+或者从 npm 装：
+
+```
+dsh plugin add dsh-db-mcp@latest
+```
+
+bundle patch（`cordis.patch.yml`）只插入一行 Loader 配置，id 为 `db-mcp`。以链接方式装入的 profile 改文件即生效；Host 模块每个进程只导入一次，所以改完 `src/host.js` 要 `POST /plugins/db-mcp/api/reload`（或重启应用）。
+
+## 面板布局
+
+页面与其它官方面板保持一致的外壳：
+
+- 页头：**‹ 返回会话**（经 `ctx.layout.selectPanel(null)` 关闭面板）、**数据库** 标题，以及连接状态与版本药丸；
+- 标签栏 —— **数据源列表 / 新建数据源 / 从 DBeaver 导入 / 运行时诊断 / 审计日志**，当前标签带下划线。
+
+点「新建数据源」或「从 DBeaver 导入」只切换标签下方那张卡片，页头与标签栏不动。编辑复用「新建数据源」标签；结构浏览是「数据源列表」下的子视图，带自己的 `← 数据源` 链接。没有第二排操作栏：**刷新** 与 **重启 MCP** 在数据源列表卡片的头部，分组相关的操作归列表自己管。
+
+## 结构概览
+
+数据源行上的「结构」按钮打开只读浏览器：左边是该源的表（或视图），右边是选中表的列——名称、类型、可空、默认值、主键标记。数据由 `GET /schema` 提供，它只把 `list_tables` / `describe_table` 转发给 MCP 服务，页面本身永远执行不了 SQL。不缓存：每次打开都读实时目录。
+
+## 分组与批量操作
+
+每个数据源带一个可选的**分组**标签（注册表里的 `group`，可在「更多设置」里改）。分组归用户所有：在「新建分组」框里输入名字即可创建，**双击组名改名**（或按删除按钮删组），把数据源行拖到某个组上即可移过去（拖到「未分组」上则清除标签）。双击数据源名只改这一条的名字，id 永不改变。列表按组渲染成若干区块，组名排序、未分组的排最后；没有分组时列表保持原来的平铺样式。
+
+每个组头都有全选复选框，所以组内的数据源和散在外面的完全一样，都能参与批量操作。勾选任意行即出现批量操作条：批量测试、设为只读或允许写、移动到某个分组、或删除（两步确认）。批量移动走 `POST /datasources/bulk`，body 形如 `{ action: 'test' | 'readOnly' | 'group' | 'delete', ids: [...], … }`；分组的增删改走 `GET /groups`、`POST /groups/save`、`POST /groups/delete`。
+
+## 发布
+
+包由 GitHub Actions 通过 [npm trusted publishing](https://docs.npmjs.com/trusted-publishers) 发布：`.github/workflows/publish.yml` 用 workflow 的 OIDC token 换短期发布凭据，因此仓库里没有任何 `NPM_TOKEN` 密钥。
+
+```bash
+node dev/bump.mjs 0.6.5      # 同时改 package.json 与 src/host.js
+git commit -am "chore: release 0.6.5"
+git tag v0.6.5 && git push origin main --tags
+```
+
+workflow 会拒绝 tag 与 `package.json` 版本不一致的情况，先跑可移植测试（`npm run test:ci`），再带 `--provenance` 发布，最后轮询 registry 确认版本已出现。首次发布（包还没有 trusted publisher 时）仍可本地 `npm publish`。
+
+## 开发
+
+```
+node dev/engines.test.mjs # 11 项：engines.py 的 commit/rollback 与 affectedRows，用假连接
+node dev/selftest.mjs     # 在临时端口挂载 src/host.js，46 项断言
+node dev/shims.test.mjs   # 挂载 index.js，检查路由、/reload、工具发布
+node dev/parse.test.mjs   # 24 项：连接串解析（DSN/JDBC/TNS/路径）
+node dev/render.test.mjs  # 40 项：用 stub React 渲染组件与结果渲染器
+node dev/i18n.test.mjs    # 12 项：中英键集合一致、无死键、无漏译
+node dev/p5.test.mjs      # 15 项：设置、审计日志、Python 环境
+node dev/mcp.test.mjs     # 19 项：真实 Python 服务走 stdio，真实 SQLite 与 Oracle 登录
+```
+
+`npm test` 跑除 `mcp.test.mjs` 之外的全部（后者需要 venv 与 Oracle 容器）。`dev/engines.test.mjs` 只需要一个 Python 解释器（插件 venv，否则 PATH 里的 `python`），不连数据库：它用假 DB-API 连接驱动 `server/engines.py`，守住 `run_query` 的 commit/rollback 与 `affectedRows` 契约。`node dev/bump.mjs 0.6.6` 会同步两处版本号。
+
+## 安全闸门
+
+是否允许写入由两道互相独立的闸门决定：
+
+1. **全局开关** —— `<运行时目录>/settings.json` 的 `allowWrite`，在诊断卡上切换。默认关闭；关闭期间所有写语句都以 `user_error` 拒绝，并给出指向该开关的提示。
+2. **单源标记** —— 数据源的 `readOnly`，默认开启。即使全局开关打开，只要不清掉这条标记，该源仍然只读。点数据源行上的「只读 / 可写」药丸即可一键切换：该源可写时药丸变成琥珀色，若全局开关仍关着，提示条会提醒你去打开它。
+
+Python 服务启动时从环境变量 `DB_MCP_ALLOW_WRITE` 读取全局标记；开关一变，Host 就会重启它。只要引擎支持，只读还会在驱动层再兜一次（SQLite 的 `mode=ro`、PostgreSQL 的 `default_transaction_read_only`、MySQL 的 `SET SESSION TRANSACTION READ ONLY`）。
+
+### 插件会启动什么，以及带着什么
+
+- Python 服务用固定的解释器路径、固定脚本、固定参数启动，**从不经过 shell**，所以任何字符串都不会被 `cmd.exe` 或 `/bin/sh` 再解析一次。
+- 子进程**不继承** Host 的环境变量。它只拿到一张很短的允许清单（`PATH`、`TEMP`、`HOME`、`PYTHON*` 之类）再加上插件自己设置的 `DB_MCP_*`。DSH 进程里的 token、云凭据不会被带下去。
+- PostgreSQL / MySQL / Oracle 都由这个子进程连接，只有 SQLite 是在进程内读的。裸 TCP 探测只是子进程起不来时的兜底，且不发任何凭据。
+- 口令存在 `secrets.json`（`0600`），任何 HTTP 接口都不会返回它；面板只知道 `hasSecret`。
+
+
+## 审计日志
+
+每次 MCP 工具调用都会向 `<运行时目录>/logs/audit.jsonl`（0600）追加一行 JSON：时间、工具、数据源、耗时、行数、截断到 2000 字符的 SQL，以及失败时的错误。结果行永不记录。文件超过 512 KiB 轮转为 `audit.1.jsonl`，也可以在 `settings.json` 里用 `auditLog: false` 关掉。面板显示最近十几条，时间按**本机时区**换算——文件里存的是 UTC，这样换机器也仍然可比；卡片会把每条时间戳转成浏览者的时区，并标出所用偏移。
+
+`dev/shims.test.mjs` 还断言 `package.json` 不带 UTF-8 BOM：Host 用 `JSON.parse` 读它，而 `JSON.parse` 会拒绝 BOM，插件随之显示为 `availability: missing`，并不加载。会「添加 BOM」的编辑器会静默弄坏 bundle——如果重启后侧边栏入口消失，先查这一项。
+
+## 阶段表
+
+| 阶段 | 内容 |
+| ---- | ---- |
+| P1 | 可安装的骨架：侧边栏入口、空面板、Host 健康接口（已完成） |
+| P2 | 数据源 CRUD、连接测试、DBeaver 导入（已完成） |
+| P3 | Python MCP 服务，工具以 `mcp__db__*` 发布（已完成） |
+| P4 | PostgreSQL / MySQL / Oracle 方言（已完成） |
+| P5 | 诊断、一键 venv、热重载、审计日志、全局写开关（已完成） |
+| P6 | 多语言打磨与文档（已完成） |
+| P7 | 只读结构概览、分组、批量操作（已完成） |
+
+## 许可
+
+Apache License 2.0 —— 见 [LICENSE](LICENSE)。
+
+## 运行时目录
+
+```
+$DSH_HOME/db-mcp/
+  datasources.json   # 数据源档案，不含口令，0600
+  secrets.json       # 各源口令，0600，仅 Host 可读
+  settings.json      # 全局写开关 + 审计开关，0600
+  logs/mcp.log       # 已掩码的日志
+  logs/audit.jsonl   # 每次 MCP 工具调用一行，超过 512 KiB 轮转
+  .venv/             # 插件内 venv：mcp、psycopg、PyMySQL、oracledb
+```

package/client.js

@@ -167,6 +167,12 @@ window.__ModuleLoader__.load({
         'audit.err': 'failed',
         'audit.hint': 'One line per MCP tool call: tool, source, duration and outcome. Query results are never logged.',
         'audit.rows': '{n} row(s)',
+        'audit.tz': 'Times follow your computer clock ({zone}); the log file keeps UTC.',
+        'action.lockSource': 'Click to make this source read-only',
+        'action.unlockSource': 'Click to allow writes on this source',
+        'notice.nowReadOnly': '{name} is read-only now.',
+        'notice.nowWritable': '{name} accepts writes now.',
+        'notice.nowWritableLocked': '{name} accepts writes now, but the global write switch is still off — turn it on under Runtime.',
         'action.schema': 'Structure',
         'action.backToSources': 'Data sources',
         'tab.list': 'Data source list',
@@ -339,6 +345,12 @@ window.__ModuleLoader__.load({
         'audit.err': '失败',
         'audit.hint': '每次 MCP 工具调用记一行：工具、数据源、耗时与结果。查询结果不会被记录。',
         'audit.rows': '{n} 行',
+        'audit.tz': '时间按本机时区显示（{zone}），日志文件里存的是 UTC。',
+        'action.lockSource': '点击改为只读',
+        'action.unlockSource': '点击允许写',
+        'notice.nowReadOnly': '{name} 已改为只读。',
+        'notice.nowWritable': '{name} 现在允许写。',
+        'notice.nowWritableLocked': '{name} 现在允许写，但全局写开关还关着——到「运行时诊断」里打开它。',
         'action.schema': '结构',
         'action.backToSources': '数据源',
         'tab.list': '数据源列表',
@@ -581,6 +593,20 @@ window.__ModuleLoader__.load({
         font-size: 12px;
         color: var(--dsw-alias-label-secondary);
       }
+      button.dbmcp-pill {
+        font-family: inherit;
+        background: transparent;
+        cursor: pointer;
+        transition: color 120ms ease, border-color 120ms ease;
+      }
+      button.dbmcp-pill:hover {
+        color: var(--dsw-alias-brand-primary);
+        border-color: var(--dsw-alias-brand-primary);
+      }
+      button.dbmcp-pill.is-open {
+        color: var(--dsw-alias-state-warn-primary);
+        border-color: var(--dsw-alias-state-warn-primary);
+      }
       .dbmcp-grid {
         display: grid;
         grid-template-columns: repeat(auto-fit, minmax(320px, 1fr));
@@ -1440,6 +1466,38 @@ window.__ModuleLoader__.load({
       return `${hours}h ${minutes % 60}m`
     }
 
+    /** UTC offset of the viewer's clock, e.g. "UTC+08:00". */
+    function zoneLabel() {
+      const offset = -new Date().getTimezoneOffset()
+      const sign = offset >= 0 ? '+' : '-'
+      const abs = Math.abs(offset)
+      const pad = (part) => String(part).padStart(2, '0')
+      return `UTC${sign}${pad(Math.floor(abs / 60))}:${pad(abs % 60)}`
+    }
+
+    /**
+     * The audit log keeps UTC ISO stamps so the file stays comparable across
+     * machines; the panel shows them on the viewer's clock instead.
+     */
+    function localClock(value) {
+      const at = Date.parse(String(value || ''))
+      if (!Number.isFinite(at)) return String(value || '').slice(11, 19)
+      const date = new Date(at)
+      return [date.getHours(), date.getMinutes(), date.getSeconds()]
+        .map((part) => String(part).padStart(2, '0'))
+        .join(':')
+    }
+
+    /** Full local timestamp, used as the hover title of an audit row. */
+    function localStamp(value) {
+      const at = Date.parse(String(value || ''))
+      if (!Number.isFinite(at)) return String(value || '')
+      const date = new Date(at)
+      const pad = (part) => String(part).padStart(2, '0')
+      const day = `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`
+      return `${day} ${localClock(value)} ${zoneLabel()}`
+    }
+
     function pythonLabel(t, python) {
       if (!python) return '-'
       if (python.ok) return `${python.command} ${python.version}`
@@ -2248,6 +2306,29 @@ window.__ModuleLoader__.load({
         }
       }
 
+      /** Flip one source between read-only and writable by clicking its pill. */
+      const toggleReadOnly = async (source) => {
+        const wasWritable = source.readOnly === false
+        const nowWritable = !wasWritable
+        const name = source.name || source.id
+        setBusy(true)
+        try {
+          await apiPost('/datasources/bulk', { action: 'readOnly', ids: [source.id], readOnly: !nowWritable })
+          const globalOpen = Boolean(settings && settings.allowWrite)
+          const message = !nowWritable
+            ? t('notice.nowReadOnly').replace('{name}', name)
+            : globalOpen
+              ? t('notice.nowWritable').replace('{name}', name)
+              : t('notice.nowWritableLocked').replace('{name}', name)
+          setNotice({ message, isError: false })
+          load()
+        } catch (error) {
+          setNotice({ message: String((error && error.message) || error), isError: true })
+        } finally {
+          setBusy(false)
+        }
+      }
+
       const bulkDelete = async () => {
         if (selected.length === 0) return
         if (!pendingBulkDelete) {
@@ -2501,7 +2582,20 @@ window.__ModuleLoader__.load({
                   ),
                   h('span', { className: 'dbmcp-pill' }, source.kind),
                   source.isDefault ? h('span', { className: 'dbmcp-pill' }, t('sources.default')) : null,
-                  h('span', { className: 'dbmcp-pill' }, source.readOnly ? t('sources.readonly') : t('sources.readwrite')),
+                  h(
+                    'button',
+                    {
+                      type: 'button',
+                      className: 'dbmcp-pill is-toggle ' + (source.readOnly === false ? 'is-open' : 'is-locked'),
+                      title: source.readOnly === false ? t('action.lockSource') : t('action.unlockSource'),
+                      'aria-pressed': source.readOnly === false,
+                      onClick: (event) => {
+                        event.stopPropagation()
+                        void toggleReadOnly(source)
+                      },
+                    },
+                    source.readOnly === false ? t('sources.readwrite') : t('sources.readonly'),
+                  ),
                 ),
             h('div', { className: 'dbmcp-item-target' }, [source.target, source.id].filter(Boolean).join(' · ')),
             h(
@@ -2933,7 +3027,11 @@ window.__ModuleLoader__.load({
                     h(
                       'div',
                       { className: 'dbmcp-audit', key: `${entry.at || 'entry'}-${index}` },
-                      h('span', { className: 'dbmcp-audit-time' }, String(entry.at || '').slice(11, 19)),
+                      h(
+                        'span',
+                        { className: 'dbmcp-audit-time', title: localStamp(entry.at) },
+                        localClock(entry.at),
+                      ),
                       h('span', { className: 'dbmcp-audit-tool' }, entry.tool || '?'),
                       h('span', { className: 'dbmcp-pill' }, entry.datasource || t('sources.default')),
                       h('span', { className: 'dbmcp-hint' }, `${entry.ms ?? 0}ms`),
@@ -2950,6 +3048,7 @@ window.__ModuleLoader__.load({
                     ),
                   ),
               h('p', { className: 'dbmcp-hint' }, t('audit.hint')),
+              h('p', { className: 'dbmcp-hint' }, t('audit.tz').replace('{zone}', zoneLabel())),
               audit.file ? h('p', { className: 'dbmcp-hint' }, `${t('audit.file')}: ${audit.file}`) : null,
             ),
           ),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-db-mcp",
-  "version": "0.6.5",
+  "version": "0.6.9",
   "description": "DSH database plugin: a data-source management panel plus a Python MCP server that exposes those sources to the agent.",
   "keywords": [
     "dsh",
@@ -41,11 +41,13 @@
     "server/requirements.txt",
     "docs/*.md",
     "LICENSE",
-    "README.md"
+    "README.md",
+    "README.zh.md"
   ],
   "scripts": {
-    "test": "node dev/selftest.mjs && node dev/shims.test.mjs && node dev/parse.test.mjs && node dev/render.test.mjs && node dev/i18n.test.mjs && node dev/p5.test.mjs",
+    "test": "node dev/engines.test.mjs && node dev/selftest.mjs && node dev/shims.test.mjs && node dev/parse.test.mjs && node dev/render.test.mjs && node dev/i18n.test.mjs && node dev/p5.test.mjs",
     "test:ci": "node dev/shims.test.mjs && node dev/parse.test.mjs && node dev/render.test.mjs && node dev/i18n.test.mjs && node dev/p5.test.mjs",
+    "test:engines": "node dev/engines.test.mjs",
     "test:mcp": "node dev/mcp.test.mjs"
   },
   "dsh": {

package/server/engines.py

@@ -553,7 +553,9 @@ def run_query(profile: dict, connection, sql: str, max_rows: int) -> dict:
     ensure_readable(sql, profile)
     kind = profile.get("kind")
     started = time.perf_counter()
+    is_write = _first_keyword(sql) not in READ_STARTERS
     cursor = connection.cursor()
+    affected = None
     try:
         if kind == "oracle" and profile.get("readOnly"):
             try:
@@ -562,14 +564,24 @@ def run_query(profile: dict, connection, sql: str, max_rows: int) -> dict:
                 pass
         cursor.execute(sql)
         columns, rows, truncated = _rows(cursor, max_rows)
-        if profile.get("readOnly") or not connection_autocommit(kind):
-            try:
-                connection.rollback()
-            except Exception:  # noqa: BLE001 - nothing to roll back
-                pass
+        if is_write:
+            affected = _affected_rows(cursor)
+        if not is_write or profile.get("readOnly"):
+            # Reads (and anything on a read-only source) must not hold the session
+            # open in a transaction; writes need the commit below instead.
+            if not connection_autocommit(kind):
+                try:
+                    connection.rollback()
+                except Exception:  # noqa: BLE001 - nothing to roll back
+                    pass
+        else:
+            # No engine here autocommits by default: `sqlite3.connect` runs in the
+            # legacy implicit-transaction mode, and MySQL/PostgreSQL/Oracle are
+            # explicit-commit. A write not committed here dies with the connection.
+            connection.commit()
     finally:
         cursor.close()
-    return {
+    result = {
         "sql": sql,
         "columns": columns,
         "rows": rows,
@@ -577,6 +589,22 @@ def run_query(profile: dict, connection, sql: str, max_rows: int) -> dict:
         "truncated": truncated,
         "elapsedMs": int((time.perf_counter() - started) * 1000),
     }
+    if affected is not None:
+        result["affectedRows"] = affected
+    return result
+
+
+def _affected_rows(cursor) -> int | None:
+    """Rows touched by a write, when the driver reports it.
+
+    `rowcount` is -1 for statements whose count is unknown (and some drivers raise
+    instead), so anything but a real, non-negative int becomes `None`.
+    """
+    try:
+        value = cursor.rowcount
+    except Exception:  # noqa: BLE001 - drivers without a usable rowcount
+        return None
+    return value if isinstance(value, int) and not isinstance(value, bool) and value >= 0 else None
 
 
 def connection_autocommit(kind: str) -> bool:

package/server/main.py

@@ -206,7 +206,8 @@ def run_query(sql: str, datasource: Optional[str] = None, max_rows: Optional[int
 
     Read-only datasources accept SELECT/WITH/SHOW/EXPLAIN statements only.
     Results are capped by `max_rows` (default 200); `truncated` says whether more
-    rows existed.
+    rows existed. Writes (INSERT/UPDATE/DELETE/DDL) are committed and report
+    `affectedRows` instead of a result set.
     """
     try:
         limit = _clamp_rows(max_rows)

package/src/host.js

@@ -33,7 +33,7 @@ const { createBridge } = await import(new URL(`./tools.js?v=${GENERATION}`, impo
 
 const API_PREFIX = '/plugins/db-mcp/api'
 const PLUGIN_NAME = 'dsh-db-mcp'
-const PLUGIN_VERSION = '0.6.5'
+const PLUGIN_VERSION = '0.6.9'
 const SCHEMA_VERSION = 1
 const REGISTRY_FILE = 'datasources.json'
 const SECRETS_FILE = 'secrets.json'

package/src/mcp.js

@@ -16,6 +16,50 @@ import { spawn } from 'node:child_process';
 const DEFAULT_TIMEOUT_MS = 30_000;
 const INIT_TIMEOUT_MS = 60_000;
 
+/**
+ * The Python child gets a small, explicit environment instead of a copy of ours.
+ * Spreading `process.env` would hand every token and cloud credential in the
+ * DSH process to a driver stack that only ever needs to find its interpreter.
+ */
+const ENV_ALLOW = [
+  'PATH',
+  'Path',
+  'PATHEXT',
+  'SystemRoot',
+  'SYSTEMROOT',
+  'windir',
+  'ComSpec',
+  'COMSPEC',
+  'TEMP',
+  'TMP',
+  'TMPDIR',
+  'HOME',
+  'USERPROFILE',
+  'HOMEDRIVE',
+  'HOMEPATH',
+  'APPDATA',
+  'LOCALAPPDATA',
+  'PROGRAMDATA',
+  'PROGRAMFILES',
+  'LANG',
+  'LC_ALL',
+  'TZ',
+  'PWD',
+  'PYTHONPATH',
+  'PYTHONHOME',
+  'PYTHONIOENCODING',
+  'VIRTUAL_ENV',
+];
+
+function childEnvironment(extra) {
+  const env = {};
+  for (const key of ENV_ALLOW) {
+    const value = process.env[key];
+    if (typeof value === 'string' && value !== '') env[key] = value;
+  }
+  return Object.assign(env, extra || {});
+}
+
 export class McpError extends Error {
   constructor(message, { code = 'mcp_error', data } = {}) {
     super(message);
@@ -61,7 +105,7 @@ export class McpClient {
     if (this.#child) return this;
     const child = spawn(this.command, this.args, {
       cwd: this.cwd,
-      env: { ...process.env, ...this.env },
+      env: childEnvironment(this.env),
       stdio: ['pipe', 'pipe', 'pipe'],
       windowsHide: true,
     });

package/src/tools.js

@@ -41,6 +41,9 @@ export function renderResult(value) {
     return `error [${code}]: ${message}${hint ? `\n${hint}` : ''}`;
   }
   if (Array.isArray(value.columns) && Array.isArray(value.rows)) {
+    if (typeof value.affectedRows === 'number' && value.columns.length === 0) {
+      return `ok: ${value.affectedRows} row(s) affected, ${value.elapsedMs}ms`;
+    }
     const head = value.columns.join(' | ');
     const body = value.rows
       .slice(0, 50)
@@ -173,7 +176,8 @@ export function createBridge({
     if (error) entry.error = String((error && error.message) || error);
     else {
       const parsed = outcome && outcome.parsed;
-      const rows = parsed && (parsed.rowCount ?? (Array.isArray(parsed.rows) ? parsed.rows.length : undefined));
+      // A write reports how many rows it touched; a read reports how many came back.
+      const rows = parsed && (parsed.affectedRows ?? parsed.rowCount ?? (Array.isArray(parsed.rows) ? parsed.rows.length : undefined));
       if (typeof rows === 'number') entry.rows = rows;
       if (parsed && parsed.error && parsed.error.code) entry.code = parsed.error.code;
     }