sqltrail-cli
通用的 PostgreSQL 结构迁移工具:库 + 命令行,可接入任意 Rust 项目。
核心思想:用 Rust struct(或 JSON 模型文件)描述「期望结构」,与数据库「实际结构」比较, 生成可人工审核的版本化迁移 SQL,再按版本执行并记录历史。
Rust struct / desired.json(期望结构)
+
PostgreSQL 元数据(实际结构)
↓ compute_diff + build_plan
迁移计划(含危险等级)
↓ 人工审核
版本化 SQL 文件(000001_name.sql)
↓ apply
开发库 / 测试库 / 正式库
快速开始(CLI)
# 1. 安装
# 2. 准备期望结构:从参考库导出(或用自己的 struct 生成,见下)
# 3. 查看差异(不修改任何东西)
# 4. 生成版本化迁移文件,人工审核
# 5. 执行迁移
也可以用环境变量代替 --database-url:
快速开始(作为库)
在你的项目 Cargo.toml 中加入:
[]
= "0.1" # 推荐入口:模型 + 派生宏 + 差异/计划
= "0.1" # 迁移引擎(连接/读取/执行)
use ;
use plan_from_database;
async
注释、索引与函数
- 表和字段注释可通过宏的
comment = "..."声明,也可直接写入SchemaModelJSON; - 索引使用
db_table(index = (...)),支持联合索引、唯一索引和部分索引; - 数据库函数使用固定 JSON 模型管理。函数定义属于可执行 SQL,生成迁移后仍需人工审核。
函数模型示例:
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。