# sqltrail-cli
通用的 PostgreSQL 结构迁移工具:**库 + 命令行**,可接入任意 Rust 项目。
核心思想:用 Rust struct(或 JSON 模型文件)描述「期望结构」,与数据库「实际结构」比较,
生成**可人工审核的版本化迁移 SQL**,再按版本执行并记录历史。
```text
Rust struct / desired.json(期望结构)
+
PostgreSQL 元数据(实际结构)
↓ compute_diff + build_plan
迁移计划(含危险等级)
↓ 人工审核
版本化 SQL 文件(000001_name.sql)
↓ apply
开发库 / 测试库 / 正式库
```
## 快速开始(CLI)
```bash
# 1. 安装
cargo install sqltrail-cli
# 2. 准备期望结构:从参考库导出(或用自己的 struct 生成,见下)
sqltrail-cli inspect --database-url postgres://user:pass@localhost:5432/ref > desired.json
# 3. 查看差异(不修改任何东西)
sqltrail-cli plan --database-url postgres://user:pass@localhost:5432/dev --desired desired.json
# 4. 生成版本化迁移文件,人工审核
sqltrail-cli generate add_user_avatar --database-url ... --desired desired.json
# 5. 执行迁移
sqltrail-cli apply --database-url ...
```
也可以用环境变量代替 `--database-url`:
```bash
export SQLTRAIL_DATABASE_URL=postgres://user:pass@localhost:5432/dev
sqltrail-cli plan --desired desired.json
```
## 快速开始(作为库)
在你的项目 `Cargo.toml` 中加入:
```toml
[dependencies]
sqltrail = "0.1" # 推荐入口:模型 + 派生宏 + 差异/计划
sqltrail-cli = "0.1" # 迁移引擎(连接/读取/执行)
```
```rust,ignore
use sqltrail::{DBSchema, DbSchema};
use sqltrail_cli::plan_from_database;
#[derive(DbSchema)]
#[db_table(schema = "public", name = "users", comment = "用户表")]
struct User {
#[db_column(primary_key)]
id: i64,
#[db_column(sql_type = "varchar(64)", unique, comment = "显示名称")]
name: String,
}
#[tokio::main]
async fn main() -> anyhow::Result<()> {
let client = sqltrail_cli::database::connect("postgres://user:pass@localhost:5432/dev").await?;
let plan = plan_from_database(&client, &User::schema()).await?;
println!("{}", sqltrail_cli::generator::render_plan(&plan));
Ok(())
}
```
## 注释、索引与函数
- 表和字段注释可通过宏的 `comment = "..."` 声明,也可直接写入 `SchemaModel` JSON;
- 索引使用 `db_table(index = (...))`,支持联合索引、唯一索引和部分索引;
- 数据库函数使用固定 JSON 模型管理。函数定义属于可执行 SQL,生成迁移后仍需人工审核。
函数模型示例:
```json
{
"manage_comments": true,
"manage_functions": true,
"schemas": [],
"tables": [],
"functions": [
{
"schema": "public",
"name": "answer",
"identity_arguments": "",
"definition_sql": "CREATE OR REPLACE FUNCTION public.answer() RETURNS integer LANGUAGE sql IMMUTABLE AS $$ SELECT 42 $$",
"comment": "返回标准答案"
}
]
}
```
`manage_comments` / `manage_functions` 默认均为 `false`,这是为了兼容旧 JSON,避免升级后意外删除数据库中已有的注释或函数。`inspect` 导出的模型会显式开启两项管理。
## 统一规范(接入约定)
| 结构来源 | 期望结构 = Rust struct(派生宏)或 SchemaModel JSON,二选一,均为统一模型 |
| 标识符 | 小写字母/数字/下划线,不以数字开头;`validate` 统一校验 |
| 重命名 | 表/字段重命名必须显式声明 `rename_from`,绝不按相似度猜测 |
| 危险操作 | 删表/删字段/收紧类型/改主键等默认只生成计划,执行需 `--allow-destructive` |
| 迁移文件 | `000001_name.sql`,固定 6 位递增编号;生成后人工审核,禁止修改已执行文件 |
| 防篡改 | 每个迁移文件记录 SHA-256 checksum,`apply` 时校验,不一致立即报错 |
| 事务 | 每个迁移默认单独事务;不支持事务的语句在文件内声明 `-- @no-transaction` |
| 版本策略 | `sqltrail-core` / `sqltrail-macros` / `sqltrail` / `sqltrail-cli` 锁步同版本发布 |
## 命令一览
```text
sqltrail-cli status # 连接状态、当前版本、待执行迁移
sqltrail-cli inspect # 读取实际结构并输出 JSON
sqltrail-cli plan --desired schema.json # 差异 + 拟生成 SQL(只读)
sqltrail-cli generate <name> --desired ... # 生成版本化迁移文件
sqltrail-cli apply [--allow-destructive] # 按版本执行迁移
```
## 文档
- API 文档:`cargo doc -p sqltrail-cli --open`
- 设计说明见各 crate README。