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
//! 迁移文件与历史表管理(实施计划第 8 阶段)。
//!
//! - 迁移文件命名:`000001_name.sql`(固定 6 位递增编号);
//! - 历史表:`public._sqltrail_migrations`,记录版本、名称、checksum 与耗时;
//! - 执行规则:
//!   - 按版本号升序执行,已执行版本不重复执行;
//!   - 已执行文件的 checksum 变化立即报错(防止篡改历史迁移);
//!   - 每个迁移默认在单独事务中执行;
//!   - 文件内出现 `-- @danger` 标记且未传 `--allow-destructive` 时拒绝执行;
//!   - 文件内出现 `-- @no-transaction` 标记时跳过事务(用于不支持事务的语句)。

use std::collections::BTreeMap;
use std::path::{Path, PathBuf};
use std::time::Instant;

use anyhow::{anyhow, bail};
use sha2::{Digest, Sha256};
use tokio_postgres::Client;

/// 迁移历史表(固定表名,introspection 会排除它)。
pub const HISTORY_TABLE: &str = "public._sqltrail_migrations";

/// 会话级 advisory lock,避免多个进程同时执行同一数据库的迁移。
const APPLY_LOCK_KEY: i64 = 0x4349_505F_4D49_4752;

/// 计算迁移文件内容的 SHA-256 checksum(十六进制)。
pub fn compute_checksum(content: &str) -> String {
    let mut hasher = Sha256::new();
    hasher.update(content.as_bytes());
    hex::encode(hasher.finalize())
}

/// 确保迁移历史表存在。
pub async fn ensure_history_table(client: &Client) -> anyhow::Result<()> {
    let sql = format!(
        "CREATE TABLE IF NOT EXISTS {HISTORY_TABLE} ( \
            version BIGINT PRIMARY KEY, \
            name TEXT NOT NULL, \
            checksum TEXT NOT NULL, \
            applied_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), \
            execution_ms BIGINT NOT NULL \
        )"
    );
    client
        .batch_execute(&sql)
        .await
        .map_err(|e| anyhow!("创建迁移历史表失败: {e}"))?;
    Ok(())
}

/// 已执行版本 → checksum 的映射。
pub async fn applied_versions(client: &Client) -> anyhow::Result<BTreeMap<i64, String>> {
    let rows = client
        .query(
            &format!("SELECT version, checksum FROM {HISTORY_TABLE}"),
            &[],
        )
        .await
        .map_err(|e| anyhow!("读取迁移历史失败: {e}"))?;
    Ok(rows.iter().map(|r| (r.get(0), r.get(1))).collect())
}

/// 一个迁移文件。
#[derive(Debug)]
pub struct MigrationFile {
    /// 版本号(文件名前 6 位)
    pub version: i64,
    /// 迁移名称(文件名中间段)
    pub name: String,
    /// 文件路径
    pub path: PathBuf,
    /// 内容 SHA-256
    pub checksum: String,
    /// 完整 SQL 内容
    pub sql: String,
}

/// 读取迁移目录下的全部 `000001_name.sql` 文件,按版本号升序排列。
///
/// 目录不存在时返回空列表;不匹配命名规则的文件会被跳过。
pub fn read_migrations(dir: &Path) -> anyhow::Result<Vec<MigrationFile>> {
    let mut files = Vec::new();
    if !dir.exists() {
        return Ok(files);
    }
    for entry in std::fs::read_dir(dir)? {
        let entry = entry?;
        let path = entry.path();
        if !path.is_file() || path.extension().map(|e| e != "sql").unwrap_or(true) {
            continue;
        }
        let file_name = path
            .file_name()
            .and_then(|n| n.to_str())
            .ok_or_else(|| anyhow!("非法文件名: {}", path.display()))?;
        // 解析 000001_name.sql
        let Some((num_part, rest)) = file_name.split_once('_') else {
            continue;
        };
        let Ok(version) = num_part.parse::<i64>() else {
            continue;
        };
        let name = rest.trim_end_matches(".sql").to_string();
        let sql = std::fs::read_to_string(&path)?;
        files.push(MigrationFile {
            version,
            name,
            path,
            checksum: compute_checksum(&sql),
            sql,
        });
    }
    files.sort_by_key(|f| f.version);
    for w in files.windows(2) {
        if w[0].version == w[1].version {
            bail!(
                "存在重复版本号:{} 与 {}",
                w[0].path.display(),
                w[1].path.display()
            );
        }
    }
    Ok(files)
}

/// 单个已执行迁移的记录。
#[derive(Debug)]
pub struct AppliedMigration {
    pub version: i64,
    pub name: String,
    pub execution_ms: u128,
}

/// apply 执行结果。
#[derive(Debug, Default)]
pub struct ApplyReport {
    pub applied: Vec<AppliedMigration>,
}

