# 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:

```bash
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):

```json
{
  "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:

```bash
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):

```json
{
  "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:

```bash
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):

```json
{
  "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 回归候选。