# PostgreSQL / MySQL Runtime Smoke 环境建议

## 结论

当前阶段的目标推荐方案是：**让 QA agent 直接在升级后的 `local-db-codex` 容器内执行 smoke，并通过挂载宿主机 Docker daemon、Docker 配置、Cargo 与 Rustup 目录来复用宿主能力**。

- 继续复用现有 `docker-compose.demo.yml`、bootstrap 脚本和 SQL fixtures
- 不依赖长期运行的宿主机 PostgreSQL / MySQL
- 不再要求 QA 手动切回宿主机执行
- 将 Docker、Rust、Cargo mirror、Docker registry mirror 的能力统一沉淀到容器运行时

在该部署升级完成前，宿主机执行仍然是可用 fallback；但后续默认路径应转向容器内 agent 自行完成 smoke。

2026-03-26 的 [CMP-17](/CMP/issues/CMP-17#comment-0cd53e93-25a5-456b-8dba-31ea098c2aa8) 已证明该路径可以成立：宿主机 PostgreSQL / MySQL smoke 已执行完成，因此“当前 QA runner 无 Docker”只代表本 agent 本地限制，不再代表方案无效。

## 三种方案对比

### 方案 A：宿主机长期运行 PostgreSQL / MySQL

优点：

- 首次接入快
- QA 不需要每次拉起容器

缺点：

- 状态容易漂移，重复执行时很难保证数据库干净
- 需要长期维护端口、用户、权限和版本
- 一旦多人共用宿主机，测试数据会互相污染
- 更适合共享开发环境，不适合作为 release smoke 证据来源

结论：**可作为临时兜底，不作为推荐主路径。**

### 方案 B：为 `local-db-codex` 部署增加 Docker runtime 能力

优点：

- 从 agent 视角最方便，理论上可以把 smoke 也放回当前容器体系
- 后续若多个项目都依赖容器型集成测试，长期上限更高

缺点：

- 这是平台/安全/运维改造，不是当前仓库内的小改动
- 会引入容器嵌套、权限边界、镜像缓存、资源隔离等额外复杂度
- 当前项目的真实瓶颈是缺可执行宿主，不是缺应用层代码

结论：**不适合作为本阶段 unblock 手段，只在未来多个项目都提出同类需求时再立项。**

### 方案 C：QA runner 在宿主机执行，数据库通过 Docker Compose 临时拉起

优点：

- 直接复用现有仓库资产，落地最快
- 每次 `up` / `down -v` 都是干净环境，可重复性最好
- 不要求改 `local-db-codex` 平台
- 后续可平滑迁移到自托管 runner 或专用 QA 主机

缺点：

- 需要一台具备 Docker / `docker compose` 的宿主机
- 宿主机上仍需准备 Rust toolchain 或 release binary

结论：**作为 fallback 可用，但不再是长期目标路径。**

### 方案 D：升级 `local-db-codex`，让 agent 在容器内复用宿主机 Docker 和 Rust

优点：

- agent 可直接在容器内执行 PostgreSQL / MySQL Docker-backed smoke
- 后续每个功能实现后的测试路径一致，不需要在人和 agent 之间切换执行环境
- 继续复用宿主机 Docker daemon 的镜像缓存、registry mirror 和权限体系
- 继续复用宿主机 Rust toolchain、Cargo 配置和 crates mirror 配置

缺点：

- 需要维护容器与宿主机之间的挂载关系
- Docker socket 暴露会提升容器能力边界，需明确接受该风险
- 宿主机 Docker / Rust 环境本身出问题时，容器内 agent 会继承同样问题

结论：**这是后续迭代的目标方案。**

## 推荐执行方式

### 容器化 QA runner 要求

- `deploy/local-db-codex` 已升级，挂载：
  - 宿主机 Docker socket
  - 宿主机 Docker config
  - 宿主机 Cargo home
  - 宿主机 Rustup home
- 容器内可直接运行：
  - `docker`
  - `cargo`
  - `rustc`
- 宿主机 Docker daemon 已配置好 registry mirror（如有）
- 宿主机 Cargo / Rustup mirror 配置已就绪（如有）

### 使用步骤

1. 启动升级后的 `local-db-codex` 部署
2. 进入 agent 所在容器运行环境，确认 `docker`、`cargo`、`rustc` 可用
3. 在工作区准备 CLI：
   - 开发验证：`cargo build`
   - 或使用已生成的 `target/debug/dbtool` / `target/release/dbtool`
4. 导出密码环境变量：

```bash
export DBTOOL_PASSWORD=dbtool
export DBTOOL_POSTGRES_ADMIN_PASSWORD=dbtoolroot
```

5. 拉起 PostgreSQL / MySQL：

```bash
docker compose -f docker-compose.demo.yml up -d postgres mysql
```

6. 导入 demo 数据：

```bash
./examples/scripts/bootstrap-postgres.sh
./examples/scripts/bootstrap-mysql.sh
```

如果本机 PostgreSQL demo 容器早于本轮权限修正创建，先清旧卷再重建：

```bash
docker compose -f docker-compose.demo.yml down -v
docker compose -f docker-compose.demo.yml up -d postgres mysql
./examples/scripts/bootstrap-postgres.sh
./examples/scripts/bootstrap-mysql.sh
```

PostgreSQL demo 当前权限边界：

- `postgres` / `dbtoolroot`：只用于 seed、restricted probe 建立与清理
- `dbtool` / `dbtool`：QA 与 TUI/CLI live 路径使用的非超级用户

可先验证 `dbtool` 不再是超级用户：

```bash
PGPASSWORD="$DBTOOL_POSTGRES_ADMIN_PASSWORD" \
psql -h 127.0.0.1 -p 55432 -U postgres -d dbtool_demo \
  -c "select rolname, rolsuper, rolcreaterole, rolcreatedb from pg_roles where rolname='dbtool';"
```

PostgreSQL restricted-schema 最小复验步骤：

```bash
PGPASSWORD="$DBTOOL_POSTGRES_ADMIN_PASSWORD" \
psql -h 127.0.0.1 -p 55432 -U postgres -d dbtool_demo <<'SQL'
drop schema if exists restricted_probe cascade;
create schema restricted_probe;
create table restricted_probe.audit_log (
  id bigint primary key,
  note text not null
);
insert into restricted_probe.audit_log values (1, 'hidden from dbtool');
revoke all on schema restricted_probe from public;
revoke all on all tables in schema restricted_probe from public;
revoke all on schema restricted_probe from dbtool;
revoke all on all tables in schema restricted_probe from dbtool;
SQL

export DBTOOL_PASSWORD=dbtool
cargo run -p dbtool-cli -- inspect --driver postgres --host 127.0.0.1 --port 55432 --database dbtool_demo --username dbtool --password-env DBTOOL_PASSWORD
cargo run -p dbtool-cli -- inspect --driver postgres --host 127.0.0.1 --port 55432 --database dbtool_demo --username dbtool --password-env DBTOOL_PASSWORD --schema restricted_probe
```

预期：

- root inspect 出现 `restricted_probe [restricted]`
- 显式 `--schema restricted_probe` 返回 restricted inspect error，而不是 empty tables

清理：

```bash
PGPASSWORD="$DBTOOL_POSTGRES_ADMIN_PASSWORD" \
psql -h 127.0.0.1 -p 55432 -U postgres -d dbtool_demo \
  -c "drop schema if exists restricted_probe cascade;"
```

7. 按 `SMOKE_RUNBOOK.md` 执行 PostgreSQL / MySQL 的 happy-path；按 `HOST_FAILURE_PATH_CHECKLIST.md` 执行 failure-path
8. 将结果回填到 `ACCEPTANCE_CHECKLIST.md`、`TEST_STRATEGY.md`、`PRE_RELEASE_CHECKLIST.md`
9. 清理环境：

```bash
docker compose -f docker-compose.demo.yml down -v
```

## Failure-path 执行入口

- PostgreSQL / MySQL happy-path 继续使用 `SMOKE_RUNBOOK.md`
- PostgreSQL / MySQL failure-path 统一使用 `HOST_FAILURE_PATH_CHECKLIST.md`
- 证据记录格式继续以 `FAILURE_PATH_EVIDENCE_TEMPLATE.md` 为准
- 在发起宿主机或 sidecar live 执行前，先跑离线夹具收敛 helper / wrapper 契约：

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

- 若只想检查单一路径，可改跑：

```bash
scripts/qa/test-failure-path-fixtures.sh format
scripts/qa/test-failure-path-fixtures.sh sidecar
```

## 2026-03-28 当前容器化 runner 观察

- QA runner 已可访问 Docker daemon，但当前仍缺 `docker compose` 子命令。
- QA runner 不能直接访问 `127.0.0.1:55432/53306`，也不能直接访问 demo 数据库容器 IP。
- 当前有效补充路径是：
  1. 复用已运行的 `dbtool-cli-v1-postgres-1` / `dbtool-cli-v1-mysql-1`
  2. 用 `docker exec` 直接导入 PostgreSQL / MySQL demo 数据
  3. 创建 sidecar container 并加入 `dbtool-cli-v1_default` 网络
4. 在 sidecar container 内执行 `dbtool`，默认主机名跟随 `QA_POSTGRES_CONTAINER` / `QA_MYSQL_CONTAINER`（当前默认是 `dbtool-cli-v1-postgres-1` / `dbtool-cli-v1-mysql-1`）

这条 sidecar network execution 路径在 2026-03-28 当前 heartbeat 已被直接验证，可用于继续补 PostgreSQL / MySQL failure-path 证据。

为减少重复手工步骤，当前仓库已提供：

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

这条脚本化路径会自动完成：

- PostgreSQL / MySQL demo 数据重导入
- sidecar container 创建与清理
- sidecar 内 failure-path helper 执行
- 证据文件回传到本地输出目录
- 当前 PostgreSQL sidecar 重导入默认使用 `postgres` / `dbtoolroot`；若宿主机 demo 管理员身份被改写，可改传 `QA_POSTGRES_ADMIN_USER` / `QA_POSTGRES_ADMIN_PASSWORD`

## 团队职责

- 后端：维护 `docker-compose.demo.yml`、bootstrap 脚本、fixtures、命令契约和容器内 smoke 兼容性
- QA：优先在容器内 agent 运行环境执行 smoke，沉淀证据和失败复现记录
- 前端：当前继续 gated，不参与此轮 runtime smoke
- CTO：维持方案边界，并确保 `local-db-codex` 能长期承载容器内 smoke

## 风险与维护成本

- Docker socket 暴露：容器获得了较强的宿主机控制能力，必须明确接受这一安全边界。
- 宿主机 Docker / Rust 环境漂移：容器会继承宿主机配置，出现问题时必须同时排查宿主机。
- 二进制与文档漂移：QA 执行时必须绑定具体 commit 或 release artifact。
- 端口冲突：必要时继续参数化 compose 端口。
- 当前已知结论：宿主机 patched-run 已确认 MySQL 中文与 emoji 输出正常，问题根因收敛到 bootstrap/import 字符集路径；后续需要把这类验证稳定迁入容器内 smoke 路径。

总体维护成本可控，因为主路径继续复用仓库现有 smoke 资产，只是把执行宿主从人工宿主机切换成可复用宿主能力的 Paperclip 容器。