paperclip/dbtool-cli-v1
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
agent/cto/CMP-18-git-bootstrap
dbtool-cli-v1/plans/2026-03-25-dbtool-cli-v1-rust-architecture-plan.md
Paperclip CTO 7424491944
Some checks failed
release-smoke / macos-13 / x86_64-apple-darwin (push) Has been cancelled
Details
release-smoke / ubuntu-latest / x86_64-unknown-linux-gnu (push) Has been cancelled
Details
release-smoke / windows-latest / x86_64-pc-windows-msvc (push) Has been cancelled
Details
chore: bootstrap independent git workflow 
Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-03-26 03:49:29 +00:00

6.6 KiB
Raw Permalink Blame History

dbtool-cli-v1 Rust 架构方案与执行计划

日期：2026-03-25
作者：CTO

1. 当前真实落地情况

  • Paperclip 中已经建立项目 dbtool-cli-v1，并已创建第一批工程 issue。
  • 配置中的项目根目录是 /workspace/repo/dbtool-cli-v1，但截至今天该目录原本并不存在，说明代码仓库尚未真正初始化。
  • 当前没有可验证的 Rust workspace、可执行 CLI、demo 数据、测试链路、发布链路或跨平台产物。
  • 因此本阶段的真实状态不是“已有实现等待扩展”，而是“需求和任务已经拆出，但代码基线仍未落地”。

2. V1 工程目标

V1 只交付 CLI，不交付 GUI。CLI 必须覆盖：

  • 连接 PostgreSQL、MySQL、SQLite
  • 浏览 schema / table / column
  • 执行临时查询
  • 执行脚本
  • 导出 CSV / JSON

当前阶段明确 gated：

  • 完整桌面 GUI
  • 插件系统
  • 多进程或服务化架构
  • 复杂 ORM / migration 编排

3. 推荐 Rust workspace 结构

dbtool-cli-v1/
  Cargo.toml
  Cargo.lock
  README.md
  plans/
  backlog/
  apps/
    dbtool-cli/
      Cargo.toml
      src/
  crates/
    db-core/
      Cargo.toml
      src/
    db-drivers/
      Cargo.toml
      src/
    db-config/
      Cargo.toml
      src/
  examples/
    fixtures/
    scripts/
  .github/
    workflows/

crate 边界

apps/dbtool-cli

  • 命令行入口
  • 参数解析
  • 表格/文本输出
  • 调用 db-core 用例
  • 初期先承载导出命令编排，避免过早拆出额外 crate

crates/db-core

  • 领域模型：连接配置、schema 树、查询请求/响应、导出请求
  • 通用错误模型
  • 驱动能力 trait
  • 应用层用例：connect、inspect、query、run-script、export

crates/db-drivers

  • PostgreSQL / MySQL / SQLite 的具体实现
  • 对 db-core trait 的适配
  • feature flag 控制三类数据库依赖
  • 统一管理连接池、SQL 方言差异和 introspection SQL

crates/db-config

  • 连接 profile
  • DSN 解析
  • 本地配置文件读写
  • 环境变量覆盖逻辑

4. 驱动抽象策略

V1 不做插件化驱动系统，也不做单独驱动进程。采用“核心 trait + 三个内建实现”的最小可行方案。

建议抽象

  • DatabaseKind
  • ConnectionProfile
  • DatabaseDriver
  • CatalogIntrospector
  • QueryExecutor

设计原则

  • db-core 只定义能力和标准化返回结构，不依赖具体数据库类型。
  • db-drivers 内部按 postgres、mysql、sqlite 模块实现，但对上层暴露统一入口。
  • 不使用过度抽象的通用连接层来抹平所有数据库差异；差异应在驱动层显式处理并记录。
  • 不把 CLI 输出格式、表格渲染、交互提示放进核心 crate。

技术选型

  • 异步运行时：tokio
  • CLI 参数：clap
  • 数据库访问：优先采用 sqlx，因为它原生覆盖 PostgreSQL、MySQL、SQLite，能减少多套驱动栈带来的维护成本
  • TLS：默认 rustls

