sqltrail-cli 0.1.0

Reusable PostgreSQL schema migration CLI and library: diff declared schema against a live database, generate versioned SQL, apply with a checksum-protected history
Documentation
# 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。