# PostgreSQL / MySQL Runtime Smoke 环境建议

## 结论

当前阶段的推荐方案是：**让 QA 在宿主机执行 smoke，但数据库仍使用仓库内的 Docker Compose 临时拉起**。

- 继续复用现有 `docker-compose.demo.yml`、bootstrap 脚本和 SQL fixtures
- 不依赖长期运行的宿主机 PostgreSQL / MySQL
- 不在当前阶段扩展 `local-db-codex` 运行时去支持 Docker

这条路径最符合当前项目状态：仓库里的 smoke 输入已经存在，真正缺的是一个有 Docker 的执行宿主，而不是新的产品代码或平台改造。

## 三种方案对比

### 方案 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

结论：**这是当前推荐方案。**

## 推荐执行方式

### 宿主机要求

- Linux 或 macOS 宿主机
- 已安装 Docker 和 `docker compose`
- 可运行 Rust `cargo`，或已取得本仓库 release / debug 二进制
- 2026-03-26 当前 QA agent runner 不满足该要求：它有 `node v24.14.0` 和预编译 `target/release/dbtool`，但缺少 `docker` 与 `cargo`

### 使用步骤

1. 在宿主机拉取当前仓库代码并进入项目根目录
2. 准备 CLI：
   - 开发验证：`cargo build`
   - 或使用已生成的 `target/debug/dbtool` / `target/release/dbtool`
3. 导出密码环境变量：

```bash
export DBTOOL_PASSWORD=dbtool
```

4. 拉起 PostgreSQL / MySQL：

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

5. 导入 demo 数据：

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

6. 按 `SMOKE_RUNBOOK.md` 执行 PostgreSQL / MySQL 的 `connect` / `inspect` / `query` / `export`
7. 将结果回填到 `ACCEPTANCE_CHECKLIST.md`、`TEST_STRATEGY.md`、`PRE_RELEASE_CHECKLIST.md`
8. 清理环境：

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

## 团队职责

- 后端：维护 `docker-compose.demo.yml`、bootstrap 脚本、fixtures 和命令契约
- QA：在宿主机执行 smoke，沉淀证据和失败复现记录
- 前端：当前继续 gated，不参与此轮 runtime smoke
- CTO：维持方案边界；若没有 Docker-capable host，再升级为平台支持请求

## 风险与维护成本

- 宿主机不可用：需要指定一台固定 QA 主机或自托管 runner
- 二进制与文档漂移：QA 执行时必须绑定具体 commit 或 release artifact
- 端口冲突：优先使用专用 QA 主机；必要时再参数化 compose 端口
- 当前 runner 与目标宿主能力不一致：本地可继续复核 SQLite 与预编译二进制，但 PostgreSQL / MySQL Docker smoke 必须迁移到符合要求的宿主机

总体维护成本低，因为主路径复用仓库现有资产，不引入新的长期数据库运维负担，也不引入新的平台能力改造。