/// 按版本顺序执行尚未执行的迁移,并写入迁移历史表。
///
/// # 参数
/// - `allow_destructive`:是否允许执行包含 `-- @danger` 标记的迁移。
pub async fn apply(
    client: &mut Client,
    files: &[MigrationFile],
    allow_destructive: bool,
) -> anyhow::Result<ApplyReport> {
    client
        .query_one("SELECT pg_advisory_lock($1)", &[&APPLY_LOCK_KEY])
        .await
        .map_err(|e| anyhow!("获取迁移执行锁失败: {e}"))?;

    let result = apply_locked(client, files, allow_destructive).await;
    let unlock_result = client
        .query_one("SELECT pg_advisory_unlock($1)", &[&APPLY_LOCK_KEY])
        .await
        .map_err(|e| anyhow!("释放迁移执行锁失败: {e}"));

    match (result, unlock_result) {
        (Err(e), _) => Err(e),
        (Ok(_), Err(e)) => Err(e),
        (Ok(report), Ok(_)) => Ok(report),
    }
}

/// 迁移历史表是否已经存在;只读,不会修改数据库。
pub async fn history_table_exists(client: &Client) -> anyhow::Result<bool> {
    let row = client
        .query_one("SELECT to_regclass($1)::text", &[&HISTORY_TABLE])
        .await
        .map_err(|e| anyhow!("检查迁移历史表失败: {e}"))?;
    let table: Option<String> = row.get(0);
    Ok(table.is_some())
}

/// 在持有 advisory lock 的前提下执行迁移。
async fn apply_locked(
    client: &mut Client,
    files: &[MigrationFile],
    allow_destructive: bool,
) -> anyhow::Result<ApplyReport> {
    // 必须在拿到锁之后读取,避免并发进程使用过期的历史快照。
    let applied = applied_versions(client).await?;
    let mut report = ApplyReport::default();

    for file in files {
        // 已执行:校验 checksum 未被篡改
        if let Some(recorded) = applied.get(&file.version) {
            if recorded != &file.checksum {
                bail!(
                    "迁移 {:06} {} 的 checksum 与历史记录不一致,文件可能已被修改!\n  历史记录: {}\n  当前文件: {}",
                    file.version,
                    file.name,
                    recorded,
                    file.checksum
                );
            }
            continue;
        }

        // 危险操作保护
        if !allow_destructive && contains_marker(&file.sql, "-- @danger") {
            bail!(
                "迁移 {:06} {} 包含危险操作(删除表/字段、收紧类型、修改主键等)。\n请人工审核后使用 `sqltrail-cli apply --allow-destructive` 显式确认。",
                file.version,
                file.name
            );
        }

        // 不支持事务的迁移需在文件中显式声明
        let no_transaction = contains_marker(&file.sql, "-- @no-transaction");
        let start = Instant::now();

        if no_transaction {
            client
                .batch_execute(&file.sql)
                .await
                .map_err(|e| anyhow!("执行迁移 {} 失败: {e}", file.path.display()))?;

            let execution_ms = start.elapsed().as_millis();
            // no-transaction 文件无法保证 DDL 与历史记录原子提交;advisory lock
            // 至少保证不会由两个 sqltrail-cli 进程并发执行。
            client
                .execute(
                    &format!(
                        "INSERT INTO {HISTORY_TABLE} (version, name, checksum, execution_ms) \
                         VALUES ($1, $2, $3, $4)"
                    ),
                    &[
                        &file.version,
                        &file.name,
                        &file.checksum,
                        &(execution_ms as i64),
                    ],
                )
                .await
                .map_err(|e| anyhow!("记录迁移历史失败(版本 {}): {e}", file.version))?;

            report.applied.push(AppliedMigration {
                version: file.version,
                name: file.name.clone(),
                execution_ms,
            });
        } else {
            let tx = client
                .transaction()
                .await
                .map_err(|e| anyhow!("开启事务失败({}): {e}", file.path.display()))?;
            tx.batch_execute(&file.sql)
                .await
                .map_err(|e| anyhow!("执行迁移 {} 失败(事务已回滚): {e}", file.path.display()))?;

            let execution_ms = start.elapsed().as_millis();
            tx.execute(
                &format!(
                    "INSERT INTO {HISTORY_TABLE} (version, name, checksum, execution_ms) \
                     VALUES ($1, $2, $3, $4)"
                ),
                &[
                    &file.version,
                    &file.name,
                    &file.checksum,
                    &(execution_ms as i64),
                ],
            )
            .await
            .map_err(|e| anyhow!("记录迁移历史失败(版本 {},事务已回滚): {e}", file.version))?;
            tx.commit()
                .await
                .map_err(|e| anyhow!("提交事务失败({}): {e}", file.path.display()))?;

            report.applied.push(AppliedMigration {
                version: file.version,
                name: file.name.clone(),
                execution_ms,
            });
        }
    }

    Ok(report)
}

/// 判断 SQL 中是否包含指定标记注释。
fn contains_marker(sql: &str, marker: &str) -> bool {
    sql.lines()
        .any(|line| line.trim_start().starts_with(marker))
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn checksum稳定且可复现() {
        let c1 = compute_checksum("CREATE TABLE t ();\n");
        let c2 = compute_checksum("CREATE TABLE t ();\n");
        let c3 = compute_checksum("CREATE TABLE t ();");
        assert_eq!(c1, c2);
        assert_eq!(c1.len(), 64);
        assert_ne!(c1, c3, "内容变化必须导致 checksum 变化");
    }

    #[test]
    fn 危险标记识别() {
        let sql = "-- @danger 危险操作\nDROP TABLE t;";
        assert!(contains_marker(sql, "-- @danger"));
        let safe = "DROP TABLE t;";
        assert!(!contains_marker(safe, "-- @danger"));
    }
}