通过 TableStudio 使用数据库
TableStudio 是用户在 Mac 上的数据库应用。它的 MCP 工具可以不通过凭据访问用户已保存的连接，并且带有原始 psql 会话所没有的安全网：对真实行的精确写操作预演、可丢弃的沙箱副本，以及一个让用户审批更改的审查收件箱。请使用这些工具进行数据库工作，而不是使用 psql、mysql、sqlite3 或自行建立连接的脚本。
以下工具名称是 TableStudio 的。你的客户端可能会带前缀显示它们（在 Claude Code 中：mcp__plugin_tablestudio_tablestudio__list_connections）。如果它们是延迟加载的，请在首次调用前按该名称加载它们。
1. 在操作之前找到正确的数据库
会话的 数据库上下文 备注（来自 TableStudio 插件）通常会指出仓库中每个数据库设置背后的 TableStudio 连接，包括其 ID 和环境。使用该 ID 作为 connection_id。该备注也会说明 TableStudio 工具何时不可用以及用户应如何处理。
如果没有该备注，或者针对它未命名的数据库：
- 调用
list_connections。每个连接可能携带用户告知 TableStudio 的信息：project：它所属的项目。优先选择项目与你正在处理的仓库匹配的连接。environment：development、staging或production。缺失表示未标记，而非 development。read_only：TableStudio 拒绝写入该数据库。Staging 仍可工作。location：local（此 Mac）、remote或sandbox（可丢弃副本，安全可用于实验）。agent_writes：direct意味着 execute_query 可能在那里写入（当写入开启时）；review意味着每个更改都会通过stage_migration供用户应用。TableStudio 决定此设置，而不是你：生产环境以及任何用户未标记为 development 或 staging 的远程数据库都是review。notes：用户关于数据库约定的备注（软删除、金额以分为单位、命名）。请遵循它们。
- 首先匹配项目，然后通过
host、port和database与项目自身的设置（.env、config）进行确认。 - 如果两个连接都可能是用户所指的，或者你无法判断其中一个是否为生产环境，请询问。不要猜测。
然后：
- 在计划任何超出读取范围的操作之前，先调用
describe_capabilities一次。它会说明当前是否允许直接写入、暂存和沙箱，并指出每个功能背后的设置。请据此进行规划，而不是在请求被拒绝时才得知限制。 agent_writes: review（生产环境，或远程且未标记）意味着永远不要直接写入：将更改暂存以供审查。TableStudio 会在那里拒绝直接写入，因此从一开始就规划暂存。- 在编写 SQL 之前检查
engine（postgres、mysql、sqlite、d1、clickhouse），并编写该方言的 SQL。 - 未保存在 TableStudio 中的数据库无法通过其工具访问。请用户将其添加到 TableStudio。绝不要在聊天中索要密码。
- 如果调用因数据库不可达而失败，请调用
connection_status。当它指出本地服务器已停止时，请使用它提供的instance_id调用start_local_database。
2. 读取和调查
- 通过名称片段查找表或列，而不是猜测名称：
search_schema可查找表和列，get_table_ddl提供完整结构、索引、外键和referenced_by。 - 使用
execute_query运行读取。选择你需要的列、过滤、聚合，并限制LIMIT。结果有上限（max_rows，默认 200），因此truncated的结果并非全部答案。 - 读取操作在只读事务中运行，时限 30 秒，包括生产环境，因此即使通过函数也无法更改数据。仍然请保持廉价：在大型生产表上，请过滤索引列或使用
database_overview的行估算值，而不是使用count(*)。 - 数据错误： 首先在数据中重现它。找到错误的行，对其计数，并找到它们开始出现的时间（
min(created_at)）。然后读取写入它们的代码。向用户展示证明该问题的查询。修复代码，如果行需要修复，则那是数据更改（第 3 节）。 - 切勿将机密、密码或连接字符串粘贴到 SQL、代码、文档或聊天中。连接字符串唯一应去的地方是项目 gitignore 的 env 文件，用于本地数据库（本地数据库技能涵盖了
get_connection_url）。
3. 更改数据 (INSERT, UPDATE, DELETE)
在 PostgreSQL 上：
- 编写语句，然后使用它调用
preflight_statement。你将获得一个verdict（looks_fine、review或would_fail）、dry_run.rows（精确显示它将更改多少行，只读）、级联到其他表的内容，以及可能导致失败的原因。 - 用通俗的语言告诉用户它将做什么：“这将更新
invoices中的 142 行；没有级联。” 如果 verdict 是would_fail，请先修复语句。如果是review，请解释原因。 - 然后要么：
agent_writes: direct，并且允许直接写入： 使用设置为dry_run.rows的expected_rows调用execute_query。只有当恰好更改了那么多行时，它才会提交，否则会回滚。在远程 PostgreSQL 数据库上，TableStudio 拒绝没有expected_rows的数据更改。agent_writes: review、不允许写入，或者任何用户应先看到的内容： 使用清晰的title、SQL 和包含预演计数的rationale（“通过...发现的 142 条重复发票作废”）调用stage_migration。它会进入 TableStudio 代理中心的用户审查队列，并且不会运行。
在 其他引擎 上没有预演：首先运行一个带有相同 WHERE 条件的 SELECT count(*)，报告计数，然后遵循相同的执行或暂存规则。
在对重要的数据库进行任何破坏性操作之前（大型 DELETE、DROP、TRUNCATE），当沙箱启用时，调用 create_restore_point，并告知用户你已这样做。
4. 更改模式
如果仓库使用迁移工具（Prisma、Drizzle、Rails、Django、Alembic、Laravel、Supabase、Knex、Ecto、TypeORM、Wrangler D1 或纯编号 SQL 文件；当插件检测到迁移工具时，会话上下文会命名它），则该更改属于该工具：
- 以该工具的方式进行更改：编辑模式并生成迁移，或编写迁移文件。
- 将该工具的开发命令应用到本地开发数据库。
- 对照真实数据检查它（见下文）。
- 将应用到其他环境的工作留给用户正常的部署流程。切勿亲自针对生产环境运行该工具的部署命令。
在迁移工具拥有模式所有权时直接运行 ALTER TABLE 会使工具的历史记录与数据库不同步，从而破坏下一次部署。
如果没有迁移工具，或者用户要求对现有数据库进行一次性更改：
- 首先使用
get_table_ddl读取表。在删除或重命名任何内容之前，检查referenced_by。 - 在副本上尝试：
create_sandbox（data：none仅模式，sample获取真实行的切片），使用execute_query在沙箱的连接上运行 DDL，并检查它是否符合你的意图。 - 使用
compare_schemas显示差异（沙箱作为source_connection_id，真实数据库作为target_connection_id）。 - 在真实连接上使用
stage_migration提出更改。用户在 TableStudio 中应用它。
对照真实数据检查迁移
在本地数据库上通过的迁移，在真实行所在的环境仍可能失败或锁定应用程序。在您认为迁移完成之前，请以只读方式对照它将部署到的数据库（通常是 staging 或 production，来自会话备注或 list_connections）进行检查：
-
对于它更改的每个表，运行
get_table_ddl：获取行数、索引以及引用它的内容。 -
对于它添加的每个约束，使用
execute_query运行 SELECT 来查找会破坏它的行：NOT NULL：SELECT count(*) FROM t WHERE col IS NULLUNIQUE：SELECT col, count(*) FROM t GROUP BY col HAVING count(*) > 1 LIMIT 20- 外键：父行不存在的子行（
LEFT JOIN … WHERE parent.id IS NULL） CHECK，或更窄的类型或长度：超出新范围的行
任何行都意味着部署会失败。向迁移添加回填或清理步骤，并加以说明。
-
在 PostgreSQL 上，标记锁定或重写大表的步骤（见下文），并切换到安全模式。
-
当更改很棘手时，在副本上实际运行它：从该连接创建 `data: