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
//! 命令行定义:使用 clap 派生定义所有子命令与参数。

use std::path::PathBuf;

use clap::{Parser, Subcommand};

/// 通用 PostgreSQL 结构迁移工具。
///
/// 只管理本地 PostgreSQL;外部数据源(Oracle/MSSQL/MySQL/SQLite)
/// 只用于获取或写入外部业务数据,不参与结构比较和迁移。
#[derive(Debug, Parser)]
#[command(name = "sqltrail-cli", version, about, long_about = None)]
pub struct Cli {
    /// PostgreSQL 连接串,也可通过环境变量 SQLTRAIL_DATABASE_URL 提供
    #[arg(long, global = true, env = "SQLTRAIL_DATABASE_URL", value_name = "URL")]
    pub database_url: Option<String>,

    /// 迁移文件目录(默认取当前目录下的 migrations)
    #[arg(long, global = true, default_value = "migrations", value_name = "DIR")]
    pub migrations_dir: PathBuf,

    /// 期望结构 JSON 文件(SchemaModel 格式)。
    /// 可由 `sqltrail-cli inspect > desired.json` 从参考库导出,
    /// 也可用 sqltrail / sqltrail-core 自行生成。
    /// 缺省视为空库(全新建库场景)。
    #[arg(long, global = true, value_name = "schema.json")]
    pub desired: Option<PathBuf>,

    #[command(subcommand)]
    pub command: Option<Command>,
}

/// 全部子命令。
#[derive(Debug, Subcommand)]
pub enum Command {
    /// 查看数据库连接状态、当前迁移版本与待执行迁移
    Status,

    /// 读取数据库实际结构并以 JSON 输出(用于排查元数据解析问题)
    Inspect,

    /// 比较期望结构与实际结构,输出差异与拟生成 SQL(不修改数据库、不写文件)
    Plan {
        /// 以 JSON 输出迁移计划
        #[arg(long)]
        json: bool,
    },

    /// 根据差异生成新的版本化迁移 SQL 文件(生成后必须人工审核,不会自动执行)
    Generate {
        /// 迁移名称,例如 add_user_avatar
        #[arg(value_name = "NAME")]
        name: String,
    },

    /// 按版本顺序执行尚未执行的迁移文件,并写入迁移历史表
    Apply {
        /// 允许执行标记为危险的迁移(删除表/字段、收紧类型、改主键等)
        #[arg(long)]
        allow_destructive: bool,
    },
}