seekdb 可复现 SQL 验证

把数据库结论变成其他人可以按相同步骤重跑的证据。优先使用最小数据集、明确断言和真实 seekdb 实例；不要把命令成功退出当作业务结果正确。

开始前

先确认以下信息，缺少时从项目配置和现有测试中查找；只有关键选择会改变结果时才询问用户：

待验证的 SQL、功能或缺陷；
预期行为，以及哪些输出字段构成通过条件；
seekdb 连接方式和版本；
是否允许创建临时数据库或表；
是否需要保留现场供后续检查。

密码、令牌和完整连接串只从环境变量或本机凭据读取。证据中记录主机类型、端口和用户角色即可，所有秘密替换为 <redacted>。

验证流程

1. 固定运行环境

连接真实 seekdb 后，先执行：

SELECT VERSION() AS seekdb_version;
SELECT DATABASE() AS current_database;

记录客户端名称、seekdb 版本和测试时间。若连接的是 MySQL、MariaDB 或模拟器，明确标注，不能把结果写成 seekdb 验证。

2. 建立最小夹具

使用只服务于本次验证的数据库或带唯一前缀的表名。夹具应满足：

数据行数量尽量少，但覆盖正常、边界和空结果；
主键及排序字段固定，避免依赖未声明的行顺序；
建表、插入和查询 SQL 完整保存；
重跑前只清理明确命名的测试对象。

不要删除用户现有的数据库、表或数据。清理范围无法确认时，保留现场并报告对象名称。

3. 把预期写成断言

为每个目标行为定义可观察条件，例如：

| 条件 | 可观察证据 | | --- | --- | | 返回正确记录 | 主键集合与预期集合相同 | | 排序稳定 | ORDER BY 明确，结果顺序逐项匹配 | | 过滤正确 | 应包含与应排除的行分别列出 | | 计划使用目标索引 | 保存 EXPLAIN 输出并指出目标节点 | | 写入正确 | 写入后重新查询，不仅检查受影响行数 |

不要只截取有利的几行。结果较长时，保存完整原始输出，并在摘要中引用决定结论的行。

4. 执行并保存原始结果

优先使用项目已有测试入口。没有入口时，可使用 MySQL 兼容客户端或 Python DB-API 执行同一份 SQL 文件。每次运行保存：

实际命令，秘密已脱敏；
标准输出和标准错误；
进程退出码；
SQL 文件与夹具文件的 SHA-256；
每条断言的通过或失败状态。

服务端返回错误时，保留错误码、SQLSTATE 和消息。先区分服务端 SQL 错误、客户端转义错误、网络错误和测试断言失败，再决定是否修改 SQL。

5. 比较修复前后

验证代码或配置修复时，使用相同的 seekdb 版本、夹具、查询和断言分别运行修复前与修复后版本。至少证明：

修复前目标断言失败；
修复后同一断言通过；
相关回归断言仍通过。

如果无法运行修复前版本，明确写成“仅验证当前版本”，不要构造失败记录。

证据目录

建议交付以下最小结构：

evidence/
├── environment.txt
├── setup.sql
├── query.sql
├── expected.md
├── stdout.txt
├── stderr.txt
└── result.md

result.md 使用以下格式：

# seekdb SQL 验证结果

- 目标：<一句话描述>
- 版本：<SELECT VERSION() 的结果>
- 结论：PASS / FAIL / BLOCKED
- 夹具：<数据库、表、数据规模>

## 断言

| 断言 | 预期 | 实际 | 状态 |
| --- | --- | --- | --- |
| <名称> | <预期> | <实际> | PASS/FAIL |

## 复现

<脱敏后的命令和文件顺序>

## 限制

<未覆盖的版本、数据规模或运行条件>

提交前检查

确认测试确实连接 seekdb，并记录 SELECT VERSION() 结果；
确认所有结论都有 SQL 输出或断言支撑；
确认 SQL、夹具和预期可由第三方独立执行；
确认输出中没有密码、令牌、Cookie、内网地址或个人数据；
确认未把临时验证扩大成无关的性能或兼容性结论；
确认清理操作只针对本次创建的测试对象。