From 49ce939ed7591eb551ef26d315764df9bca5158d Mon Sep 17 00:00:00 2001 From: ScriptedAlchemy Date: Mon, 16 Nov 2026 18:30:06 -0800 Subject: [PATCH] fix(rusqlite-runtime): admit stores left by an interrupted checkpoint A daemon killed while closing its stores can leave a main file mixing committed generations beside a WAL that no live connection maps. SQLite recovers that state from the WAL, but pin_initialized refused it: the immutable main-only view fails every statement, and a disconnected WAL recovers into a heap index that cannot prove SHM ownership. The daemon then crash-looped on "existing SQLite file has no valid database header". FinishInitialSchema stamps the registered application ID and must then checkpoint it into the main file, so that header proves the store was published and owns its sidecars. Read it through the inspection connection's VFS file and admit the store when its nonempty WAL completes the schema view. Unstamped files and stores with no recoverable WAL are still refused. Co-Authored-By: Claude Opus 5.5 --- .../src/connection/mod.rs | 76 +++++++++++++---- .../src/connection/tests.rs | 82 +++++++++++++++++++ 2 files changed, 143 insertions(+), 15 deletions(-) diff --git a/crates/tracedecay-rusqlite-runtime/src/connection/mod.rs b/crates/tracedecay-rusqlite-runtime/src/connection/mod.rs index 1ae3cfddf63..3b69eca7831 100644 --- a/crates/tracedecay-rusqlite-runtime/src/connection/mod.rs +++ b/crates/tracedecay-rusqlite-runtime/src/connection/mod.rs @@ -166,6 +166,13 @@ impl OpenedDatabaseFile { } _ => Ok(false), }; + // A published store owns its sidecars, so its WAL needs no shared + // index to prove ownership; it must still complete the schema view. + let published_wal_completes_view = |inspection: &Connection| { + Ok(main_header_declares_published_schema(inspection) + && sidecar("-wal")?.is_some_and(|wal| wal.is_file() && wal.len() > 0) + && live_wal_store_schema_reader(path).is_some()) + }; let initialized = match open_immutable_reader(path) { Ok(inspection) => { let initialized = match has_store_schema(&inspection) { @@ -174,6 +181,7 @@ impl OpenedDatabaseFile { // checkpoint can expose pages from different committed // generations in that main-only view, including a schema // object whose parent table is still only in the WAL. + Err(_) if published_wal_completes_view(&inspection)? => true, Err(_) if live_wal_is_initialized()? => true, Err(_) => return Err(OpenedDatabaseFileError::InvalidHeader), }; @@ -1226,28 +1234,66 @@ fn has_store_schema(connection: &Connection) -> rusqlite::Result { ) } +/// `FinishInitialSchema` stamps the registered application ID and must then +/// checkpoint it into the main file, so the main header alone proves the +/// schema was published. A process killed mid-checkpoint leaves a main file +/// mixing committed generations, and SQLite parses the schema before any +/// statement, even a header pragma. Read the header through the connection's +/// own VFS file instead: the WAL still holds every committed frame, and +/// SQLite's ordinary recovery restores them on the next writable open. +fn main_header_declares_published_schema(connection: &Connection) -> bool { + let mut file: *mut ffi::sqlite3_file = std::ptr::null_mut(); + let mut header = [0_u8; 100]; + // SAFETY: FILE_POINTER borrows the connection's open main file, which the + // live `connection` keeps valid for this call. `header` is writable + // storage of exactly the length passed to xRead. + let read = unsafe { + if ffi::sqlite3_file_control( + connection.handle(), + c"main".as_ptr(), + ffi::SQLITE_FCNTL_FILE_POINTER, + (&raw mut file).cast(), + ) != ffi::SQLITE_OK + { + return false; + } + let Some(read) = file + .as_ref() + .and_then(|file| file.pMethods.as_ref()) + .and_then(|methods| methods.xRead) + else { + return false; + }; + read(file, header.as_mut_ptr().cast(), header.len() as i32, 0) + }; + read == ffi::SQLITE_OK + && header.starts_with(b"SQLite format 3\0") + && header[68..72] == crate::schema_version::REGISTERED_STORE_APPLICATION_ID.to_be_bytes() +} + +/// A read transaction whose WAL-inclusive view holds the store schema. The +/// connection never checkpoints and never writes the SHM. +fn live_wal_store_schema_reader(path: &Path) -> Option { + let uri = read_only_uri(&sqlite_host_path(path), "readonly_shm=1").ok()?; + let flags = OpenFlags::SQLITE_OPEN_READ_ONLY + | OpenFlags::SQLITE_OPEN_URI + | OpenFlags::SQLITE_OPEN_PRIVATE_CACHE; + let connection = Connection::open_with_flags(uri, flags).ok()?; + connection + .set_db_config(DbConfig::SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE, true) + .ok()?; + connection.execute_batch("BEGIN").ok()?; + matches!(has_store_schema(&connection), Ok(true)).then_some(connection) +} + /// A legacy store's first schema commit can still be in its live WAL. /// Ask SQLite to read that commit using the existing shared index. A read-only /// VFS can also recover a disconnected WAL into a *heap* index, which cannot /// establish that the adjacent SHM belongs to this active database. fn live_wal_has_store_schema(path: &Path) -> bool { - let Ok(uri) = read_only_uri(&sqlite_host_path(path), "readonly_shm=1") else { - return false; - }; - let flags = OpenFlags::SQLITE_OPEN_READ_ONLY - | OpenFlags::SQLITE_OPEN_URI - | OpenFlags::SQLITE_OPEN_PRIVATE_CACHE; - let Ok(connection) = Connection::open_with_flags(uri, flags) else { + let Some(connection) = live_wal_store_schema_reader(path) else { return false; }; - if connection - .set_db_config(DbConfig::SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE, true) - .is_err() - || connection.execute_batch("BEGIN").is_err() - || !matches!(has_store_schema(&connection), Ok(true)) - { - return false; - } let mut file: *mut ffi::sqlite3_file = std::ptr::null_mut(); // SAFETY: the read transaction keeps the main file and mapped WAL index // live. FILE_POINTER borrows the connection's file; xShmMap inspects page diff --git a/crates/tracedecay-rusqlite-runtime/src/connection/tests.rs b/crates/tracedecay-rusqlite-runtime/src/connection/tests.rs index b300aa381f7..c803949f835 100644 --- a/crates/tracedecay-rusqlite-runtime/src/connection/tests.rs +++ b/crates/tracedecay-rusqlite-runtime/src/connection/tests.rs @@ -766,6 +766,88 @@ fn live_wal_recovers_an_inconsistent_immutable_checkpoint_view() { drop(writer); } +/// A process killed mid-checkpoint leaves a main file mixing committed +/// generations beside a WAL that no live connection maps. SQLite recovers that +/// state from the WAL, so a store whose main header proves the registered +/// schema was published must stay attachable. Without that stamp the same +/// files remain an ambiguous initialization and are still refused. +#[test] +fn crash_interrupted_checkpoint_of_a_published_store_remains_attachable() { + for published in [true, false] { + let directory = tempfile::tempdir().unwrap(); + let path = directory.path().join("sessions.db"); + let wal_path = sidecar_path(&path, "-wal"); + let shm_path = sidecar_path(&path, "-shm"); + let journal_path = sidecar_path(&path, "-journal"); + let writer = Connection::open(&path).unwrap(); + if published { + writer + .pragma_update( + None, + "application_id", + crate::schema_version::REGISTERED_STORE_APPLICATION_ID, + ) + .unwrap(); + } + writer + .execute_batch( + "PRAGMA journal_mode = WAL; + PRAGMA wal_checkpoint(TRUNCATE); + CREATE TABLE lcm_raw_messages(value INTEGER); + INSERT INTO lcm_raw_messages VALUES (42); + CREATE TRIGGER git_history_message_update + AFTER UPDATE ON lcm_raw_messages BEGIN SELECT 1; END;", + ) + .unwrap(); + let main_header = std::fs::read(&path).unwrap()[..100].to_vec(); + let wal = std::fs::read(&wal_path).unwrap(); + let shm = std::fs::read(&shm_path).unwrap(); + // Checkpoint a schema generation the WAL does not hold, so the + // main-only view has the trigger without its parent table. + writer + .execute_batch( + "PRAGMA writable_schema = ON; + DELETE FROM sqlite_schema WHERE type = 'table' AND name = 'lcm_raw_messages'; + PRAGMA writable_schema = OFF; + PRAGMA wal_checkpoint(TRUNCATE);", + ) + .unwrap(); + // The killed process held the only mapping of the WAL index. + drop(writer); + std::fs::write(&wal_path, wal).unwrap(); + std::fs::write(&shm_path, shm).unwrap(); + let mut main = std::fs::read(&path).unwrap(); + main[..100].copy_from_slice(&main_header); + std::fs::write(&path, main).unwrap(); + // Initialization leaves an empty rollback journal beside every store. + std::fs::write(&journal_path, b"").unwrap(); + + let opened = OpenedDatabaseFile::pin_initialized(&path); + if !published { + assert!( + matches!(opened, Err(OpenedDatabaseFileError::InvalidHeader)), + "an unstamped main with a disconnected WAL is still ambiguous" + ); + continue; + } + opened + .expect("the published header admits SQLite's own WAL recovery") + .release_after_workers_exit(); + let recovered = Connection::open(&path).unwrap(); + assert_eq!( + recovered.query_row("SELECT value FROM lcm_raw_messages", [], |row| { + row.get::<_, i64>(0) + }), + Ok(42), + "recovery restores every committed WAL frame" + ); + assert_eq!( + recovered.query_row("PRAGMA quick_check", [], |row| row.get::<_, String>(0)), + Ok("ok".to_owned()) + ); + } +} + #[test] fn create_new_refuses_to_replace_an_existing_database() { let file = NamedTempFile::new().unwrap();