Skip to main content

yang_base/database/
initializer.rs

1//! 数据库初始化器
2//!
3//! 负责执行插件的数据库初始化脚本和迁移。
4//!
5//! # 设计说明
6//!
7//! DatabaseInitializer 使用 yang-db::Database 的方法执行 SQL,支持事务和非事务两种初始化模式。
8//! 所有数据库操作都通过 yang-db 库实现,确保类型安全和统一的数据库访问接口。
9//!
10//! # 示例
11//!
12//! ```rust,ignore
13//! use yang_base::database::DatabaseInitializer;
14//! use yang_base::plugin::PluginManager;
15//! use yang_db::Database;
16//!
17//! // 创建数据库连接
18//! let db = Database::connect("mysql://user:pass@localhost/db").await?;
19//!
20//! // 创建插件管理器并注册插件
21//! let manager = PluginManager::new();
22//! manager.register(MyPlugin).await?;
23//!
24//! // 创建数据库初始化器(启用事务模式)
25//! let initializer = DatabaseInitializer::new(db, true);
26//!
27//! // 初始化所有插件的数据库
28//! initializer.initialize_all(&manager).await?;
29//! ```
30
31use crate::error::BaseError;
32use crate::plugin::{Plugin, PluginLifecycleStage, PluginManager};
33use crate::table::{SchemaColumn, SchemaValidationReport, TableDefinition};
34use std::sync::Arc;
35use yang_db::Database;
36
37/// 迁移 dry-run 中单项的状态。
38#[derive(Debug, Clone, Copy, PartialEq, Eq)]
39#[non_exhaustive]
40pub enum MigrationPlanStatus {
41    /// 尚未执行。
42    Pending,
43    /// 已执行且校验和一致。
44    Applied,
45    /// 相同 module/version 的内容已变化或历史记录不可验证。
46    ChecksumMismatch,
47    /// 另一个初始化器已预留并正在执行。
48    InProgress,
49}
50
51/// 一条可审计的迁移计划记录。
52#[derive(Debug, Clone, PartialEq, Eq)]
53pub struct MigrationPlanEntry {
54    /// 插件/模块名称。
55    pub module: String,
56    /// 迁移版本。
57    pub version: String,
58    /// 当前 SQL 内容的稳定校验和。
59    pub checksum: String,
60    /// 与数据库记录比较后的状态。
61    pub status: MigrationPlanStatus,
62}
63
64/// dry-run 迁移计划;生成过程只读数据库,不创建表或写记录。
65#[derive(Debug, Clone, Default, PartialEq, Eq)]
66pub struct MigrationPlan {
67    /// 按插件依赖顺序及插件声明顺序排列的迁移项。
68    pub entries: Vec<MigrationPlanEntry>,
69}
70
71#[derive(sqlx::FromRow)]
72struct MigrationRecord {
73    checksum: Option<String>,
74    status: String,
75}
76
77fn classify_migration_record(
78    record: Option<(Option<&str>, &str)>,
79    expected_checksum: &str,
80) -> MigrationPlanStatus {
81    match record {
82        None => MigrationPlanStatus::Pending,
83        Some((_, status)) if status != "applied" => MigrationPlanStatus::InProgress,
84        Some((Some(actual), "applied")) if actual == expected_checksum => {
85            MigrationPlanStatus::Applied
86        }
87        Some(_) => MigrationPlanStatus::ChecksumMismatch,
88    }
89}
90
91/// 计算迁移 SQL 的稳定 FNV-1a 64 位校验和。
92fn migration_checksum(sql: &str) -> String {
93    let mut hash = 0xcbf2_9ce4_8422_2325_u64;
94    for byte in sql.as_bytes() {
95        hash ^= u64::from(*byte);
96        hash = hash.wrapping_mul(0x0000_0100_0000_01b3);
97    }
98    format!("{hash:016x}")
99}
100
101fn migration_execution_error(
102    module: &str,
103    version: &str,
104    sql: &str,
105    source: yang_db::DbError,
106) -> BaseError {
107    BaseError::MigrationExecutionFailed {
108        module: module.to_string(),
109        version: version.to_string(),
110        checksum: migration_checksum(sql),
111        source,
112    }
113}
114
115/// 数据库初始化器
116///
117/// 负责执行插件的数据库初始化脚本和迁移。
118/// 所有数据库操作都通过 yang-db::Database 提供的方法实现。
119///
120/// # 字段
121///
122/// - `db`: 调用方显式传入并交由初始化器持有的数据库实例
123/// - `use_transaction`: 是否启用事务模式
124///
125/// # 示例
126///
127/// ```rust,ignore
128/// use yang_base::database::DatabaseInitializer;
129/// use yang_db::Database;
130///
131/// let db = Database::connect("mysql://root:password@localhost/test").await?;
132/// let initializer = DatabaseInitializer::new(db, true);
133/// ```
134pub struct DatabaseInitializer {
135    /// 显式拥有的数据库实例。
136    db: Database,
137
138    /// 是否启用事务模式
139    use_transaction: bool,
140}
141
142impl DatabaseInitializer {
143    /// 创建新的数据库初始化器
144    ///
145    /// # 参数
146    ///
147    /// - `db`: yang-db::Database 实例
148    /// - `use_transaction`: 是否启用事务模式
149    ///
150    /// # 返回
151    ///
152    /// - DatabaseInitializer 实例
153    ///
154    /// # 示例
155    ///
156    /// ```rust,ignore
157    /// use yang_base::database::DatabaseInitializer;
158    /// use yang_db::Database;
159    ///
160    /// let db = Database::connect("mysql://root:password@localhost/test").await?;
161    ///
162    /// // 创建事务模式的初始化器
163    /// let initializer = DatabaseInitializer::new(db, true);
164    ///
165    /// // 创建非事务模式的初始化器
166    /// let db2 = Database::connect("mysql://root:password@localhost/test").await?;
167    /// let initializer = DatabaseInitializer::new(db2, false);
168    /// ```
169    pub fn new(db: Database, use_transaction: bool) -> Self {
170        Self {
171            db,
172            use_transaction,
173        }
174    }
175
176    /// 返回底层数据库实例的引用
177    ///
178    pub(crate) fn db(&self) -> &Database {
179        &self.db
180    }
181
182    /// 只读生成单个插件的迁移计划,不创建迁移表、不执行 SQL、不写迁移记录。
183    pub async fn plan_migrations(&self, plugin: &dyn Plugin) -> Result<MigrationPlan, BaseError> {
184        let table_exists = self
185            .db()
186            .table_exists(yang_db::table!("_migrations"))
187            .await
188            .map_err(BaseError::DatabaseQueryFailed)?;
189        let mut entries = Vec::new();
190        for (version, sql) in plugin.migration_sql() {
191            let checksum = migration_checksum(&sql);
192            let record = if table_exists {
193                self.load_migration_record(plugin.name(), &version).await?
194            } else {
195                None
196            };
197            let status = classify_migration_record(
198                record
199                    .as_ref()
200                    .map(|record| (record.checksum.as_deref(), record.status.as_str())),
201                &checksum,
202            );
203            entries.push(MigrationPlanEntry {
204                module: plugin.name().to_string(),
205                version,
206                checksum,
207                status,
208            });
209        }
210        Ok(MigrationPlan { entries })
211    }
212
213    /// 只读生成全部插件的迁移计划。
214    pub async fn plan_all(
215        &self,
216        plugin_manager: &PluginManager,
217    ) -> Result<MigrationPlan, BaseError> {
218        let mut plan = MigrationPlan::default();
219        for plugin in plugin_manager.get_all().await {
220            plan.entries
221                .extend(self.plan_migrations(plugin.as_ref()).await?.entries);
222        }
223        Ok(plan)
224    }
225
226    /// 从 MySQL information_schema 读取当前列并验证表定义的运行期字段契约。
227    ///
228    /// 本方法只读,不生成或执行 ALTER;数据库额外列不视为问题。
229    pub async fn validate_table_definition(
230        &self,
231        table: &TableDefinition,
232    ) -> Result<SchemaValidationReport, BaseError> {
233        #[derive(sqlx::FromRow)]
234        struct ColumnRow {
235            column_name: String,
236            data_type: String,
237            column_type: String,
238            is_nullable: String,
239            character_maximum_length: Option<i64>,
240            column_default: Option<String>,
241            extra: String,
242        }
243
244        let rows: Vec<ColumnRow> = self
245            .db()
246            .query_with_params(
247                "SELECT CAST(COLUMN_NAME AS CHAR) AS column_name, CAST(DATA_TYPE AS CHAR) AS data_type, CAST(COLUMN_TYPE AS CHAR) AS column_type, CAST(IS_NULLABLE AS CHAR) AS is_nullable, CAST(CHARACTER_MAXIMUM_LENGTH AS SIGNED) AS character_maximum_length, CAST(COLUMN_DEFAULT AS CHAR) AS column_default, CAST(EXTRA AS CHAR) AS extra FROM information_schema.columns WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = ? ORDER BY ORDINAL_POSITION",
248                vec![serde_json::Value::String(table.name().to_string())],
249            )
250            .await
251            .map_err(BaseError::DatabaseQueryFailed)?;
252        let columns: Vec<_> = rows
253            .into_iter()
254            .map(|row| {
255                SchemaColumn::new(
256                    row.column_name,
257                    row.data_type,
258                    row.column_type,
259                    row.is_nullable.eq_ignore_ascii_case("YES"),
260                    row.character_maximum_length
261                        .and_then(|length| u64::try_from(length).ok()),
262                    row.column_default,
263                )
264                .with_auto_increment(
265                    row.extra
266                        .split_whitespace()
267                        .any(|part| part.eq_ignore_ascii_case("auto_increment")),
268                )
269            })
270            .collect();
271        Ok(table.validate_schema(&columns))
272    }
273
274    async fn load_migration_record(
275        &self,
276        module: &str,
277        version: &str,
278    ) -> Result<Option<MigrationRecord>, BaseError> {
279        let sql = "SELECT checksum, status FROM _migrations WHERE module_name = ? AND version = ? LIMIT 1";
280        let records: Vec<MigrationRecord> = self
281            .db()
282            .query_with_params(
283                sql,
284                vec![
285                    serde_json::Value::String(module.to_string()),
286                    serde_json::Value::String(version.to_string()),
287                ],
288            )
289            .await
290            .map_err(BaseError::DatabaseQueryFailed)?;
291        Ok(records.into_iter().next())
292    }
293
294    fn validate_migration_record(
295        &self,
296        module: &str,
297        version: &str,
298        expected_checksum: &str,
299        record: Option<MigrationRecord>,
300    ) -> Result<bool, BaseError> {
301        match classify_migration_record(
302            record
303                .as_ref()
304                .map(|record| (record.checksum.as_deref(), record.status.as_str())),
305            expected_checksum,
306        ) {
307            MigrationPlanStatus::Pending => Ok(false),
308            MigrationPlanStatus::Applied => Ok(true),
309            MigrationPlanStatus::ChecksumMismatch => Err(BaseError::MigrationChecksumMismatch {
310                module: module.to_string(),
311                version: version.to_string(),
312                expected: expected_checksum.to_string(),
313                actual: record.and_then(|record| record.checksum),
314            }),
315            MigrationPlanStatus::InProgress => Err(BaseError::MigrationInProgress {
316                module: module.to_string(),
317                version: version.to_string(),
318            }),
319        }
320    }
321
322    /// 初始化所有插件的数据库
323    ///
324    /// # 参数
325    ///
326    /// - `plugin_manager`: 插件管理器
327    ///
328    /// # 返回
329    ///
330    /// - `Ok(())`: 初始化成功
331    /// - `Err(BaseError)`: 初始化失败
332    ///
333    /// # 说明
334    ///
335    /// 使用 yang-db::Database::execute 和 yang-db::Database::transaction 方法。
336    /// 根据 use_transaction 标志选择事务或非事务模式。
337    ///
338    /// # 示例
339    ///
340    /// ```rust,ignore
341    /// use yang_base::database::DatabaseInitializer;
342    /// use yang_base::plugin::PluginManager;
343    /// use yang_db::Database;
344    ///
345    /// let db = Database::connect("mysql://root:password@localhost/test").await?;
346    /// let manager = PluginManager::new();
347    /// manager.register(MyPlugin).await?;
348    ///
349    /// let initializer = DatabaseInitializer::new(db, true);
350    /// initializer.initialize_all(&manager).await?;
351    /// ```
352    pub async fn initialize_all(&self, plugin_manager: &PluginManager) -> Result<(), BaseError> {
353        log::info!("开始初始化数据库...");
354
355        // 创建迁移记录表(使用 yang-db::Database::execute)
356        self.create_migration_table().await?;
357
358        // 获取所有插件(已按依赖关系排序)
359        let plugins = plugin_manager.get_all().await;
360
361        if self.use_transaction {
362            // 事务模式:所有插件在一个事务中初始化(使用 yang-db::Transaction)
363            self.initialize_with_transaction(&plugins).await?;
364        } else {
365            // 非事务模式:逐个插件初始化(使用 yang-db::Database::execute)
366            self.initialize_without_transaction(&plugins).await?;
367        }
368
369        log::info!("数据库初始化完成");
370        Ok(())
371    }
372
373    /// 使用事务模式初始化
374    ///
375    /// # 参数
376    ///
377    /// - `plugins`: 插件列表(已按依赖关系排序)
378    ///
379    /// # 返回
380    ///
381    /// - `Ok(())`: 初始化成功
382    /// - `Err(BaseError)`: 初始化失败
383    ///
384    /// # 说明
385    ///
386    /// 使用 yang-db::Database::transaction 创建事务。
387    /// 使用 yang-db::Transaction::execute 执行 SQL。
388    /// 使用 yang-db::Transaction::commit 提交事务。
389    #[allow(deprecated)]
390    async fn initialize_with_transaction(
391        &self,
392        plugins: &[Arc<dyn Plugin>],
393    ) -> Result<(), BaseError> {
394        let mut tx = self
395            .db()
396            .transaction()
397            .await
398            .map_err(BaseError::DatabaseTransactionFailed)?;
399
400        for plugin in plugins {
401            let name = plugin.name();
402            log::info!("初始化插件数据库: {}", name);
403
404            // 执行初始化 SQL(使用 yang-db::Transaction::execute)
405            for sql in plugin.init_sql() {
406                if let Err(e) = tx.execute(&sql).await {
407                    log::error!("插件 {} 初始化失败: {}", name, e);
408                    return Err(BaseError::PluginLifecycleFailed {
409                        plugin: name.to_string(),
410                        stage: PluginLifecycleStage::Initialize,
411                        source: Box::new(e),
412                    });
413                }
414            }
415
416            // 执行迁移
417            self.run_migrations_in_tx(&mut tx, plugin.as_ref()).await?;
418
419            // 调用初始化回调
420            if let Err(e) = plugin.on_init().await {
421                log::error!("插件 {} 初始化回调失败: {}", name, e);
422                return Err(BaseError::PluginLifecycleFailed {
423                    plugin: name.to_string(),
424                    stage: PluginLifecycleStage::Initialize,
425                    source: e,
426                });
427            }
428        }
429
430        tx.commit()
431            .await
432            .map_err(BaseError::DatabaseTransactionFailed)?;
433
434        Ok(())
435    }
436
437    /// 不使用事务模式初始化
438    ///
439    /// # 参数
440    ///
441    /// - `plugins`: 插件列表(已按依赖关系排序)
442    ///
443    /// # 返回
444    ///
445    /// - `Ok(())`: 初始化成功
446    /// - `Err(BaseError)`: 初始化失败
447    ///
448    /// # 说明
449    ///
450    /// 使用 yang-db::Database::execute 执行 SQL。
451    #[allow(deprecated)]
452    async fn initialize_without_transaction(
453        &self,
454        plugins: &[Arc<dyn Plugin>],
455    ) -> Result<(), BaseError> {
456        for plugin in plugins {
457            let name = plugin.name();
458            log::info!("初始化插件数据库: {}", name);
459
460            // 执行初始化 SQL(使用 yang-db::Database::execute)
461            for sql in plugin.init_sql() {
462                if let Err(e) = self.db().execute(&sql).await {
463                    log::error!("插件 {} 初始化失败: {}", name, e);
464                    return Err(BaseError::PluginLifecycleFailed {
465                        plugin: name.to_string(),
466                        stage: PluginLifecycleStage::Initialize,
467                        source: Box::new(e),
468                    });
469                }
470            }
471
472            // 执行迁移
473            self.run_migrations(plugin.as_ref()).await?;
474
475            // 调用初始化回调
476            if let Err(e) = plugin.on_init().await {
477                log::error!("插件 {} 初始化回调失败: {}", name, e);
478                return Err(BaseError::PluginLifecycleFailed {
479                    plugin: name.to_string(),
480                    stage: PluginLifecycleStage::Initialize,
481                    source: e,
482                });
483            }
484        }
485
486        Ok(())
487    }
488
489    /// 创建迁移记录表
490    ///
491    /// # 返回
492    ///
493    /// - `Ok(())`: 创建成功
494    /// - `Err(BaseError)`: 创建失败
495    ///
496    /// # 说明
497    ///
498    /// 使用 yang-db::Database::execute 执行 SQL。
499    #[allow(deprecated)]
500    pub async fn create_migration_table(&self) -> Result<(), BaseError> {
501        let sql = r#"
502            CREATE TABLE IF NOT EXISTS _migrations (
503                id INT AUTO_INCREMENT PRIMARY KEY,
504                module_name VARCHAR(255) NOT NULL COMMENT '模块名称',
505                version VARCHAR(255) NOT NULL COMMENT '迁移版本',
506                checksum CHAR(16) NULL COMMENT 'FNV-1a 迁移内容校验和',
507                status VARCHAR(16) NOT NULL DEFAULT 'applied' COMMENT 'running/applied',
508                executed_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '执行时间',
509                UNIQUE KEY unique_migration (module_name, version),
510                INDEX idx_module_name (module_name)
511            ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='数据库迁移记录表'
512        "#;
513
514        self.db()
515            .execute(sql)
516            .await
517            .map_err(BaseError::DatabaseExecuteFailed)?;
518
519        self.ensure_migration_column(
520            "checksum",
521            "ALTER TABLE _migrations ADD COLUMN checksum CHAR(16) NULL AFTER version",
522        )
523        .await?;
524        self.ensure_migration_column(
525            "status",
526            "ALTER TABLE _migrations ADD COLUMN status VARCHAR(16) NOT NULL DEFAULT 'applied' AFTER checksum",
527        )
528        .await?;
529
530        Ok(())
531    }
532
533    async fn ensure_migration_column(
534        &self,
535        column: &str,
536        alter_sql: &str,
537    ) -> Result<(), BaseError> {
538        #[derive(sqlx::FromRow)]
539        struct CountResult {
540            count: i64,
541        }
542        let rows: Vec<CountResult> = self
543            .db()
544            .query_with_params(
545                "SELECT COUNT(*) AS count FROM information_schema.columns WHERE table_schema = DATABASE() AND table_name = '_migrations' AND column_name = ?",
546                vec![serde_json::Value::String(column.to_string())],
547            )
548            .await
549            .map_err(BaseError::DatabaseQueryFailed)?;
550        if rows.first().map(|row| row.count).unwrap_or(0) == 0 {
551            #[allow(deprecated)]
552            self.db()
553                .execute(alter_sql)
554                .await
555                .map_err(BaseError::DatabaseExecuteFailed)?;
556        }
557        Ok(())
558    }
559
560    /// 执行迁移(非事务模式)
561    ///
562    /// # 参数
563    ///
564    /// - `plugin`: 插件实例
565    ///
566    /// # 返回
567    ///
568    /// - `Ok(())`: 迁移成功
569    /// - `Err(BaseError)`: 迁移失败
570    ///
571    /// # 说明
572    ///
573    /// 使用 yang-db::Database::execute 执行 SQL。
574    #[allow(deprecated)]
575    pub async fn run_migrations(&self, plugin: &dyn Plugin) -> Result<(), BaseError> {
576        let module_name = plugin.name();
577
578        for (version, sql) in plugin.migration_sql() {
579            let checksum = migration_checksum(&sql);
580            if self.validate_migration_record(
581                module_name,
582                &version,
583                &checksum,
584                self.load_migration_record(module_name, &version).await?,
585            )? {
586                continue;
587            }
588
589            if let Err(reservation_error) = self
590                .record_migration_with_checksum(module_name, &version, &checksum, "running")
591                .await
592            {
593                let record = self.load_migration_record(module_name, &version).await?;
594                if self.validate_migration_record(module_name, &version, &checksum, record)? {
595                    continue;
596                }
597                return Err(reservation_error);
598            }
599
600            log::info!("执行迁移: {} v{}", module_name, version);
601
602            if let Err(source) = self.db().execute(&sql).await {
603                let _ = self
604                    .delete_migration_reservation(module_name, &version, &checksum)
605                    .await;
606                return Err(migration_execution_error(
607                    module_name,
608                    &version,
609                    &sql,
610                    source,
611                ));
612            }
613            self.mark_migration_applied(module_name, &version, &checksum)
614                .await?;
615        }
616
617        Ok(())
618    }
619
620    /// 执行迁移(事务模式)
621    ///
622    /// # 参数
623    ///
624    /// - `tx`: yang-db 事务对象
625    /// - `plugin`: 插件实例
626    ///
627    /// # 返回
628    ///
629    /// - `Ok(())`: 迁移成功
630    /// - `Err(BaseError)`: 迁移失败
631    ///
632    /// # 说明
633    ///
634    /// 使用 yang-db::Transaction::execute 执行 SQL。
635    #[allow(deprecated)]
636    pub async fn run_migrations_in_tx(
637        &self,
638        tx: &mut yang_db::Transaction,
639        plugin: &dyn Plugin,
640    ) -> Result<(), BaseError> {
641        let module_name = plugin.name();
642
643        for (version, sql) in plugin.migration_sql() {
644            let checksum = migration_checksum(&sql);
645            let record_sql = "SELECT checksum, status FROM _migrations WHERE module_name = ? AND version = ? LIMIT 1";
646            let record_params = vec![
647                serde_json::Value::String(module_name.to_string()),
648                serde_json::Value::String(version.clone()),
649            ];
650            let records: Vec<MigrationRecord> = tx
651                .query_with_params(record_sql, record_params)
652                .await
653                .map_err(BaseError::DatabaseQueryFailed)?;
654            if self.validate_migration_record(
655                module_name,
656                &version,
657                &checksum,
658                records.into_iter().next(),
659            )? {
660                continue;
661            }
662
663            let reserve_sql = "INSERT INTO _migrations (module_name, version, checksum, status) VALUES (?, ?, ?, 'running')";
664            let reserve_params = vec![
665                serde_json::Value::String(module_name.to_string()),
666                serde_json::Value::String(version.clone()),
667                serde_json::Value::String(checksum.clone()),
668            ];
669            tx.execute_with_params(reserve_sql, reserve_params)
670                .await
671                .map_err(BaseError::DatabaseExecuteFailed)?;
672
673            log::info!("执行迁移: {} v{}", module_name, version);
674
675            if let Err(source) = tx.execute(&sql).await {
676                let cleanup_sql = "DELETE FROM _migrations WHERE module_name = ? AND version = ? AND checksum = ? AND status = 'running'";
677                let cleanup_params = vec![
678                    serde_json::Value::String(module_name.to_string()),
679                    serde_json::Value::String(version.clone()),
680                    serde_json::Value::String(checksum.clone()),
681                ];
682                let _ = tx.execute_with_params(cleanup_sql, cleanup_params).await;
683                return Err(migration_execution_error(
684                    module_name,
685                    &version,
686                    &sql,
687                    source,
688                ));
689            }
690
691            let applied_sql = "UPDATE _migrations SET status = 'applied', executed_at = CURRENT_TIMESTAMP WHERE module_name = ? AND version = ? AND checksum = ? AND status = 'running'";
692            let applied_params = vec![
693                serde_json::Value::String(module_name.to_string()),
694                serde_json::Value::String(version.clone()),
695                serde_json::Value::String(checksum),
696            ];
697            let affected = tx
698                .execute_with_params(applied_sql, applied_params)
699                .await
700                .map_err(BaseError::DatabaseExecuteFailed)?;
701            if affected != 1 {
702                return Err(BaseError::DatabaseMigrationFailed(
703                    module_name.to_string(),
704                    format!("迁移 v{version} 的 running 预留已丢失"),
705                ));
706            }
707        }
708
709        Ok(())
710    }
711
712    /// 检查迁移是否已执行
713    ///
714    /// # 参数
715    ///
716    /// - `module_name`: 模块名称
717    /// - `version`: 迁移版本
718    ///
719    /// # 返回
720    ///
721    /// - `Ok(bool)`: true 表示已执行,false 表示未执行
722    /// - `Err(BaseError)`: 查询失败
723    ///
724    /// # 说明
725    ///
726    /// 使用参数化查询,防止 SQL 注入攻击。
727    pub async fn is_migration_executed(
728        &self,
729        module_name: &str,
730        version: &str,
731    ) -> Result<bool, BaseError> {
732        // 定义查询结果结构体
733        #[derive(sqlx::FromRow)]
734        struct CountResult {
735            count: i64,
736        }
737
738        // 使用参数占位符,防止 SQL 注入
739        let sql = "SELECT COUNT(*) as count FROM _migrations WHERE module_name = ? AND version = ? AND status = 'applied'";
740        let params = vec![
741            serde_json::Value::String(module_name.to_string()),
742            serde_json::Value::String(version.to_string()),
743        ];
744
745        // 使用 yang-db::Database::query_with_params 方法
746        let results: Vec<CountResult> = self
747            .db()
748            .query_with_params(sql, params)
749            .await
750            .map_err(BaseError::DatabaseQueryFailed)?;
751
752        Ok(results.first().map(|r| r.count > 0).unwrap_or(false))
753    }
754
755    /// 记录迁移
756    ///
757    /// # 参数
758    ///
759    /// - `module_name`: 模块名称
760    /// - `version`: 迁移版本
761    ///
762    /// # 返回
763    ///
764    /// - `Ok(())`: 记录成功
765    /// - `Err(BaseError)`: 记录失败
766    ///
767    /// # 说明
768    ///
769    /// 使用参数化查询,防止 SQL 注入攻击。
770    pub async fn record_migration_with_checksum(
771        &self,
772        module_name: &str,
773        version: &str,
774        checksum: &str,
775        status: &str,
776    ) -> Result<(), BaseError> {
777        if !matches!(status, "running" | "applied") {
778            return Err(BaseError::DatabaseMigrationFailed(
779                module_name.to_string(),
780                format!("非法迁移状态: {status}"),
781            ));
782        }
783        let sql =
784            "INSERT INTO _migrations (module_name, version, checksum, status) VALUES (?, ?, ?, ?)";
785        let params = vec![
786            serde_json::Value::String(module_name.to_string()),
787            serde_json::Value::String(version.to_string()),
788            serde_json::Value::String(checksum.to_string()),
789            serde_json::Value::String(status.to_string()),
790        ];
791
792        self.db()
793            .execute_with_params(sql, params)
794            .await
795            .map_err(BaseError::DatabaseExecuteFailed)?;
796
797        Ok(())
798    }
799
800    async fn mark_migration_applied(
801        &self,
802        module: &str,
803        version: &str,
804        checksum: &str,
805    ) -> Result<(), BaseError> {
806        let affected = self
807            .db()
808            .execute_with_params(
809                "UPDATE _migrations SET status = 'applied', executed_at = CURRENT_TIMESTAMP WHERE module_name = ? AND version = ? AND checksum = ? AND status = 'running'",
810                vec![
811                    serde_json::Value::String(module.to_string()),
812                    serde_json::Value::String(version.to_string()),
813                    serde_json::Value::String(checksum.to_string()),
814                ],
815            )
816            .await
817            .map_err(BaseError::DatabaseExecuteFailed)?;
818        if affected != 1 {
819            return Err(BaseError::DatabaseMigrationFailed(
820                module.to_string(),
821                format!("迁移 v{version} 的 running 预留已丢失"),
822            ));
823        }
824        Ok(())
825    }
826
827    async fn delete_migration_reservation(
828        &self,
829        module: &str,
830        version: &str,
831        checksum: &str,
832    ) -> Result<(), BaseError> {
833        self.db()
834            .execute_with_params(
835                "DELETE FROM _migrations WHERE module_name = ? AND version = ? AND checksum = ? AND status = 'running'",
836                vec![
837                    serde_json::Value::String(module.to_string()),
838                    serde_json::Value::String(version.to_string()),
839                    serde_json::Value::String(checksum.to_string()),
840                ],
841            )
842            .await
843            .map_err(BaseError::DatabaseExecuteFailed)?;
844        Ok(())
845    }
846}
847
848#[cfg(test)]
849mod tests {
850    use super::*;
851    use std::error::Error;
852
853    #[test]
854    fn migration_execution_error_preserves_identity_checksum_and_source() {
855        let sql = "ALTER TABLE users ADD COLUMN status INT";
856        let error = migration_execution_error(
857            "accounts",
858            "202607150001",
859            sql,
860            yang_db::DbError::SqlSyntaxError("bad ddl".into()),
861        );
862
863        match &error {
864            BaseError::MigrationExecutionFailed {
865                module,
866                version,
867                checksum,
868                ..
869            } => {
870                assert_eq!(module, "accounts");
871                assert_eq!(version, "202607150001");
872                assert_eq!(checksum, &migration_checksum(sql));
873                assert_ne!(checksum, &migration_checksum("ALTER TABLE users"));
874            }
875            other => panic!("期望 MigrationExecutionFailed,得到: {other:?}"),
876        }
877        assert!(error.source().is_some());
878    }
879
880    #[test]
881    fn migration_record_classification_detects_drift_and_in_progress() {
882        assert_eq!(
883            classify_migration_record(None, "new-checksum"),
884            MigrationPlanStatus::Pending
885        );
886        assert_eq!(
887            classify_migration_record(Some((Some("same"), "applied")), "same"),
888            MigrationPlanStatus::Applied
889        );
890        assert_eq!(
891            classify_migration_record(Some((Some("old"), "applied")), "new"),
892            MigrationPlanStatus::ChecksumMismatch
893        );
894        assert_eq!(
895            classify_migration_record(Some((None, "applied")), "new"),
896            MigrationPlanStatus::ChecksumMismatch
897        );
898        assert_eq!(
899            classify_migration_record(Some((Some("same"), "running")), "same"),
900            MigrationPlanStatus::InProgress
901        );
902    }
903}