dbtool-cli-v1/FAILURE_PATH_EVIDENCE_SAMPLE.md

PostgreSQL / MySQL Failure-Path Evidence Sample

日期：2026-03-28
作者：Senior Backend Engineer
用途：给 QA / CTO 一份可直接复制改值的 failure-path 记录样例。

使用方式

• 本文件是“填写示例”，不是执行证据本身。
• 只有把其中的时间、宿主机、二进制路径、commit、命令输出替换为真实值后，才能回填到 USABLE_EVIDENCE_LEDGER.md 或 issue 评论中。
• 正式场景列表与命令来源仍以 FAILURE_PATH_EVIDENCE_TEMPLATE.md 为准。

Sample A: PostgreSQL Wrong Password

PG-CONN-AUTH-001

• Date (UTC): 2026-03-28T14:10:00Z
• Operator: qa-engineer
• Host: qa-host-01
• Binary Path: ./target/release/dbtool
• Binary Version: 0.1.0
• Commit SHA: <replace-with-real-sha>
• Branch: <replace-with-real-branch>
• Driver: postgres
• Scenario ID: PG-CONN-AUTH-001
• Command:

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

• Exit Code: 2

Output (excerpt):

{
  "status": "error",
  "operation": "connect",
  "state": "error",
  "error": {
    "operation": "connect",
    "kind": "authentication",
    "message": "postgres authentication failed"
  }
}

Verdict:

• Expected: status=error, state=error, error.kind=authentication, 无密码泄露
• Actual: JSON envelope 返回 authentication，未回显 password env 的实际值
• Result: pass

Sample B: MySQL Unreachable Port

MY-CONN-NET-001

• Date (UTC): 2026-03-28T14:18:00Z
• Operator: qa-engineer
• Host: qa-host-01
• Binary Path: ./target/release/dbtool
• Binary Version: 0.1.0
• Commit SHA: <replace-with-real-sha>
• Branch: <replace-with-real-branch>
• Driver: mysql
• Scenario ID: MY-CONN-NET-001
• Command:

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

• Exit Code: 2

Output (excerpt):

{
  "status": "error",
  "operation": "connect",
  "state": "error",
  "error": {
    "operation": "connect",
    "kind": "connection",
    "message": "connection failed: Connection refused (os error 111)"
  }
}

Verdict:

• Expected: status=error, state=error, error.kind=connection
• Actual: JSON envelope 返回 connection，符合不可达端口预期
• Result: pass

Sample C: PostgreSQL Bad SQL

PG-QUERY-SQL-001

• Date (UTC): 2026-03-28T14:25:00Z
• Operator: qa-engineer
• Host: qa-host-01
• Binary Path: ./target/release/dbtool
• Binary Version: 0.1.0
• Commit SHA: <replace-with-real-sha>
• Branch: <replace-with-real-branch>
• Driver: postgres
• Scenario ID: PG-QUERY-SQL-001
• Command:

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

• Exit Code: 2

Output (excerpt):

{
  "status": "error",
  "operation": "query",
  "state": "error",
  "error": {
    "operation": "query",
    "kind": "query",
    "message": "query failed: relation does not exist"
  }
}

Verdict:

• Expected: status=error, state=error, error.kind=query
• Actual: JSON envelope 返回 query，错误定位在 SQL 执行阶段
• Result: pass

回填规则

• 一次执行至少保留：
  • 完整命令
  • 退出码
  • 关键 JSON 片段
  • 实际 commit / branch
• 若输出和样例文案不同，只要 status、state、error.kind 与场景预期一致，可以判为 pass。
• 若 error.kind 偏离预期，应优先回填到 issue，并视为 backend contract 回归候选。