备注：sqlx 当前官方仓库明确覆盖 PostgreSQL、MySQL、SQLite；打包链路可在仓库稳定后再接入 cargo-dist，当前不建议先引入额外发布复杂度。

5. 依赖关系与推进顺序

Phase 0：建基线

  1. 初始化 Rust workspace
  2. 跑通 CLI 二进制和 --help
  3. 建立基础 README、开发说明、样例目录

Phase 1：建公共能力

  1. 定义 db-core trait 与标准返回结构
  2. 完成 db-config
  3. 建立驱动 contract test 基座

Phase 2：按数据库逐个接入

  1. PostgreSQL
  2. MySQL
  3. SQLite

顺序理由：先做服务型主路径，再覆盖文件型数据库差异。

Phase 3：补全导出与稳定性

  1. CSV / JSON 导出
  2. demo fixtures
  3. smoke runbook
  4. 跨平台打包

6. 测试策略

单元测试

  • db-config：profile 解析、环境变量覆盖、路径处理
  • db-core：查询参数、错误转换、导出请求校验

contract test

  • 对三种数据库复用同一组行为测试：
    • 连接成功
    • 连接失败
    • schema 列举
    • table 描述
    • 简单查询
    • 参数化查询
    • 导出

集成测试

  • PostgreSQL / MySQL：使用容器启动测试实例
  • SQLite：使用临时文件数据库

CLI smoke test

  • dbtool connect
  • dbtool inspect
  • dbtool query
  • dbtool export

CLI 输出建议用 snapshot 测试保护，但只用于稳定文本输出，不替代行为测试。

7. 打包与发布策略

当前不需要“部署”，需要的是“发布可执行 CLI”。

第一阶段

  • 先用 CI matrix 生成 macOS、Linux、Windows release binary
  • 每个平台至少执行一次 --help smoke test
  • 产出压缩包和 checksum

第二阶段

  • 当命令面稳定后，再接入 cargo-dist 统一发布描述和产物整理

这个顺序比一开始就引入复杂发布工具更稳妥。

8. 前后端与 QA 第一轮职责

后端

  • 初始化 workspace
  • 定义核心抽象
  • 按 PostgreSQL → MySQL → SQLite 顺序交付驱动
  • 落地导出能力
  • 建立打包流水线

前端

  • 不做 GUI 实现
  • 产出未来桌面端信息架构
  • 明确连接管理、schema browser、query editor、results table 的交互边界
  • 提前识别未来 GUI 对 CLI / core 层的契约要求

QA

  • 建立跨数据库验收矩阵
  • 落地 demo fixtures 与 smoke runbook
  • 对 connect / inspect / query / export 建可重复回归路径

9. 与现有 issue 的对应关系

已有 issue

  • CMP-4：初始化 Rust workspace
  • CMP-5：PostgreSQL
  • CMP-6：MySQL
  • CMP-7：SQLite
  • CMP-8：CSV / JSON 导出
  • CMP-9：未来 GUI 信息架构
  • CMP-10：跨数据库验收矩阵
  • CMP-11：里程碑、依赖图和交付跟踪

已补充的 issue

  • CMP-12：CLI 打包、发布与跨平台 smoke 流水线
  • CMP-13：demo 数据库、样例脚本与 smoke runbook

10. 当前关键风险

P0

  • 项目路径之前不存在，说明仓库尚未初始化，CMP-4 是所有实现工作的真实前置

P1

  • 产品范围文档 CMP-2 尚未完成前，部分命令细节和验收文字仍需与 PM 对齐
  • 当前只有一名后端工程师，驱动接入和发布链路都压在同一人身上，关键路径较长

P2

  • 没有 demo fixtures 时，QA 和后续 smoke automation 难以尽早稳定

11. 招聘建议

当前先不建议立即扩编。

原因：

  • 现阶段瓶颈是仓库初始化、架构收敛和第一条实现链路，不是人手数量
  • 在 PostgreSQL 主链路和 CI/发布链路跑通前，新增工程师的边际收益有限

触发招聘的条件：

  • CMP-4 到 CMP-5 跑通后，后端仍被 MySQL / SQLite / release pipeline 长时间阻塞
  • 或 GUI 方向从“设计基线”升级为并行实现项目