From 13474aca7db5a0ad81a8114daa0aa82a8c06203e Mon Sep 17 00:00:00 2001 From: Aditya Mukhopadhyay Date: Sat, 26 Sep 2026 13:00:59 +0530 Subject: [PATCH] fix(durability): fsync the parent directory after creating the .graph/WAL and deleting the WAL (#389) On POSIX a created or deleted file survives a power loss only once its parent directory is fsynced. Minigraf fsynced file contents but never a directory, so a power loss could lose a freshly created .graph or .wal, or resurrect a WAL that checkpoint() had deleted. Add storage::dir_sync::sync_parent_dir (open parent dir + sync_all on Unix; no-op elsewhere) and call it: - in FileBackend::open_with after writing the header of a new/empty file - in WalWriter::open_or_create after creating the WAL, and after re-initializing a headerless WAL left by a crash - in WalWriter::delete_file after a successful remove A test-only thread-local log records each sync and whether the child existed at that moment, so unit tests check both that the sync happens and that it follows the create/remove. Resurrected-WAL replay idempotence was already covered by tests/edge_cases_test.rs::test_stale_wal_after_checkpoint_is_idempotent. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01BedF9ZmqVZLkvDwn91fuKy --- CHANGELOG.md | 1 + CLAUDE.md | 3 +- README.md | 2 +- docs/TEST_COVERAGE.md | 4 +- src/storage/backend/file.rs | 54 ++++++++++++++- src/storage/dir_sync.rs | 126 ++++++++++++++++++++++++++++++++++ src/storage/mod.rs | 1 + src/wal.rs | 131 +++++++++++++++++++++++++++++++++++- 8 files changed, 315 insertions(+), 7 deletions(-) create mode 100644 src/storage/dir_sync.rs diff --git a/CHANGELOG.md b/CHANGELOG.md index d479cb9cab..1e4e2b955a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,6 +16,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Fixed +- **A power loss could lose a new database or WAL file, or bring back a deleted WAL (#389).** On Linux and other POSIX systems, a created or deleted file survives a power loss only once its parent directory is fsynced; Minigraf fsynced file contents but never a directory. Creating the `.graph` file or the `.wal` sidecar, and deleting the WAL after a checkpoint, now fsync the parent directory after the file operation. A resurrected WAL was already harmless, since replay skips entries at or below the last checkpointed transaction, but a lost `.graph` or WAL lost committed data. Windows needs no directory sync and is unchanged. Process kills were never affected, because they leave the OS page cache intact. - **Bound-entity queries could drop rows when one `WriteTransaction` wrote the same attribute in several valid-time windows (#323).** Both facts share a `tx_count`, and the selective lookup path de-duplicated on `(entity, attribute, tx_count, asserted)`, so one window's value was silently lost, while the same query via a full scan returned both. That de-duplication has been removed, and bound-entity queries now always match a full scan. ### Notes diff --git a/CLAUDE.md b/CLAUDE.md index ff620b95b0..b5c4609f4a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -111,6 +111,7 @@ cargo run < demos/demo_negation.txt - `btree_v6.rs`: On-disk B+tree (`build_btree`, `rebuild_btree_incremental`, `OnDiskIndexReader`, `MutexStorageBackend`) - `btree.rs`: Legacy v5 B+tree (migration only) - `cache.rs`: LRU page cache (`PageCache`, default 256 pages) + - `dir_sync.rs`: `sync_parent_dir` — fsyncs the parent directory after creating the `.graph`/WAL or deleting the WAL (no-op off Unix) - `packed_pages.rs`: Packed fact pages (~25 facts/4KB page), `MAX_FACT_BYTES` - `persistent_facts.rs`: `PersistentFactStorage` — v7 save/load, auto-migration v1–v6→v7 @@ -167,7 +168,7 @@ Auto-migrates v1/v2/v3/v4/v5/v6 → v7 on open/checkpoint. ## Test Coverage -**1190 tests passing** (1182 passing, 8 ignored; unit + integration + doc). +**1200 tests passing** (1192 passing, 8 ignored; unit + integration + doc). See `docs/TEST_COVERAGE.md` for the full per-file breakdown. **Testing conventions** — see the Testing Conventions section below before writing any tests. diff --git a/README.md b/README.md index aad4e86be5..17778e53b7 100644 --- a/README.md +++ b/README.md @@ -92,7 +92,7 @@ let r2 = pq.execute(&[("tx", BindValue::TxCount(2)), ("entity", BindValue::Entit ```bash cargo run # interactive Datalog REPL -cargo test # run 1190 tests +cargo test # run 1200 tests cargo run < demos/demo_recursive.txt # recursive rules demo ``` diff --git a/docs/TEST_COVERAGE.md b/docs/TEST_COVERAGE.md index 5850fcb4e5..605e313171 100644 --- a/docs/TEST_COVERAGE.md +++ b/docs/TEST_COVERAGE.md @@ -4,9 +4,9 @@ **Verified**: 2026-09-26 with `cargo test` -**Result**: 1,182 passing tests and 8 ignored tests (1,190 total) +**Result**: 1,192 passing tests and 8 ignored tests (1,200 total) -The v2.0.1 suite covers the public database API, the Datalog engine, storage and recovery paths, and the v2.0.0 locking and structured-error-code changes, plus v2.0.1's regression test for rebuilding indexes on open after several checkpoints (#370). Since v2.0.1, `tests/point_query_history_test.rs` and new storage unit tests check that attribute-narrowed bound-entity lookups return exactly what a full scan returns, and that `net_asserted_facts` matches its previous implementation on randomized histories (#323). Attribute-scan tests check that the AEVT range covers exactly the queried attribute, including non-ASCII names such as `:丿` and prefix siblings such as `:ab` for `:a` (#381). Incremental B+tree rebuild tests check that checkpoints which copy untouched index leaves produce exactly the entries and file checksum a full rebuild would, including over repeated checkpoints, that single-fact checkpoints do not fragment the index, and that a cyclic leaf chain or damaged slot directory is rejected rather than copied (#315). +The v2.0.1 suite covers the public database API, the Datalog engine, storage and recovery paths, and the v2.0.0 locking and structured-error-code changes, plus v2.0.1's regression test for rebuilding indexes on open after several checkpoints (#370). Since v2.0.1, `tests/point_query_history_test.rs` and new storage unit tests check that attribute-narrowed bound-entity lookups return exactly what a full scan returns, and that `net_asserted_facts` matches its previous implementation on randomized histories (#323). Attribute-scan tests check that the AEVT range covers exactly the queried attribute, including non-ASCII names such as `:丿` and prefix siblings such as `:ab` for `:a` (#381). Incremental B+tree rebuild tests check that checkpoints which copy untouched index leaves produce exactly the entries and file checksum a full rebuild would, including over repeated checkpoints, that single-fact checkpoints do not fragment the index, and that a cyclic leaf chain or damaged slot directory is rejected rather than copied (#315). Directory-sync unit tests check that creating the `.graph` file or the WAL, and deleting the WAL, fsync the parent directory after the file operation, and that reopening an existing file does not (#389). ### Covered Areas diff --git a/src/storage/backend/file.rs b/src/storage/backend/file.rs index 9db2a66199..f521ee292f 100644 --- a/src/storage/backend/file.rs +++ b/src/storage/backend/file.rs @@ -1,5 +1,6 @@ /// File-based storage backend for native platforms. use crate::error::{ErrorCode, bail_coded, err_coded}; +use crate::storage::dir_sync::sync_parent_dir; use crate::storage::{FileHeader, PAGE_SIZE, StorageBackend}; use anyhow::Result; use std::fs::{File, OpenOptions}; @@ -285,9 +286,14 @@ impl FileBackend { } } } else { - // New file or empty file: write initial header + // New file or empty file: write initial header, then make the + // file's directory entry durable. Without the directory sync a + // power loss can lose the whole file despite the header fsync + // (#389). An empty file left by a crash before this point takes + // this branch again on the next open, so the sync is repeated. let header = FileHeader::new(); Self::write_header(&mut file, &header)?; + sync_parent_dir(&path)?; header }; @@ -855,4 +861,50 @@ mod tests { "exactly one concurrent claimant should be admitted" ); } + + // ── #389: parent-directory fsync ──────────────────────────────────────── + + #[test] + fn test_create_syncs_parent_dir_after_header_write() { + use crate::storage::dir_sync::take_sync_log; + let dir = tempfile::tempdir().unwrap(); + let path = dir.path().join("new.graph"); + take_sync_log(); + + let backend = FileBackend::open(&path).unwrap(); + + let log = take_sync_log(); + assert_eq!( + log.len(), + 1, + "creating the file must sync its directory once" + ); + assert_eq!( + log[0].dir, + dir.path(), + "must sync the file's parent directory" + ); + assert!( + log[0].child_existed, + "directory sync must follow the create" + ); + drop(backend); + } + + #[test] + fn test_reopen_existing_does_not_sync_parent_dir() { + use crate::storage::dir_sync::take_sync_log; + let dir = tempfile::tempdir().unwrap(); + let path = dir.path().join("existing.graph"); + drop(FileBackend::open(&path).unwrap()); + take_sync_log(); + + let backend = FileBackend::open(&path).unwrap(); + + assert!( + take_sync_log().is_empty(), + "reopening an initialized file creates nothing, so needs no directory sync" + ); + drop(backend); + } } diff --git a/src/storage/dir_sync.rs b/src/storage/dir_sync.rs new file mode 100644 index 0000000000..21f9d8d9ce --- /dev/null +++ b/src/storage/dir_sync.rs @@ -0,0 +1,126 @@ +//! Parent-directory fsync (#389). +//! +//! On POSIX systems a newly created, deleted or renamed file survives a power +//! loss only once its parent directory has been fsynced: `fsync` on the file +//! itself makes the file's *contents* durable, not the directory entry that +//! names it. Without this, a power loss (not a process kill -- a kill leaves +//! the OS page cache intact) can lose a freshly created `.graph` or `.wal`, +//! or bring back a WAL that `checkpoint()` deleted. +//! +//! Durability order: +//! +//! - Create: create file → write + `sync_all` its first bytes → sync parent dir. +//! - Delete: remove file → sync parent dir. +//! +//! Windows needs no directory sync (NTFS journals directory metadata), and +//! cannot open a directory as a `File` without extra flags, so this is a no-op +//! there and on every other non-Unix target. + +use std::io; +use std::path::Path; + +/// Fsync the directory that contains `child`, making `child`'s creation or +/// removal durable. +/// +/// `child` is the path of the file that was just created or removed, not the +/// directory itself. A bare file name (no parent component) refers to the +/// current directory. +pub(crate) fn sync_parent_dir(child: &Path) -> io::Result<()> { + let dir = match child.parent() { + Some(p) if !p.as_os_str().is_empty() => p, + _ => Path::new("."), + }; + + #[cfg(test)] + record(dir, child); + + #[cfg(unix)] + std::fs::File::open(dir)?.sync_all()?; + #[cfg(not(unix))] + let _ = dir; + Ok(()) +} + +// ─── Test-only call log ───────────────────────────────────────────────────── +// +// A power loss cannot be simulated in a test, so tests instead check that the +// sync happens at all and in the right order relative to the file operation: +// each call records the directory and whether `child` existed at that moment. +// After a create it must exist; after a delete it must not. Thread-local, so +// concurrently running tests do not see each other's calls. + +#[cfg(test)] +thread_local! { + static SYNC_LOG: std::cell::RefCell> = + const { std::cell::RefCell::new(Vec::new()) }; +} + +/// One recorded `sync_parent_dir` call. +#[cfg(test)] +#[derive(Debug, Clone, PartialEq, Eq)] +pub(crate) struct DirSync { + /// The directory that was synced. + pub dir: std::path::PathBuf, + /// The file the sync was made on behalf of. + pub child: std::path::PathBuf, + /// Whether `child` existed when the directory was synced. + pub child_existed: bool, +} + +#[cfg(test)] +fn record(dir: &Path, child: &Path) { + SYNC_LOG.with(|log| { + log.borrow_mut().push(DirSync { + dir: dir.to_path_buf(), + child: child.to_path_buf(), + child_existed: child.exists(), + }) + }); +} + +/// Return and clear this thread's recorded directory syncs. +#[cfg(test)] +pub(crate) fn take_sync_log() -> Vec { + SYNC_LOG.with(|log| std::mem::take(&mut *log.borrow_mut())) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn test_syncs_parent_of_child() { + let dir = tempfile::tempdir().unwrap(); + let child = dir.path().join("a.graph"); + std::fs::write(&child, b"x").unwrap(); + take_sync_log(); + + sync_parent_dir(&child).unwrap(); + + let log = take_sync_log(); + assert_eq!(log.len(), 1, "expected exactly one directory sync"); + assert_eq!(log[0].dir, dir.path(), "must sync the child's parent"); + assert!(log[0].child_existed, "child existed at sync time"); + } + + #[test] + fn test_bare_file_name_syncs_current_dir() { + take_sync_log(); + sync_parent_dir(Path::new("no-such-file.graph")).unwrap(); + let log = take_sync_log(); + assert_eq!(log.len(), 1, "expected exactly one directory sync"); + assert_eq!(log[0].dir, Path::new("."), "bare name means current dir"); + assert!(!log[0].child_existed, "child does not exist"); + } + + #[cfg(unix)] + #[test] + fn test_missing_parent_dir_is_an_error() { + let dir = tempfile::tempdir().unwrap(); + let child = dir.path().join("gone").join("a.graph"); + assert!( + sync_parent_dir(&child).is_err(), + "a directory that cannot be opened must surface as an error" + ); + } +} diff --git a/src/storage/mod.rs b/src/storage/mod.rs index 3145504265..9a409e653f 100644 --- a/src/storage/mod.rs +++ b/src/storage/mod.rs @@ -9,6 +9,7 @@ pub mod backend; pub mod btree; pub mod btree_v6; pub mod cache; +pub(crate) mod dir_sync; pub mod index; pub mod packed_pages; pub mod persistent_facts; diff --git a/src/wal.rs b/src/wal.rs index 781bbf77a1..3c611c940a 100644 --- a/src/wal.rs +++ b/src/wal.rs @@ -22,6 +22,7 @@ use crate::db::SyncMode; use crate::error::{ErrorCode, bail_coded, err_coded}; use crate::graph::types::Fact; +use crate::storage::dir_sync::sync_parent_dir; use crate::storage::packed_pages::MAX_FACT_BYTES; use anyhow::Result; use std::fs::{File, OpenOptions}; @@ -148,6 +149,9 @@ impl WalWriter { { Ok(mut file) => { write_wal_header(&mut file)?; + // The header is durable; make the WAL's directory entry + // durable too, or a power loss can lose the whole file (#389). + sync_parent_dir(path)?; file.seek(SeekFrom::End(0))?; return Ok(WalWriter { file, sync_mode }); } @@ -162,7 +166,12 @@ impl WalWriter { // A previous crash landed between this file's creation and its // header write completing; no entry could have been appended // yet, so re-initialize it as a fresh, empty WAL. - WalHeaderState::Absent => write_wal_header(&mut file)?, + // The crash may also have preceded the directory sync that + // follows creation, so repeat it (#389). + WalHeaderState::Absent => { + write_wal_header(&mut file)?; + sync_parent_dir(path)?; + } } file.seek(SeekFrom::End(0))?; Ok(WalWriter { file, sync_mode }) @@ -192,6 +201,9 @@ impl WalWriter { /// Delete the WAL file at `path`. Called after a successful checkpoint. /// + /// Fsyncs the parent directory after the remove, so a power loss cannot + /// bring the deleted WAL back (#389). + /// /// Uses a short retry loop to tolerate Windows races where the OS file handle /// is not immediately released after the `WalWriter` is dropped. pub fn delete_file(path: &Path) -> Result<()> { @@ -200,7 +212,10 @@ impl WalWriter { let mut last_err = None; for i in 0..retries { match std::fs::remove_file(path) { - Ok(()) => return Ok(()), + Ok(()) => { + sync_parent_dir(path)?; + return Ok(()); + } Err(e) => { last_err = Some(e); if i.saturating_add(1) < retries { @@ -740,4 +755,116 @@ mod tests { std::fs::remove_dir(&path).unwrap(); } + + // ── #389: parent-directory fsync ──────────────────────────────────────── + + #[test] + fn test_wal_create_syncs_parent_dir_after_create() { + use crate::storage::dir_sync::take_sync_log; + let dir = tempfile::tempdir().unwrap(); + let path = dir.path().join("test.wal"); + take_sync_log(); + + let _writer = WalWriter::open_or_create(&path, SyncMode::Full).unwrap(); + + let log = take_sync_log(); + assert_eq!( + log.len(), + 1, + "creating the WAL must sync its directory once" + ); + assert_eq!( + log[0].dir, + dir.path(), + "must sync the WAL's parent directory" + ); + assert!( + log[0].child_existed, + "directory sync must follow the create" + ); + } + + #[test] + fn test_wal_reopen_existing_does_not_sync_parent_dir() { + use crate::storage::dir_sync::take_sync_log; + let dir = tempfile::tempdir().unwrap(); + let path = dir.path().join("test.wal"); + drop(WalWriter::open_or_create(&path, SyncMode::Full).unwrap()); + take_sync_log(); + + let _writer = WalWriter::open_or_create(&path, SyncMode::Full).unwrap(); + + assert!( + take_sync_log().is_empty(), + "reopening an intact WAL creates nothing, so needs no directory sync" + ); + } + + #[test] + fn test_wal_reinit_headerless_syncs_parent_dir() { + use crate::storage::dir_sync::take_sync_log; + let dir = tempfile::tempdir().unwrap(); + let path = dir.path().join("test.wal"); + // A crash between `create_new` and the header write leaves a short + // file whose directory entry may never have been synced either. + std::fs::write(&path, b"MW").unwrap(); + take_sync_log(); + + let _writer = WalWriter::open_or_create(&path, SyncMode::Full).unwrap(); + + let log = take_sync_log(); + assert_eq!( + log.len(), + 1, + "re-initializing the WAL must sync its directory" + ); + assert!( + log[0].child_existed, + "directory sync must follow the header write" + ); + } + + #[test] + fn test_wal_delete_syncs_parent_dir_after_remove() { + use crate::storage::dir_sync::take_sync_log; + let dir = tempfile::tempdir().unwrap(); + let path = dir.path().join("test.wal"); + drop(WalWriter::open_or_create(&path, SyncMode::Full).unwrap()); + take_sync_log(); + + WalWriter::delete_file(&path).unwrap(); + + let log = take_sync_log(); + assert_eq!( + log.len(), + 1, + "deleting the WAL must sync its directory once" + ); + assert_eq!( + log[0].dir, + dir.path(), + "must sync the WAL's parent directory" + ); + assert!( + !log[0].child_existed, + "directory sync must follow the remove" + ); + } + + #[test] + fn test_wal_failed_delete_does_not_sync_parent_dir() { + use crate::storage::dir_sync::take_sync_log; + let dir = tempfile::tempdir().unwrap(); + let path = dir.path().join("not-a-file.wal"); + std::fs::create_dir(&path).unwrap(); + take_sync_log(); + + assert!(WalWriter::delete_file(&path).is_err(), "delete must fail"); + assert!( + take_sync_log().is_empty(), + "nothing was removed, nothing to sync" + ); + + std::fs::remove_dir(&path).unwrap(); + } }