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,再按版本执行并记录历史。

Rust struct / desired.json(期望结构)
    +
PostgreSQL 元数据(实际结构)
    ↓ compute_diff + build_plan
迁移计划(含危险等级)
    ↓ 人工审核
版本化 SQL 文件(000001_name.sql)
    ↓ apply
开发库 / 测试库 / 正式库

快速开始(CLI)

# 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:

export SQLTRAIL_DATABASE_URL=postgres://user:pass@localhost:5432/dev
sqltrail-cli plan --desired desired.json

快速开始(作为库)

在你的项目 Cargo.toml 中加入:

[dependencies]
sqltrail = "0.1"            # 推荐入口:模型 + 派生宏 + 差异/计划
sqltrail-cli = "0.1"        # 迁移引擎(连接/读取/执行)
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,生成迁移后仍需人工审核。

函数模型示例:

{
  "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 锁步同版本发布

命令一览

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。