dbtool-cli-v1/FAILURE_PATH_EVIDENCE_TEMPLATE.md

PostgreSQL / MySQL Failure-Path Evidence Template

日期：2026-03-28
作者：Senior Backend Engineer
用途：dbtool-usable-v1 在 PostgreSQL / MySQL failure-path 上补齐可审计证据，供 QA / CTO 直接复用。

配套样例：FAILURE_PATH_EVIDENCE_SAMPLE.md

1. 适用范围

• 当前仅覆盖 connect、query 的 failure-path。
• 目标是把 release gate 中“PostgreSQL / MySQL failure-path 仍缺可审计执行证据”这条 blocker 收口为可执行清单。
• 不扩展产品范围，不引入新能力，不替代 SMOKE_RUNBOOK.md 的 happy-path 验证。

2. 执行前置

• 执行环境：Docker-capable 宿主机（当前 QA runner 仍缺 docker）。
• 已完成：
  • docker compose -f docker-compose.demo.yml up -d postgres mysql
  • ./examples/scripts/bootstrap-postgres.sh
  • ./examples/scripts/bootstrap-mysql.sh
• CLI 可执行：
  • 推荐 ./target/release/dbtool
  • 或 cargo run -q -p dbtool-cli -- <args>
• 若想减少人工整理，可直接运行：

scripts/qa/run-failure-path-evidence.sh ./target/release/dbtool all ./tmp/failure-path-evidence

脚本会为 6 个场景分别生成 .out 与 .md 证据文件，便于直接贴回 issue 评论。 当前 helper 还会把可检测到的密码泄露模式直接判成 fail：

• 错误密码场景：对原始密码值做精确匹配
• 真实密码场景：检查常见泄露模式，例如 password=<value>、"password":"<value>"、:<value>@
• 若 Binary Version、Commit SHA、Branch、Host 等 traceability 字段缺失或退化为 unknown-*，helper 也会直接判成 fail

若执行环境不是宿主机直连，而是 sidecar container / 自定义网络路径，可覆盖默认 host / port：

DBTOOL_POSTGRES_HOST=postgres \
DBTOOL_POSTGRES_PORT=5432 \
DBTOOL_MYSQL_HOST=mysql \
DBTOOL_MYSQL_PORT=3306 \
scripts/qa/run-failure-path-evidence.sh ./target/release/dbtool all ./tmp/failure-path-evidence

若当前 QA runner 只能通过 Docker daemon + sidecar 网络接入数据库，也可直接运行：

scripts/qa/run-failure-path-evidence-sidecar.sh ./target/release/dbtool ./tmp/failure-path-evidence

该脚本会：

• 重新导入 PostgreSQL / MySQL demo 数据
• 创建 sidecar container 加入 dbtool-cli-v1_default
• 在 sidecar 内调用 scripts/qa/run-failure-path-evidence.sh
• 将生成的 .out / .md 证据包复制回本地输出目录
• 继承宿主发起侧的 host / binary / version / commit / branch 标签，避免 sidecar 与 host-run 两条路径出现双口径 traceability

3. 追溯字段（每条证据都要填）

• Date (UTC):
• Operator:
• Host:
• Execution Path:
• Binary Path:
• Binary Version (--version):
• Commit SHA:
• Branch:
• Driver:
• Scenario ID:
• Command:
• Exit Code:
• Key Output:
• Verdict (pass / fail):

说明：

• helper 当前会自动生成并校验这些字段中的大部分内容。
• 若生成结果出现 unknown-version、unknown-commit、unknown-branch、unknown-host 或空值，应视为 traceability 不完整。
• Execution Path 推荐使用：
  • host
  • sidecar

如需先确认 helper 与 sidecar wrapper 的离线夹具回归仍通过，可直接运行：

scripts/qa/test-failure-path-fixtures.sh

4. 场景矩阵

Scenario ID	Driver	Command	Failure Type	JSON Expectation
PG-CONN-AUTH-001	postgres	connect	错误密码	status=error, state=error, error.kind=authentication
PG-CONN-NET-001	postgres	connect	不可达端口	status=error, state=error, error.kind=connection
PG-QUERY-SQL-001	postgres	query	坏 SQL / 不存在对象	status=error, state=error, error.kind=query
MY-CONN-AUTH-001	mysql	connect	错误密码	status=error, state=error, error.kind=authentication
MY-CONN-NET-001	mysql	connect	不可达端口	status=error, state=error, error.kind=connection
MY-QUERY-SQL-001	mysql	query	坏 SQL / 不存在对象	status=error, state=error, error.kind=query

说明：

• status 是 envelope 级结果（success / error）。
• state 是共享状态映射（失败路径应为 error）。

5. 命令模板

先设置正确密码，再按场景覆盖：

export DBTOOL_PASSWORD=dbtool

PostgreSQL

错误密码：

export DBTOOL_PASSWORD=wrong-password
./target/release/dbtool connect --driver postgres --host 127.0.0.1 --port 55432 --database dbtool_demo --username dbtool --password-env DBTOOL_PASSWORD --result-format json

网络不可达：

export DBTOOL_PASSWORD=dbtool
./target/release/dbtool connect --driver postgres --host 127.0.0.1 --port 59999 --database dbtool_demo --username dbtool --password-env DBTOOL_PASSWORD --result-format json

坏 SQL：

export DBTOOL_PASSWORD=dbtool
./target/release/dbtool query --driver postgres --host 127.0.0.1 --port 55432 --database dbtool_demo --username dbtool --password-env DBTOOL_PASSWORD --file examples/sql/postgres/failing_query.sql --result-format json

MySQL

错误密码：

export DBTOOL_PASSWORD=wrong-password
./target/release/dbtool connect --driver mysql --host 127.0.0.1 --port 53306 --database qa_demo --username dbtool --password-env DBTOOL_PASSWORD --result-format json

网络不可达：

export DBTOOL_PASSWORD=dbtool
./target/release/dbtool connect --driver mysql --host 127.0.0.1 --port 59998 --database qa_demo --username dbtool --password-env DBTOOL_PASSWORD --result-format json

坏 SQL：

export DBTOOL_PASSWORD=dbtool
./target/release/dbtool query --driver mysql --host 127.0.0.1 --port 53306 --database qa_demo --username dbtool --password-env DBTOOL_PASSWORD --file examples/sql/mysql/failing_query.sql --result-format json

6. 证据记录模板

### <Scenario ID>

- Date (UTC):
- Operator:
- Host:
- Binary Path:
- Binary Version:
- Commit SHA:
- Branch:
- Command:
- Exit Code:

Output (excerpt):
```json
{
  "status": "error",
  "operation": "connect",
  "state": "error",
  "error": {
    "kind": "authentication"
  }
}
```

Verdict:
- Expected:
- Actual:
- Result: pass | fail

7. 收口标准

• 上述 6 个场景每个至少一条可审计记录。
• 每条记录都包含追溯字段和命令输出摘要。
• USABLE_EVIDENCE_LEDGER.md 的 PostgreSQL / MySQL failure-path 行更新为 verified 或明确保留 blocked 原因。
• USABLE_RELEASE_GATE.md 的对应 blocker 条目同步更新。
• 若使用 scripts/qa/run-failure-path-evidence.sh，仍需人工确认生成的 Result、traceability 字段与场景归类是否与实际执行一致，再回填到共享台账。