让 Agent 查数据库不出错:只读先行、可验证的 SQL 分析工作流
让 Agent 查数据库是日常操作,也是高危操作。五道护栏:只读连接先行、SQL 先交出来再执行、EXPLAIN 先于 ANALYZE、每个数字附带查询、写操作走单独审核通道。

划界:这篇和已发的数据库指南有什么不同
先说清楚这篇指南的位置。站里已经有好几篇数据库相关的指南,各管一摊:《vibe-database-selection-guide》讲选哪个数据库,《vibe-project-schema-migration-guide》讲怎么改表结构,《vibe-project-db-backup-disaster-recovery-guide》讲备份和灾难恢复,《vibe-project-slow-query-index-guide》讲慢查询和索引调优,《vibe-project-data-import-migration-guide》讲数据导入迁移。本篇不讲选型、不讲改表、不讲备份、不讲索引调优,只讲一件事:让 Agent 替你查数、做分析的时候,怎么保证它只读、不乱改、结论可复核。
这件事值得单独写一篇,是因为“让 Agent 查数据库”是 vibe coder 最常干、也最容易出事的操作之一。应用上线之后,你总想问它几个问题:上周注册了多少用户?哪个功能最常用?这笔订单为什么没成功?问的时候很自然,Agent 也答得很痛快。但你很少想过:它是用什么身份连的数据库?它跑的那条 SQL,你检查过吗?它报出来的那个数字,你能复核吗?如果答案是“没想过”,这篇指南就是写给你的。
依据是 PostgreSQL 的官方文档:EXPLAIN 的文档(postgresql.org/docs/current/sql-explain.html)和 SET TRANSACTION 的文档(postgresql.org/docs/current/sql-set-transaction.html)。本文提到的只读事务、EXPLAIN 与 EXPLAIN ANALYZE 的区别、回滚保护写操作的做法,都出自这两份文档。文中给出的操作建议(比如“先交 SQL 再执行”“每个数字附查询”)是基于这些机制的做法,会说明哪些是文档原话、哪些是建议。例子里的 shop 数据库是虚构的,仅用于演示。
风险在哪:三种最常见的翻车
第一种翻车是 Agent 改了数据,而你以为它只是在查。最常见的场景是:你让 Agent“看看这笔订单为什么没成功”,它为了“修复”问题,顺手跑了一条 UPDATE。或者你让它“清理一下测试数据”,它理解的“测试数据”和你理解的不是同一批。Agent 的默认行为是“把事情做完”,而不是“只看不碰”。如果你给它的数据库连接是读写权限,它就有能力改数据——不管你有没有让它改。
第二种翻车是数字错了,但看起来很对。Agent 写了一条 SQL,跑出来一个数字,写进回答里,语气非常肯定。但这条 SQL 可能漏了一个状态过滤(把退款订单也算进了销售额),可能有时区问题(“上周”按 UTC 算还是按本地时间算),可能因为 JOIN 多了一张表导致行数翻倍。数字本身不会告诉你它错了,只有复核能发现。而大多数人看到 Agent 给出的数字,第一反应是直接用,不会复核。
第三种翻车是查询本身把数据库拖垮。一条没有 WHERE 条件的 SELECT、一张几百万行的表、一个没加 LIMIT 的查询,在小数据量的时候跑得飞快,上线几个月后就可能把数据库打满。Agent 不知道你的表有多大,也不知道现在是不是业务高峰期,它只知道“先把数据拿回来再说”。更麻烦的是,EXPLAIN ANALYZE 本身会真的执行查询——对着写操作用它,等于直接改了数据。PostgreSQL 的文档特意警告了这一点,很多人不知道。
这三种翻车有一个共同点:问题都不出在 Agent“笨”上,出在“没有护栏”上。Agent 按你的要求干活,但你没给它划边界。这篇指南的五条规则,就是五道护栏。
规则一:只读先行,别给 Agent 写的权限
第一道护栏是最重要的一道:让 Agent 查数用的连接,只能读,不能写。PostgreSQL 的文档写得很清楚,只读事务会禁止一大批写操作:INSERT、UPDATE、DELETE、MERGE、COPY FROM(写非临时表的时候),所有的 CREATE、ALTER、DROP,以及 COMMENT、GRANT、REVOKE、TRUNCATE。设置的方法是一条命令,在事务开始的时候执行:
BEGIN TRANSACTION READ ONLY;
SELECT count(*) FROM orders WHERE status = 'paid';
COMMIT;
或者把整个会话的默认行为设成只读:
SET SESSION CHARACTERISTICS AS TRANSACTION READ ONLY;
文档里还有一句提醒值得注意:只读是“高层次上的概念”,并不能阻止所有对磁盘的写入。比如它不会阻止数据库内部的统计信息更新。所以只读事务不是万能保险,它防的是“Agent 发了一条写 SQL”,不是“数据库本身一个字节都不会变”。即便如此,它依然是性价比最高的护栏:一条命令,就把最危险的那类错误挡在了外面。
除了事务级别的只读,更彻底的做法是给 Agent 一个专门的只读数据库账号。这个账号在数据库层面就只有 SELECT 权限,连不小心都写不进去。很多 vibe 项目把数据库托管在 Supabase、Neon 这类服务上,建一个只读账号通常就是几分钟的事。原则是:Agent 用的连接,和应用本身用的连接,分开。应用要写数据,给它写权限;Agent 只查数,只给它读权限。两个连接不要共用一个账号、一个连接字符串。
如果你只能做到一件事,就做这一件:从今天开始,Agent 查数据库一律走只读连接。这条规则能拦住的错误,比后面四条加起来都多。
规则二:先交 SQL,再执行
第二道护栏是流程上的:让 Agent 先把要跑的 SQL 写出来给你看,你确认了再执行。不要让它“直接查一下告诉我结果”,要让它“先把查询写出来,我看一眼”。这个习惯看起来多了一步,实际上是整个工作流里最关键的一步:SQL 是可以被检查的,数字是没法被检查的。你看一眼 SQL,就能发现漏掉的状态过滤、错掉的表名、没加的 LIMIT;你直接看数字,什么都发现不了。
具体的做法是:你问问题的时候就把规矩定下来。“先写出你要跑的 SQL,等我确认再执行。”Agent 第一次可能会不习惯,多问两次就记住了。更好的做法是把这条规矩写进项目的 CLAUDE.md 或者 AGENTS.md,让它变成这个项目的默认做法,而不是每次现说。
检查 SQL 的时候重点看四样东西。第一,表名和字段名对不对——Agent 很容易凭印象编一个字段名出来,比如把 user_id 写成 users_id。第二,WHERE 条件全不全——状态、时间范围、租户隔离,有没有漏掉哪一个。第三,有没有 LIMIT——分析查询先加 LIMIT 100 看一眼形状,确认没问题再放开。第四,是不是只读语句——以 SELECT 或者 WITH 开头的是读,以 INSERT、UPDATE、DELETE、DROP 开头的是写,看到写语句直接叫停,不管 Agent 的理由是什么。
规则三:先 EXPLAIN,再 ANALYZE
第三道护栏是看执行计划。PostgreSQL 的 EXPLAIN 命令会显示查询的执行计划:会用什么方式扫描表(顺序扫描还是索引扫描)、多表之间用什么算法连接、预估要处理多少行、预估成本是多少。关键是:不带 ANALYZE 的 EXPLAIN 只做计划、不执行查询,所以它是安全的,哪怕对着 UPDATE 或者 DELETE 用,也不会改数据。文档的原话是,EXPLAIN 会显示规划器为这条语句生成的执行计划,包括表怎么被扫描、连接算法怎么选。
EXPLAIN SELECT * FROM orders WHERE customer_id = 2;
EXPLAIN ANALYZE 则不一样:它会真的执行查询,再把实际的运行时间统计加到执行计划里。文档明确警告:使用 ANALYZE 选项时,语句是真的被执行了。虽然 EXPLAIN 会丢弃 SELECT 返回的结果,但其他副作用会照常发生。如果你想对 INSERT、UPDATE、DELETE、MERGE、CREATE TABLE AS 或者 EXECUTE 用 EXPLAIN ANALYZE,又不想让它真的改数据,文档给的标准做法是包在事务里再回滚:
BEGIN;
EXPLAIN ANALYZE ...;
ROLLBACK;
给 Agent 的规矩可以定成两条:第一,任何查询先跑 EXPLAIN 看一眼,顺序扫描一张大表、预估行数和实际差了两个数量级,都是叫停的信号。第二,EXPLAIN ANALYZE 只对 SELECT 用,而且只在你确认过之后用;对写操作用 ANALYZE,必须包在 BEGIN 和 ROLLBACK 里。Agent 如果分不清这两者的区别,让它只用不带 ANALYZE 的 EXPLAIN——少看一点实际耗时,换来的是绝对不会误改数据。
还有一个细节:执行计划的预估准不准,取决于表的统计信息新不新鲜。文档提醒说,规划器依赖 pg_statistic 里的数据做判断,通常 autovacuum 会自动维护,但如果一张表最近发生了大量变化,可能需要手动跑 ANALYZE 命令更新统计信息。Agent 报出来的“预估 10 行、实际 10 万行”,很多时候不是查询写错了,是统计信息过期了。
规则四:每个数字都要能复核
第四道护栏是针对结论的:Agent 报出来的每个数字,都必须附带能复核它的东西——查询本身、行数、运行时间。没有这些东西的数字,不要直接用。具体的格式可以定成这样:结论一句话,附上完整的 SQL,再附上返回的行数。比如下面的格式:
结论:上周付费订单 1,284 笔。
查询:SELECT count(*) FROM orders WHERE status = 'paid' AND created_at >= '2026-11-09' AND created_at < '2026-11-16';
返回:1 行,1,284。
复核的方法有三种,从便宜到贵。最便宜的是“换个问法再算一遍”:让 Agent 用另一种写法算同一个数,比如先按天分组加总,再直接 COUNT(*) 全表,看两个数字对不对得上。对不上,说明至少有一种写法错了。中间档的是“看行数”:查询返回了多少行、影响了多少行,这个数字本身就是线索。COUNT(*) 返回 0 的时候,先别信“没有数据”,先问一句“是不是 WHERE 条件写错了”。最贵的是“自己跑一遍”:把 SQL 复制到数据库客户端里自己执行一次,看结果是不是一样。重要的数字(比如要发给投资人、要写进复盘的),值得花这个成本。
一个特别容易错的点是时间范围。Agent 写 WHERE created_at >= '2026-11-09' 的时候,你要问一句:这是 UTC 还是本地时间?数据库里存的时间是哪个时区?“上周”是指周一到周日,还是过去 7 天?这些问题看起来琐碎,但时区错一次,数字就错一整天。让 Agent 在回答里写明它用的时间范围和时区,是成本最低的防错方法。
另一个容易错的点是 JOIN 导致的行数膨胀。订单表 JOIN 订单明细表,一笔订单有三条明细,COUNT(*) 就会把一笔订单算成三笔。Agent 写这种查询的时候经常漏掉 DISTINCT 或者子查询。复核的方法很简单:先不加 JOIN,单独 COUNT 一遍订单表,再加 JOIN 对比,数字变大了就说明有问题。
规则五:写操作走另一条路
第五道护栏是把“查”和“改”彻底分开。分析会话只查数,不改数据。任何写操作——修一条错数据、补一个字段、删一批测试账号——都不在分析会话里做,而是走另一条路:写成迁移文件或者修复脚本,经过检查之后再执行。迁移文件的好处是:它有名字、有版本、能回滚、能进代码评审。直接在对话里跑 UPDATE,什么都没有,错了都不知道是哪句话错的。
这个分开还有一个原因:分析会话和修复会话需要的上下文不一样。分析的时候,Agent 需要的是“只读、谨慎、每个数字都能复核”;修复的时候,需要的是“先备份、影响范围先算出来、执行完验证一遍”。混在一个会话里,两种要求会互相干扰。分开之后,每种会话的规矩都更简单,也更容易执行。
如果确实要在分析的过程里发现了一个需要修的数据,正确的做法是:让 Agent 把问题和修复方案写下来,停在那里,不要执行。你看完方案,确认影响范围(先跑一条 SELECT COUNT(*) 看看会动多少行),再决定是走迁移文件,还是单独开一个修复会话。这个“停一下”的动作,就是第五道护栏本身。
还有一个容易被忽略的细节:查数的时间越长,数字越容易“漂移”。一份报表要跑好几分钟,中间如果有新订单进来,前面的查询和后面的查询看到的数据就不一样了,最后拼出来的总数对不上。PostgreSQL 的做法是给长报表开一个 REPEATABLE READ 事务:从第一条查询开始,整个事务看到的都是同一份快照,后面再进来什么数据都不影响它。更讲究的做法是再加上 SERIALIZABLE 和 DEFERRABLE,文档里明确说这种组合“很适合跑长报表或者备份”。日常随手查一下用默认的 READ COMMITTED 就够了,但只要是“要跑一阵子、结果要对得上”的报表,先把隔离级别想清楚,再让 Agent 动手。
一个完整的例子:从“上周卖了多少”到可信的数字
下面用一个虚构的 shop 数据库走一遍完整流程。这个例子是编的,表名和数字都是为了演示,别当成真实数据。问题是:“上周付费订单有多少笔?”
Agent 第一版 SQL 可能是这样的:
SELECT count(*) FROM orders WHERE created_at >= '2026-11-09';
按规则二,你先检查:漏了状态过滤(退款和取消的订单也被算进去了),时间范围只有下限没有上限(“上周”被算成了“11 月 9 日之后的所有时间”),时区也没说明。让 Agent 改成这样:
SELECT count(*) FROM orders
WHERE status = 'paid'
AND created_at >= '2026-11-09 00:00:00+08'
AND created_at < '2026-11-16 00:00:00+08';
按规则三,先跑 EXPLAIN 看一眼:有没有用到 created_at 上的索引?预估行数和表的实际规模差多少?如果 EXPLAIN 显示顺序扫描一张几十万行的表,先别急着执行,问一句“要不要先加个索引,或者把时间范围拆小”。按规则一,执行的时候走只读事务。按规则四,回答里附上查询、行数和时间范围。最后按规则五,如果发现有一批订单的状态标错了需要修,写下来,走迁移,不在这次会话里动手。
这个例子里每条规则都只多花几十秒,但拦住的是三类真实错误:漏过滤、错时区、误改数据。五条规则合起来,就是一句话:Agent 查数的时候,慢一点没关系,错了才麻烦。
检查清单:贴在你的项目里
最后是一份可以直接用的检查清单,贴进 CLAUDE.md 或者 AGENTS.md 就能生效。Agent 查数据库之前,先确认这五条:第一,连接是只读的,事务以 READ ONLY 开始;第二,SQL 先写出来给你看,确认再执行;第三,EXPLAIN 先看计划,EXPLAIN ANALYZE 只对 SELECT 用,写操作必须包在 BEGIN 和 ROLLBACK 里;第四,每个数字附带完整查询、行数和时间范围;第五,写操作不走分析会话,单独写迁移或者修复脚本。
还有三条是给“查不到”的时候准备的。Agent 说“查不到”或者“表不存在”,先别让它自己猜:让他把数据库的表清单列出来(比如 SELECT table_name FROM information_schema.tables),对照着看是表名错了,还是连错了库。如果查询报权限错误,说明只读账号的权限没配好,修权限,别为了省事换成读写账号。如果 Agent 说“数据看起来不对”,先怀疑统计信息过期或者时区,让它把原始行抽几条出来看,别直接信它的解释。
这份清单还有一个隐含的好处:它让“查数”这件事变得可以交接。新人加入项目,问“这个数字怎么来的”,你不用再口头解释一遍,直接指给他看:查询在这里、规则在这里、复核方法在这里。Agent 的工作流和人的工作流用的是同一套护栏,团队里每个人查出来的数字口径一致,就不会出现“你算的 1284、我算的 1310,到底谁对”的争论。数字的口径一致,比数字本身更重要。反过来想,一个没有护栏的团队,数字的口径会随着每次提问悄悄漂移:这次 Agent 用了 UTC,下次用了本地时间;这次排除了退款订单,下次忘了。等你发现数字对不上,已经不知道哪一次算的是对的。护栏的价值就在于此:它不是为了防一次事故,而是为了让每一次的结果都能复现、都能追溯。
这份清单不需要你一次全做到。先做到第一条——只读连接——你就已经拦住了最危险的错误。剩下的四条,每次用的时候加一条,一个月之后就是完整的工作流。Agent 查数据库这件事,护栏不是越多越好,是越早立越好。
评论 (0)
原始来源
相关文章
Flexbox 一次只排一个方向,排对了,导航栏、卡片墙、购物车行都听话。本文按 MDN 的《Basic concepts of flexbox》《Aligning items in a flex container》《Controlling ratios of flex items along the main axis》三篇官方文档讲清楚:两根轴、容器与项目、方向与换行、剩余空间、flex 三件套、两根轴上的对齐、间距与自动边距。
2026 年 11 月 17 日,微软发布 MAI Code 2 和 Code 2 Flash:大模型 770 亿激活参数、100 万上下文,四项基准平均通过率 63.2%,与 GPT-6.1 Sol、Claude Opus 5.5 咬得很紧,但每任务成本只有 0.309 美元。先看清三处“但是”:价格是推广价、分数是三者最低、长周期任务不在舒适区。
2026 年 11 月 11 日,AWS 开源 UAEF:先把 LangGraph、LangChain、Strands、Bedrock AgentCore 等框架的运行记录翻成统一格式,再用 36 个指标、7 个维度打分,回归超过 5% 就亮灯。评审模型本身也被防了一手:打分要引原文作证,分数不能用来决定安全放行。