1use 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#[derive(Debug, Clone, Copy, PartialEq, Eq)]
39#[non_exhaustive]
40pub enum MigrationPlanStatus {
41 Pending,
43 Applied,
45 ChecksumMismatch,
47 InProgress,
49}
50
51#[derive(Debug, Clone, PartialEq, Eq)]
53pub struct MigrationPlanEntry {
54 pub module: String,
56 pub version: String,
58 pub checksum: String,
60 pub status: MigrationPlanStatus,
62}
63
64#[derive(Debug, Clone, Default, PartialEq, Eq)]
66pub struct MigrationPlan {
67 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
91fn 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
115pub struct DatabaseInitializer {
135 db: Database,
137
138 use_transaction: bool,
140}
141
142impl DatabaseInitializer {
143 pub fn new(db: Database, use_transaction: bool) -> Self {
170 Self {
171 db,
172 use_transaction,
173 }
174 }
175
176 pub(crate) fn db(&self) -> &Database {
179 &self.db
180 }
181
182 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 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 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 pub async fn initialize_all(&self, plugin_manager: &PluginManager) -> Result<(), BaseError> {
353 log::info!("开始初始化数据库...");
354
355 self.create_migration_table().await?;
357
358 let plugins = plugin_manager.get_all().await;
360
361 if self.use_transaction {
362 self.initialize_with_transaction(&plugins).await?;
364 } else {
365 self.initialize_without_transaction(&plugins).await?;
367 }
368
369 log::info!("数据库初始化完成");
370 Ok(())
371 }
372
373 #[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 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 self.run_migrations_in_tx(&mut tx, plugin.as_ref()).await?;
418
419 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 #[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 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 self.run_migrations(plugin.as_ref()).await?;
474
475 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 #[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 #[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 #[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 pub async fn is_migration_executed(
728 &self,
729 module_name: &str,
730 version: &str,
731 ) -> Result<bool, BaseError> {
732 #[derive(sqlx::FromRow)]
734 struct CountResult {
735 count: i64,
736 }
737
738 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 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 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}