dbtool-cli-v1/DEVELOPING.md

Developing dbtool-cli-v1

本地开发

cargo fmt
cargo test
cargo run -p dbtool-cli -- --help

TUI 开发验证补充：

cargo build -p dbtool-tui
scripts/tui/smoke-tty.sh ./target/debug/dbtool-tui
scripts/tui/smoke-tty.sh ./target/debug/dbtool-tui 20 90 /tmp/dbtool-tui-small.log

dbtool-tui 需要 TTY；不要用 cargo run -p dbtool-tui -- --help 替代交互 smoke。详细口径见 TUI_SMOKE_RUNBOOK.md。

failure-path 证据 helper / sidecar wrapper 的离线回归入口：

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

需要缩小范围时可改跑：

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

Git 仓库、branch、commit、push 与 agent 认证规范见 GIT_WORKFLOW.md。

如果当前 Linux 环境没有 cc / ar，改用 zig cc + zig ar。对 bundled SQLite 路径，linker 包装器需要兼容 Cargo 传入的 GNU target flag：

cat > /tmp/zig-cc <<'EOF'
#!/usr/bin/env bash
set -euo pipefail
args=()
for arg in "$@"; do
  case "$arg" in
    --target=x86_64-unknown-linux-gnu)
      args+=("--target=x86_64-linux-gnu")
      ;;
    *)
      args+=("$arg")
      ;;
  esac
done
exec zig cc "${args[@]}"
EOF
cat > /tmp/zig-ar <<'EOF'
#!/usr/bin/env bash
set -euo pipefail
exec zig ar "$@"
EOF
chmod +x /tmp/zig-cc /tmp/zig-ar
export CC=/tmp/zig-cc
export AR=/tmp/zig-ar
export CARGO_TARGET_X86_64_UNKNOWN_LINUX_GNU_LINKER=/tmp/zig-cc

# 如果当前环境的 rustup 没有默认 toolchain，可显式指定 stable 工具链
export RUSTC="$(rustup which --toolchain stable rustc)"
export RUSTDOC="$(rustup which --toolchain stable rustdoc)"
"$(dirname "$RUSTC")/cargo" test --workspace
"$(dirname "$RUSTC")/cargo" build --release --bin dbtool
./target/release/dbtool --help

当前 crate 责任

• apps/cli：命令行入口、参数解析、退出码与用户可见输出
• crates/db-core：领域模型、输入约束、公共错误
• crates/db-config：连接 profile、配置抽象、脱敏摘要
• crates/db-drivers：驱动 trait 与按数据库分发的边界

当前约束

• 当前 PostgreSQL、MySQL 与 SQLite 已实现真实数据库 I/O
• export 已通过共享查询结果模型实现 CSV / JSON 写出
• 子命令的 flag 形状已稳定到可供 QA / GUI 复用的程度，后续只能做兼容性演进
• 错误信息必须避免泄露密码等敏感信息
• PostgreSQL 非参数化查询使用 simple query，可执行多语句 SQL 文件；带 --param 时会切到 prepared execution，因此应传单条参数化语句
• MySQL 非参数化查询使用 text protocol，可执行多语句 SQL 文件；带 --param 时会切到 positional prepared execution，因此应传单条参数化语句
• MySQL inspect 继续复用 --schema flag，但语义上对应数据库名
• SQLite inspect 也复用 --schema flag，但 demo 路径固定使用 main
• SQLite 查询当前按单条 statement 执行；多语句 SQL 会返回显式错误，而不是隐式忽略后续语句
• export 当前要求查询必须返回结果集；非结果集语句会被明确拒绝
• export 当前要求父目录已存在，且默认拒绝覆盖已有文件，除非显式传入 --overwrite

验证路径

• cargo build 验证 workspace 可编译
• cargo test 验证核心输入校验、脱敏逻辑和 CLI 参数解析
• cargo run -p dbtool-cli -- --help 验证 CLI 可启动
• cargo run -p dbtool-cli -- connect --help 与 cargo run -p dbtool-cli -- inspect --help 验证关键子命令可启动
• cargo run -p dbtool-cli -- query ... --file <sql> 验证 SQL 文件读取入口
• cargo run -p dbtool-cli -- export ... --format <csv|json> --output <path> 验证导出路径
• ./examples/scripts/bootstrap-sqlite.sh + SQLite CLI happy path 验证本地样例数据库闭环
• scripts/qa/test-failure-path-fixtures.sh 验证 failure-path evidence helper 与 sidecar wrapper 的离线契约
• 无系统 linker 的 Linux 环境使用兼容 Cargo target flag 的 zig cc 包装器与 zig ar 验证路径

发布 smoke

• GitHub Actions baseline: .github/workflows/release-smoke.yml
• 发布与回滚说明：RELEASE_RUNBOOK.md
• 本地 Linux 产物复核：scripts/release/smoke-binary.sh <binary> 与 scripts/release/package-unix.sh <target-triple> <binary>