//! Tracked SQL migrations. The core's own database updater is disabled in this project, so schema changes //! shipped with a release are applied here, one file at a time, recorded in a ledger table, and never twice. use std::path::Path; use serde::Serialize; use crate::db::{self, Db}; use crate::error::{Error, Result}; use crate::fsx; use crate::manifest::Migration; const LEDGER_SCHEMA: &str = "acore_world"; const AUTH_LEDGER_SCHEMA: &str = "acore_auth"; const LEDGER_TABLE: &str = "coa_manager_migrations"; #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)] #[serde(rename_all = "lowercase")] pub enum Status { Applied, Pending, Failed, Running, } #[derive(Debug, Clone)] pub struct LedgerRow { pub db: String, pub id: String, pub sha256: String, pub status: Status, pub error: Option, pub baseline: bool, } /// Storage for the ledger and the ability to run a SQL file; implemented by the real database and by tests. pub trait Store { fn load(&self) -> Result>; fn load_readonly(&self) -> Result> { self.load() } fn put(&self, row: &LedgerRow) -> Result<()>; fn put_batch(&self, rows: &[LedgerRow]) -> Result<()> { for row in rows { self.put(row)?; } Ok(()) } fn run_file(&self, schema: &str, file: &Path) -> Result<()>; } fn hex_of(s: &str) -> String { hex::encode(s.as_bytes()) } fn ident_ok(s: &str) -> bool { !s.is_empty() && s.len() <= 150 && s.chars() .all(|c| c.is_ascii_alphanumeric() || matches!(c, '_' | '.' | '-')) } pub(crate) fn shared_auth(kind: &str) -> bool { matches!(db::schema_of(kind), Ok("acore_auth")) } fn create_ledger(db: &Db, schema: &str) -> Result<()> { db.query(&format!("CREATE TABLE IF NOT EXISTS `{schema}`.`{LEDGER_TABLE}` (`db` VARCHAR(32) NOT NULL, `id` VARCHAR(190) NOT NULL, `sha256` CHAR(64) NOT NULL, `status` VARCHAR(16) NOT NULL, `applied_at` DATETIME NOT NULL, `error` TEXT NULL, `baseline` TINYINT NOT NULL DEFAULT 0, PRIMARY KEY (`db`,`id`)) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;"))?; Ok(()) } impl Store for Db { fn load(&self) -> Result> { create_ledger(self, LEDGER_SCHEMA)?; create_ledger(self, AUTH_LEDGER_SCHEMA)?; let rows = self.load_readonly()?; // Preserve already-recorded core history even if a module later replaces its updates table. // A zero checksum remains unknown; importing it does not invent a checksum for old SQL. let selected: std::collections::BTreeMap<_, _> = rows .iter() .map(|row| ((row.db.clone(), row.id.to_ascii_lowercase()), row)) .collect(); let core: Vec<_> = selected .values() .filter(|r| { r.status == Status::Applied && r.baseline && r.sha256 == "0".repeat(64) && matches!(r.db.as_str(), "world" | "characters") && ident_ok(&r.id) }) .map(|r| (*r).clone()) .collect(); self.put_batch(&core)?; Ok(rows) } fn load_readonly(&self) -> Result> { // Resolve physical schemas once, then read all history in two client calls. // Using a neutral connection prevents a Wildcard query from rerouting the other realm. let connection = self.clone().for_realm(crate::realms::Mode::Coa); let world = self.realm_schema("acore_world"); let characters = self.realm_schema("acore_characters"); let others: Vec<_> = [ crate::realms::Mode::Coa, crate::realms::Mode::Wildcard, crate::realms::Mode::Reborn, ] .into_iter() .filter(|m| *m != self.realm()) .map(|m| m.schema("world").unwrap()) .collect(); let schemas: std::collections::BTreeSet<_> = [world, characters, AUTH_LEDGER_SCHEMA] .into_iter() .chain(others.iter().copied()) .collect(); let catalog = connection.query(&format!("SELECT table_schema,table_name FROM information_schema.tables WHERE table_schema IN ('{}') AND table_name IN ('updates','{LEDGER_TABLE}') AND table_type='BASE TABLE';", schemas.into_iter().collect::>().join("','")))?; let available: std::collections::BTreeSet<_> = catalog .lines() .filter_map(|line| line.split_once('\t')) .collect(); let text = |expression: &str| format!("CONVERT({expression} USING utf8mb4) COLLATE utf8mb4_bin"); let mut queries = Vec::new(); for (kind, schema) in [ ("characters", characters), ("auth", AUTH_LEDGER_SCHEMA), ("world", world), ] { if available.contains(&(schema, "updates")) { queries.push(format!("SELECT 'core','{kind}',{},REPEAT('0',64),'applied',1,'' FROM `{schema}`.`updates` WHERE BINARY RIGHT(name,4)='.sql'",text("LEFT(name,CHAR_LENGTH(name)-4)"))); } } for (origin, schema, filter) in [("local", world, ""), ("shared", AUTH_LEDGER_SCHEMA, "")] .into_iter() .chain(others.iter().map(|schema| { ( "other", *schema, " WHERE `db` IN ('auth','coa-auth','wildcard-auth','reborn-auth')", ) })) { if available.contains(&(schema, LEDGER_TABLE)) { queries.push(format!("SELECT '{origin}',{},{},{},{},`baseline`,{} FROM `{schema}`.`{LEDGER_TABLE}`{filter}",text("`db`"),text("`id`"),text("`sha256`"),text("`status`"),text("COALESCE(HEX(`error`),'')"))); } } if queries.is_empty() { return Ok(vec![]); } let out = connection.query(&queries.join(" UNION ALL "))?; let (mut rows, mut local, mut auth, mut shared) = (Vec::new(), Vec::new(), Vec::new(), Vec::new()); for line in out.lines().filter(|l| !l.is_empty()) { let f: Vec<_> = line.split('\t').collect(); if f.len() < 6 { return Err(Error::Invalid( "The database migration history is malformed; no SQL was replayed.".into(), )); } // Unrelated legacy filenames cannot match a valid manifest migration ID. if f[0] == "core" && !ident_ok(f[2]) { continue; } if !matches!(f[4], "applied" | "failed" | "running") || !ident_ok(f[2]) || f[3].len() != 64 || !f[3].chars().all(|c| c.is_ascii_hexdigit()) { return Err(Error::Invalid( "The database migration history is invalid; no SQL was replayed.".into(), )); } let error = f .get(6) .filter(|h| !h.is_empty()) .and_then(|h| hex::decode(h).ok()) .map(|b| String::from_utf8_lossy(&b).into_owned()); let row = LedgerRow { db: f[1].into(), id: f[2].into(), sha256: f[3].into(), status: match f[4] { "applied" => Status::Applied, "running" => Status::Running, _ => Status::Failed, }, baseline: f[5] == "1", error, }; match f[0] { "core" => rows.push(row), "local" if !shared_auth(&row.db) => local.push(row), "local" | "other" => auth.push(row), "shared" => shared.push(row), _ => return Err(Error::Invalid("Unknown migration history source.".into())), } } rows.extend(local); // An interrupted legacy auth execution must not be hidden by another realm's applied row. auth.sort_by_key(|r| { ( match r.status { Status::Applied => 0, Status::Running => 1, Status::Failed => 2, Status::Pending => 3, }, r.sha256 != "0".repeat(64), ) }); for mut row in auth { row.db = "auth".into(); rows.push(row); } // New auth records live with the shared account database and are authoritative. for mut row in shared { if !shared_auth(&row.db) { return Err(Error::Invalid( "The shared authentication migration history is invalid.".into(), )); } rows.retain(|r| !(shared_auth(&r.db) && r.id.eq_ignore_ascii_case(&row.id))); row.db = "auth".into(); rows.push(row); } Ok(rows) } fn put(&self, row: &LedgerRow) -> Result<()> { self.put_batch(std::slice::from_ref(row)) } fn put_batch(&self, rows: &[LedgerRow]) -> Result<()> { let mut groups = std::collections::BTreeMap::<&str, Vec>::new(); for r in rows { if !ident_ok(&r.id) || !ident_ok(&r.db) || r.sha256.len() != 64 || !r.sha256.chars().all(|c| c.is_ascii_hexdigit()) { return Err(Error::Invalid( "migration record has an invalid identifier".into(), )); } let status = match r.status { Status::Applied => "applied", Status::Running => "running", _ => "failed", }; let error = r .error .as_deref() .map(|e| format!("UNHEX('{}')", hex_of(e))) .unwrap_or_else(|| "NULL".into()); let (schema, kind) = if shared_auth(&r.db) { (AUTH_LEDGER_SCHEMA, "auth") } else { (LEDGER_SCHEMA, r.db.as_str()) }; groups.entry(schema).or_default().push(format!( "('{}','{}','{}','{status}',NOW(),{error},{})", kind, r.id, r.sha256, r.baseline as u8 )); } for (schema, values) in groups { self.query(&format!("REPLACE INTO `{schema}`.`{LEDGER_TABLE}` (`db`,`id`,`sha256`,`status`,`applied_at`,`error`,`baseline`) VALUES {};",values.join(",")))?; } Ok(()) } fn run_file(&self, schema: &str, file: &Path) -> Result<()> { self.run_sql_file(schema, file) } } /// Statements that can lose data. Detection is deliberately conservative: a false positive only costs a backup. pub fn looks_destructive(sql: &str) -> bool { let upper: String = sql .lines() .filter(|l| !l.trim_start().starts_with("--") && !l.trim_start().starts_with('#')) .collect::>() .join(" ") .to_uppercase(); [ "DROP TABLE", "DROP DATABASE", "DROP SCHEMA", "TRUNCATE", "DELETE FROM", "DROP COLUMN", "DROP INDEX", "DROP PRIMARY", "DROP FOREIGN", ] .iter() .any(|k| upper.contains(k)) } #[derive(Debug, Clone, Serialize)] pub struct Item { pub id: String, pub db: String, pub status: Status, pub destructive: bool, pub baseline: bool, pub error: Option, } #[derive(Debug, Serialize)] #[serde(rename_all = "camelCase")] pub struct Audit { pub total: usize, pub applied: usize, pub checksum_verified: usize, pub legacy_unknown: usize, } pub fn inventory_sha256(list: &[Migration]) -> Result { let inventory: Vec<_> = list .iter() .map(|m| (&m.db, &m.id, &m.sha256, &m.compatible_sha256, m.destructive)) .collect(); Ok(fsx::sha256_bytes(&serde_json::to_vec(&inventory)?)) } pub fn audit_applied(store: &dyn Store, list: &[Migration]) -> Result { let rows = store.load_readonly()?; check_history(&rows, list)?; let mut audit = Audit { total: list.len(), applied: 0, checksum_verified: 0, legacy_unknown: 0, }; for migration in list { let row = recorded(&rows, migration) .filter(|r| r.status == Status::Applied) .ok_or_else(|| { Error::Invalid(format!( "Release migration {} ({}) is not recorded as applied.", migration.id, migration.db )) })?; audit.applied += 1; if row.sha256 == "0".repeat(64) { audit.legacy_unknown += 1; } else { audit.checksum_verified += 1; } } Ok(audit) } pub fn status(store: &dyn Store, list: &[Migration]) -> Result> { let rows = store.load()?; Ok(list .iter() .map(|m| { // Manager records are appended after the core's updates table and are authoritative. let row = recorded(&rows, m); let history = effective_history(&rows, m); let changed = history.iter().any(|r| hash_changed(r,m)); let interrupted = history.iter().find(|r| matches!(r.status, Status::Running | Status::Failed)); Item { id: m.id.clone(), db: m.db.clone(), status: if changed || interrupted.is_some() { Status::Failed } else { row.map(|r| r.status).unwrap_or(Status::Pending) }, destructive: m.destructive, baseline: row.map(|r| r.baseline).unwrap_or(false), error: if changed { Some("An already applied SQL file changed. Publish a new migration instead of replaying it.".into()) } else { interrupted.and_then(|r| r.error.clone()).or_else(|| row.and_then(|r| r.error.clone())) }, } }) .collect()) } fn recorded<'a>(rows: &'a [LedgerRow], m: &Migration) -> Option<&'a LedgerRow> { rows.iter().rev().find(|r| { (r.db == m.db || shared_auth(&r.db) && shared_auth(&m.db)) && r.id.eq_ignore_ascii_case(&m.id) }) } fn effective_history<'a>(rows: &'a [LedgerRow], m: &Migration) -> Vec<&'a LedgerRow> { if shared_auth(&m.db) { rows.iter() .filter(|r| shared_auth(&r.db) && r.id.eq_ignore_ascii_case(&m.id)) .collect() } else { recorded(rows, m).into_iter().collect() } } fn preserve_auth_history(store: &dyn Store, rows: &[LedgerRow], list: &[Migration]) -> Result<()> { let applied: Vec<_> = list .iter() .filter(|m| shared_auth(&m.db)) .filter_map(|m| recorded(rows, m)) .filter(|r| r.status == Status::Applied) .cloned() .collect(); store.put_batch(&applied) } /// Migrations that were published with different bytes but have the same effect, so a server that applied either /// version accepts the other. The Wildcard table repair went out as `c1d8…` (0.261005.0, 0.261006.1) and as `9e4a…` /// (0.261005.22, 0.261007.24); the packages carry no list of compatible versions, so the Manager knows this pair. const SAME_EFFECT: &[(&str, &[&str])] = &[( "manager_repair__20261005_missing_wildcard_tables", &[ "c1d8dbf2271234283a48a39e4b4aea1106b83b70581f1e3c4aa9fff438e8e4d2", "9e4a36245c3f83255415c122c01f08ceb3e3b83898d3d427ac4e2fbcf61e9638", ], )]; fn same_effect(id: &str, a: &str, b: &str) -> bool { SAME_EFFECT.iter().any(|(known, hashes)| { known.eq_ignore_ascii_case(id) && hashes.iter().any(|h| h.eq_ignore_ascii_case(a)) && hashes.iter().any(|h| h.eq_ignore_ascii_case(b)) }) } fn hash_changed(row: &LedgerRow, m: &Migration) -> bool { row.status == Status::Applied && row.sha256 != "0".repeat(64) && !row.sha256.eq_ignore_ascii_case(&m.sha256) && !m .compatible_sha256 .iter() .any(|hash| hash.eq_ignore_ascii_case(&row.sha256)) && !same_effect(&m.id, &row.sha256, &m.sha256) } /// Inspect recorded history without creating a ledger or executing migrations. pub fn preflight(store: &dyn Store, list: &[Migration]) -> Result<()> { check_history(&store.load_readonly()?, list) } pub fn pending_count(store: &dyn Store, list: &[Migration]) -> Result { let rows = store.load_readonly()?; Ok(pending_migrations(&rows, list)?.len()) } fn verified_file(m: &Migration, dir: &Path) -> Result<(&'static str, std::path::PathBuf, bool)> { if !ident_ok(&m.id) { return Err(Error::InvalidManifest(format!( "migration id {:?} is not allowed", m.id ))); } let schema = db::schema_of(&m.db)?; let path = fsx::safe_join(dir, &format!("{}/{}.sql", m.db, m.id))?; let bytes = std::fs::read(&path) .map_err(|_| Error::Invalid(format!("migration file {} is missing", m.id)))?; let actual = fsx::sha256_bytes(&bytes); if !actual.eq_ignore_ascii_case(&m.sha256) { return Err(Error::HashMismatch { path: path.display().to_string(), expected: m.sha256.clone(), actual, }); } Ok(( schema, path, m.destructive || looks_destructive(&String::from_utf8_lossy(&bytes)), )) } /// Check every migration artifact, including applied history, before replacing server files. pub fn verify_files(list: &[Migration], dir: &Path) -> Result<()> { validate_list(list)?; for m in list { verified_file(m, dir)?; } Ok(()) } fn validate_list(list: &[Migration]) -> Result<()> { let mut seen = std::collections::BTreeSet::new(); for m in list { if !ident_ok(&m.id) { return Err(Error::InvalidManifest(format!( "migration id {:?} is not allowed", m.id ))); } let schema = db::schema_of(&m.db)?; if !seen.insert((schema, m.id.to_ascii_lowercase())) { return Err(Error::InvalidManifest(format!( "duplicate migration {} ({})", m.id, m.db ))); } } Ok(()) } fn pending_migrations<'a>(rows: &[LedgerRow], list: &'a [Migration]) -> Result> { check_history(rows, list)?; Ok(list .iter() .filter(|m| recorded(rows, m).is_none_or(|r| r.status != Status::Applied)) .collect()) } fn check_history(rows: &[LedgerRow], list: &[Migration]) -> Result<()> { validate_list(list)?; for m in list { for row in effective_history(rows, m) { if matches!(row.status, Status::Running | Status::Failed) { return Err(Error::Invalid(format!("Database update {} ({}) failed or was interrupted and may be partially applied. Restore its recovery point before retrying.", m.id, m.db))); } if hash_changed(row, m) { return Err(Error::Invalid(format!("Applied database update {} ({}) has a different checksum. A new migration is required; it was not replayed.", m.id, m.db))); } } } Ok(()) } /// Record migrations as already present without running them (adopting an existing server whose database /// was brought up to date by hand). pub fn baseline(store: &dyn Store, list: &[Migration]) -> Result { let rows = store.load()?; check_history(&rows, list)?; preserve_auth_history(store, &rows, list)?; let mut n = 0; for m in list { if recorded(&rows, m).is_some_and(|r| r.status == Status::Applied) { continue; } store.put(&LedgerRow { db: m.db.clone(), id: m.id.clone(), sha256: m.sha256.clone(), status: Status::Applied, error: None, baseline: true, })?; n += 1; } Ok(n) } #[derive(Debug, Serialize)] pub struct ApplyReport { pub applied: Vec, pub failed: Option<(String, String)>, pub snapshot: Option, } /// Apply every pending migration in list order, stopping at the first failure. `snapshot` runs once, before the /// first pending migration, when any of them is (or looks) destructive. pub fn apply_pending( store: &dyn Store, list: &[Migration], dir: &Path, snapshot: &dyn Fn() -> Result, ) -> Result { let rows = store.load()?; // The list order is the release's order of application (released updates, then pending, then modules). let todo = pending_migrations(&rows, list)?; tracing::info!( total = list.len(), pending = todo.len(), skipped = list.len() - todo.len(), "database migration plan" ); // Resolve and verify every file before running anything. let mut files = Vec::new(); let mut any_destructive = false; for m in &todo { let (schema, path, destructive) = verified_file(m, dir)?; any_destructive |= destructive; files.push((*m, schema, path)); } let mut report = ApplyReport { applied: Vec::new(), failed: None, snapshot: None, }; if files.is_empty() { preserve_auth_history(store, &rows, list)?; return Ok(report); } if any_destructive { report.snapshot = Some(snapshot().map_err(|e| { Error::Invalid(format!( "No database update was applied because the safety backup failed: {e}" )) })?); } preserve_auth_history(store, &rows, list)?; for (m, schema, path) in files { tracing::info!(migration = %m.id, database = %m.db, "database migration starting"); store.put(&LedgerRow { db: m.db.clone(), id: m.id.clone(), sha256: m.sha256.clone(), status: Status::Running, error: Some("Interrupted SQL must be recovered before replay.".into()), baseline: false, })?; match store.run_file(schema, &path) { Ok(()) => { store.put(&LedgerRow { db: m.db.clone(), id: m.id.clone(), sha256: m.sha256.clone(), status: Status::Applied, error: None, baseline: false, })?; report.applied.push(m.id.clone()); tracing::info!(migration = %m.id, database = %m.db, "database migration applied"); } Err(e) => { tracing::error!(migration = %m.id, database = %m.db, "database migration failed; details saved in migration history"); let msg = e.to_string(); let _ = store.put(&LedgerRow { db: m.db.clone(), id: m.id.clone(), sha256: m.sha256.clone(), status: Status::Failed, error: Some(msg.clone()), baseline: false, }); report.failed = Some((m.id.clone(), msg)); break; } } } Ok(report) } #[cfg(test)] mod tests { use super::*; use std::cell::RefCell; #[test] fn the_two_published_versions_of_the_wildcard_table_repair_are_interchangeable() { let (old, new) = ( "c1d8dbf2271234283a48a39e4b4aea1106b83b70581f1e3c4aa9fff438e8e4d2", "9e4a36245c3f83255415c122c01f08ceb3e3b83898d3d427ac4e2fbcf61e9638", ); let id = "manager_repair__20261005_missing_wildcard_tables"; let row = |id: &str, sha: &str| LedgerRow { db: "characters".into(), id: id.into(), sha256: sha.into(), status: Status::Applied, error: None, baseline: false, }; let migration = |id: &str, sha: &str| Migration { compatible_sha256: vec![], id: id.into(), db: "characters".into(), sha256: sha.into(), destructive: false, }; assert!( !hash_changed(&row(id, old), &migration(id, new)), "applied as c1d8, offered as 9e4a" ); assert!( !hash_changed(&row(id, new), &migration(id, old)), "applied as 9e4a, offered as c1d8" ); assert!( hash_changed(&row(id, &"a".repeat(64)), &migration(id, new)), "an unknown version is still a change" ); assert!( hash_changed( &row("other_migration", old), &migration("other_migration", new) ), "only the known pair is exempt" ); } #[derive(Default)] struct Mem { rows: RefCell>, ran: RefCell>, fail_on: Option<&'static str>, } impl Store for Mem { fn load(&self) -> Result> { Ok(self.rows.borrow().clone()) } fn put(&self, r: &LedgerRow) -> Result<()> { let mut rows = self.rows.borrow_mut(); rows.retain(|x| !(x.db == r.db && x.id == r.id)); rows.push(r.clone()); Ok(()) } fn run_file(&self, _schema: &str, file: &Path) -> Result<()> { let name = file.file_stem().unwrap().to_string_lossy().into_owned(); if self.fail_on == Some(Box::leak(name.clone().into_boxed_str())) { return Err(Error::Invalid("syntax error near 'FOO'".into())); } self.ran.borrow_mut().push(name); Ok(()) } } #[test] fn qualification_inventory_digest_matches_release_pipeline_encoding() { let list = vec![Migration { id: "one".into(), db: "world".into(), sha256: "a".repeat(64), compatible_sha256: vec![], destructive: false, }]; assert_eq!( inventory_sha256(&list).unwrap(), "b35e45f666304500e69ff352f83103910075ace998afb7915b548765b8c30703" ); } #[test] fn qualification_rejects_missing_interrupted_failed_and_changed_history() { let (_dir, list) = setup(&[("world", "qualification_probe", "SELECT 1;")]); let store = Mem::default(); assert!(audit_applied(&store, &list).is_err()); for status in [Status::Running, Status::Failed, Status::Pending] { store .put(&LedgerRow { db: "world".into(), id: list[0].id.clone(), sha256: list[0].sha256.clone(), status, error: None, baseline: false, }) .unwrap(); assert!(audit_applied(&store, &list).is_err()); } store .put(&LedgerRow { db: "world".into(), id: list[0].id.clone(), sha256: "a".repeat(64), status: Status::Applied, error: None, baseline: false, }) .unwrap(); assert!(audit_applied(&store, &list).is_err()); store.rows.borrow_mut()[0].sha256 = list[0].sha256.clone(); assert_eq!(audit_applied(&store, &list).unwrap().checksum_verified, 1); store.rows.borrow_mut()[0].sha256 = "0".repeat(64); let audit = audit_applied(&store, &list).unwrap(); assert_eq!( (audit.applied, audit.checksum_verified, audit.legacy_unknown), (1, 0, 1) ); assert!(store.ran.borrow().is_empty()); } fn setup(files: &[(&str, &str, &str)]) -> (tempfile::TempDir, Vec) { let d = tempfile::tempdir().unwrap(); let mut list = Vec::new(); for (db, id, sql) in files { std::fs::create_dir_all(d.path().join(db)).unwrap(); std::fs::write(d.path().join(db).join(format!("{id}.sql")), sql).unwrap(); list.push(Migration { compatible_sha256: vec![], id: id.to_string(), db: db.to_string(), sha256: fsx::sha256_bytes(sql.as_bytes()), destructive: false, }); } (d, list) } fn no_snapshot() -> Result { panic!("no snapshot expected") } #[test] fn manager_failure_overrides_an_old_core_update_record() { let (d, list) = setup(&[("characters", "same_id", "SELECT 1;")]); let store = Mem::default(); let old = LedgerRow { db: "characters".into(), id: "same_id".into(), sha256: "0".repeat(64), status: Status::Applied, error: None, baseline: true, }; let failed = LedgerRow { sha256: list[0].sha256.clone(), status: Status::Failed, error: Some("previous failure".into()), baseline: false, ..old.clone() }; store.rows.borrow_mut().extend([old, failed]); assert_eq!(status(&store, &list).unwrap()[0].status, Status::Failed); assert!(apply_pending(&store, &list, d.path(), &no_snapshot) .unwrap_err() .to_string() .contains("partially applied")); assert!(store.ran.borrow().is_empty()); } #[test] fn changed_applied_sql_is_reported_and_never_replayed() { let (d, list) = setup(&[("characters", "same_id", "SELECT 1;")]); let store = Mem::default(); store.rows.borrow_mut().push(LedgerRow { db: "characters".into(), id: "same_id".into(), sha256: "a".repeat(64), status: Status::Applied, error: None, baseline: false, }); assert_eq!(status(&store, &list).unwrap()[0].status, Status::Failed); assert!(apply_pending(&store, &list, d.path(), &no_snapshot).is_err()); assert!(store.ran.borrow().is_empty()); } #[test] fn every_entry_point_rejects_duplicate_sql_before_execution() { let (dir, original) = setup(&[("world", "once", "SELECT 1;\n")]); for alias in ["world", "coa-world"] { let mut list = original.clone(); let mut duplicate = original[0].clone(); duplicate.db = alias.into(); list.push(duplicate); let store = Mem::default(); assert!(preflight(&store, &list).is_err()); assert!(pending_count(&store, &list).is_err()); assert!(apply_pending(&store, &list, dir.path(), &no_snapshot).is_err()); assert!(store.ran.borrow().is_empty()); assert!(store.rows.borrow().is_empty()); } } #[test] fn staged_files_reject_missing_corrupt_duplicate_and_invalid_migrations() { let (dir, list) = setup(&[("characters", "repair", "SELECT 1;\n")]); verify_files(&list, dir.path()).unwrap(); let mut bad = list.clone(); bad[0].id = "../outside".into(); assert!(verify_files(&bad, dir.path()).is_err()); bad = list.clone(); bad.push(list[0].clone()); assert!(verify_files(&bad, dir.path()).is_err()); std::fs::write(dir.path().join("characters/repair.sql"), b"SELECT 2;\n").unwrap(); assert!(verify_files(&list, dir.path()).is_err()); std::fs::remove_file(dir.path().join("characters/repair.sql")).unwrap(); assert!(verify_files(&list, dir.path()).is_err()); } #[test] fn preflight_uses_readonly_history_and_rejects_conflicts_without_writes() { struct ReadOnly<'a>(&'a Mem); impl Store for ReadOnly<'_> { fn load(&self) -> Result> { panic!("preflight must use readonly access") } fn load_readonly(&self) -> Result> { self.0.load() } fn put(&self, _: &LedgerRow) -> Result<()> { panic!("preflight must not rewrite history") } fn run_file(&self, _: &str, _: &Path) -> Result<()> { panic!("preflight must not run SQL") } } let (_d, list) = setup(&[("characters", "repair", "SELECT 1;\n")]); for state in [Status::Applied, Status::Running, Status::Failed] { let store = Mem::default(); store.rows.borrow_mut().push(LedgerRow { db: "characters".into(), id: "repair".into(), sha256: "a".repeat(64), status: state, error: None, baseline: false, }); assert!(preflight(&ReadOnly(&store), &list).is_err()); assert_eq!(store.rows.borrow()[0].sha256, "a".repeat(64)); assert_eq!(store.rows.borrow()[0].status, state); } } #[test] fn published_compatibility_preserves_history_and_never_replays_sql() { let (d, mut list) = setup(&[("characters", "repair", "SELECT 1;\n")]); let store = Mem::default(); let old = fsx::sha256_bytes(b"SELECT 1;\r\n"); store.rows.borrow_mut().push(LedgerRow { db: "characters".into(), id: "repair".into(), sha256: old.clone(), status: Status::Applied, error: None, baseline: false, }); assert!(apply_pending(&store, &list, d.path(), &no_snapshot).is_err()); list[0].compatible_sha256.push(old.clone()); assert_eq!(status(&store, &list).unwrap()[0].status, Status::Applied); assert!(apply_pending(&store, &list, d.path(), &no_snapshot) .unwrap() .applied .is_empty()); assert!(store.ran.borrow().is_empty()); assert_eq!(store.rows.borrow()[0].sha256, old); store.rows.borrow_mut()[0].status = Status::Running; assert!(apply_pending(&store, &list, d.path(), &no_snapshot).is_err()); store.rows.borrow_mut()[0].status = Status::Failed; assert!(apply_pending(&store, &list, d.path(), &no_snapshot).is_err()); assert!(store.ran.borrow().is_empty()); } #[test] fn applies_in_order_once_and_records_the_ledger() { let (d, list) = setup(&[ ("world", "2026_09_01_00_a", "CREATE TABLE t (id INT);"), ("world", "2026_09_02_00_b", "ALTER TABLE t ADD c INT;"), ]); let store = Mem::default(); let r = apply_pending(&store, &list, d.path(), &no_snapshot).unwrap(); assert_eq!( r.applied, ["2026_09_01_00_a", "2026_09_02_00_b"], "manifest order is application order" ); assert_eq!(*store.ran.borrow(), ["2026_09_01_00_a", "2026_09_02_00_b"]); let again = apply_pending(&store, &list, d.path(), &no_snapshot).unwrap(); assert!(again.applied.is_empty(), "never applied twice"); assert!(status(&store, &list) .unwrap() .iter() .all(|i| i.status == Status::Applied)); } #[test] fn a_failure_stops_the_batch_and_is_remembered() { let (d, list) = setup(&[ ("world", "m1", "SELECT 1;"), ("world", "m2", "BROKEN;"), ("world", "m3", "SELECT 3;"), ]); let store = Mem { fail_on: Some("m2"), ..Default::default() }; let r = apply_pending(&store, &list, d.path(), &no_snapshot).unwrap(); assert_eq!(r.applied, ["m1"]); assert_eq!(r.failed.as_ref().unwrap().0, "m2"); assert_eq!( *store.ran.borrow(), ["m1"], "m3 must not run after m2 failed" ); let st = status(&store, &list).unwrap(); assert_eq!( st.iter().map(|i| i.status).collect::>(), [Status::Applied, Status::Failed, Status::Pending] ); assert!(st[1].error.as_deref().unwrap().contains("syntax error")); } #[test] fn destructive_migrations_force_a_backup_first_and_a_failed_backup_blocks_everything() { let (d, list) = setup(&[( "characters", "d1", "-- cleanup\nDELETE FROM old_stuff WHERE 1;", )]); let store = Mem::default(); let r = apply_pending(&store, &list, d.path(), &|| Ok("backup-1".into())).unwrap(); assert_eq!(r.snapshot.as_deref(), Some("backup-1")); assert_eq!(r.applied, ["d1"]); let store = Mem::default(); let e = apply_pending(&store, &list, d.path(), &|| { Err(Error::Invalid("disk full".into())) }) .unwrap_err(); assert!(e.to_string().contains("safety backup failed")); assert!( store.ran.borrow().is_empty(), "nothing ran without a backup" ); } #[test] fn tampered_or_missing_files_are_refused_before_anything_runs() { let (d, mut list) = setup(&[("world", "t1", "SELECT 1;"), ("world", "t2", "SELECT 2;")]); list[1].sha256 = "0".repeat(64); let store = Mem::default(); assert!(matches!( apply_pending(&store, &list, d.path(), &no_snapshot), Err(Error::HashMismatch { .. }) )); assert!( store.ran.borrow().is_empty(), "t1 must not run when t2 is bad" ); std::fs::remove_file(d.path().join("world/t1.sql")).unwrap(); assert!(apply_pending(&store, &list[..1], d.path(), &no_snapshot).is_err()); } #[test] fn interrupted_sql_is_reported_and_never_automatically_replayed() { let (d, list) = setup(&[("world", "partial", "DROP TABLE valuable;")]); let store = Mem::default(); store.rows.borrow_mut().push(LedgerRow { db: "world".into(), id: "partial".into(), sha256: list[0].sha256.clone(), status: Status::Running, error: Some("interrupted".into()), baseline: false, }); assert_eq!(status(&store, &list).unwrap()[0].status, Status::Failed); assert!(apply_pending(&store, &list, d.path(), &no_snapshot) .unwrap_err() .to_string() .contains("interrupted")); assert!(store.ran.borrow().is_empty()); } #[test] fn baseline_marks_without_running_and_hostile_ids_are_rejected() { let (d, list) = setup(&[("world", "b1", "SELECT 1;")]); let store = Mem::default(); assert_eq!(baseline(&store, &list).unwrap(), 1); assert_eq!(baseline(&store, &list).unwrap(), 0); assert!(store.ran.borrow().is_empty()); assert!(status(&store, &list).unwrap()[0].baseline); let mut evil = list.clone(); evil[0].id = "../../x".into(); assert!(apply_pending(&Mem::default(), &evil, d.path(), &no_snapshot).is_err()); } #[test] fn destructive_detection_ignores_comments() { assert!(looks_destructive("ALTER TABLE t DROP COLUMN c;")); assert!(looks_destructive("truncate table t;")); assert!(!looks_destructive( "-- DROP TABLE nothing\nINSERT INTO t VALUES (1);" )); assert!(!looks_destructive("CREATE TABLE IF NOT EXISTS t (id INT);")); } }