113 lines
5.0 KiB
Markdown
113 lines
5.0 KiB
Markdown
# dbtool-cli-v1
|
||
|
||
`dbtool-cli-v1` 是一个面向 PostgreSQL、MySQL 和 SQLite 的跨数据库 CLI 工具。
|
||
|
||
当前仓库已经具备 Rust workspace 基线，并已落地 PostgreSQL、MySQL 与 SQLite 的首个 happy path：
|
||
|
||
- 根 `Cargo` workspace
|
||
- `apps/cli` 可执行入口
|
||
- `crates/db-core` 领域模型与输入校验
|
||
- `crates/db-config` 连接 profile 与脱敏摘要
|
||
- `crates/db-drivers` 驱动边界与 PostgreSQL / MySQL / SQLite 实现
|
||
|
||
## 当前状态
|
||
|
||
当前已实现：
|
||
|
||
- PostgreSQL `connect`
|
||
- PostgreSQL `inspect`
|
||
- PostgreSQL `query`
|
||
- MySQL `connect`
|
||
- MySQL `inspect`
|
||
- MySQL `query`
|
||
- SQLite `connect`
|
||
- SQLite `inspect`
|
||
- SQLite `query`
|
||
- `export` 到 CSV
|
||
- `export` 到 JSON
|
||
- `.sql` 文件读取
|
||
- `--password-env` 密码注入且保持输出脱敏
|
||
|
||
已验证：
|
||
|
||
- 标准环境：`cargo build`
|
||
- 标准环境：`cargo test`
|
||
- 标准环境：`cargo run -p dbtool-cli -- --help`
|
||
- 链接器受限的 Linux 环境：使用 `zig cc` 作为 host linker 执行 `cargo check` / `cargo test`
|
||
|
||
当前 `connect` / `inspect` / `query` / `export` 在 PostgreSQL、MySQL 与 SQLite 的共享抽象上都已经可用；当前剩余工作主要是 Docker 环境下的跨数据库 smoke 与发布链路。
|
||
|
||
## Workspace 结构
|
||
|
||
```text
|
||
dbtool-cli-v1/
|
||
Cargo.toml
|
||
README.md
|
||
DEVELOPING.md
|
||
apps/
|
||
cli/
|
||
Cargo.toml
|
||
src/main.rs
|
||
crates/
|
||
db-core/
|
||
db-config/
|
||
db-drivers/
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
```bash
|
||
cargo run -p dbtool-cli -- --help
|
||
export DBTOOL_PASSWORD=dbtool
|
||
cargo run -p dbtool-cli -- connect --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 qa_demo
|
||
cargo run -p dbtool-cli -- query --driver postgres --host 127.0.0.1 --port 55432 --database dbtool_demo --username dbtool --password-env DBTOOL_PASSWORD --file examples/sql/postgres/happy_path_query.sql
|
||
cargo run -p dbtool-cli -- connect --driver mysql --host 127.0.0.1 --port 53306 --database qa_demo --username dbtool --password-env DBTOOL_PASSWORD
|
||
cargo run -p dbtool-cli -- inspect --driver mysql --host 127.0.0.1 --port 53306 --database qa_demo --username dbtool --password-env DBTOOL_PASSWORD --schema qa_demo
|
||
cargo run -p dbtool-cli -- query --driver mysql --host 127.0.0.1 --port 53306 --database qa_demo --username dbtool --password-env DBTOOL_PASSWORD --file examples/sql/mysql/happy_path_query.sql
|
||
cargo run -p dbtool-cli -- connect --driver sqlite --path examples/tmp/dbtool-demo.sqlite
|
||
cargo run -p dbtool-cli -- inspect --driver sqlite --path examples/tmp/dbtool-demo.sqlite --schema main
|
||
cargo run -p dbtool-cli -- query --driver sqlite --path examples/tmp/dbtool-demo.sqlite --file examples/sql/sqlite/happy_path_query.sql
|
||
cargo run -p dbtool-cli -- export --driver sqlite --path examples/tmp/dbtool-demo.sqlite --file examples/sql/sqlite/export_query.sql --format csv --output examples/tmp/export.csv
|
||
```
|
||
|
||
如果当前 Linux 环境没有系统 `cc`，可以改用一个 C 兼容 linker，例如 `zig cc`：
|
||
|
||
```bash
|
||
cat > /tmp/zig-cc <<'EOF'
|
||
#!/bin/sh
|
||
exec zig cc "$@"
|
||
EOF
|
||
chmod +x /tmp/zig-cc
|
||
export CC=/tmp/zig-cc
|
||
export CARGO_TARGET_X86_64_UNKNOWN_LINUX_GNU_LINKER=/tmp/zig-cc
|
||
cargo test
|
||
cargo run -p dbtool-cli -- --help
|
||
```
|
||
|
||
最小发布与产物 smoke 已定义在 `.github/workflows/release-smoke.yml` 与 `RELEASE_RUNBOOK.md`；当前 Linux 还可本地执行 `scripts/release/smoke-binary.sh` 和 `scripts/release/package-unix.sh` 复核产物命名与 checksum。
|
||
|
||
Git 仓库初始化、agent 提交规范与远程接入方式见 `GIT_WORKFLOW.md`。
|
||
|
||
## PostgreSQL / MySQL / SQLite 行为说明
|
||
|
||
- 非参数化 `query` 会走 PostgreSQL simple query 协议，因此支持包含多条语句的 `.sql` 文件，例如 `SET search_path ...; SELECT ...`
|
||
- 非参数化 `query` 在 MySQL 上走 text protocol，因此也支持包含多条语句的 `.sql` 文件，例如 `USE qa_demo; SELECT ...`
|
||
- 带 `--param` 的 `query` 会切换到 prepared execution，当前要求 SQL 为单条参数化语句
|
||
- 凭据只通过 `--password-env` 注入，错误和成功输出都不会回显密码
|
||
- MySQL `inspect` 里的 `schema` 参数当前映射到数据库名；顶层 `inspect` 返回的是数据库列表
|
||
- SQLite 顶层 `inspect` 返回附加数据库列表，demo happy path 使用 `main`；`--schema main` 会列出表，`--schema main --table <table>` 会列出列
|
||
- SQLite 当前使用单条 statement 执行模型；若传入多语句 SQL，会明确返回 `Multiple statements provided`
|
||
- `export` 只接受返回结果集的查询；若 SQL 只有 rows affected 而没有结果集，会明确报错
|
||
- `export` 不会静默覆盖已有文件，且会在父目录不存在时给出显式下一步提示
|
||
|
||
## 设计原则
|
||
|
||
- CLI、未来 GUI 与自动化场景共享同一套核心语义
|
||
- 先稳定领域边界、错误模型和可测试输入校验
|
||
- 驱动差异留在 `db-drivers`，不污染公共 crate
|
||
|
||
## 下一步
|
||
|
||
- `CMP-12`：在此 workspace 基线之上接入跨平台打包与 smoke
|