Skip to content

armgit / codex

Public Imported from GitHub
0

Lightweight coding agent that runs in your terminal

Rust

Add an experimental command to migrate NFS databases to DELETE mode (#55975)

Dmitriy Kovalenko3c4c04b224b5
diff --git a/codex-rs/Cargo.lock b/codex-rs/Cargo.lock
index 8f34c3fd70..b00ef1baf3 100644
--- a/codex-rs/Cargo.lock
+++ b/codex-rs/Cargo.lock
@@ -2569,6 +2569,7 @@ dependencies = [
"insta",
"jsonwebtoken",
"libc",
+ "libsqlite3-sys",
"os_info",
"owo-colors",
"predicates",
diff --git a/codex-rs/cli/Cargo.toml b/codex-rs/cli/Cargo.toml
index 26dee62ece..cad79b2cb2 100644
--- a/codex-rs/cli/Cargo.toml
+++ b/codex-rs/cli/Cargo.toml
@@ -87,11 +87,13 @@ crossterm = { workspace = true, features = ["event-stream"] }
futures = { workspace = true }
http = { workspace = true }
libc = { workspace = true }
+libsqlite3-sys = { workspace = true }
os_info = { workspace = true }
owo-colors = { workspace = true }
regex-lite = { workspace = true }
serde = { workspace = true, features = ["derive"] }
serde_json = { workspace = true }
+sqlx = { workspace = true }
supports-color = { workspace = true }
sys-locale = { workspace = true }
tempfile = { workspace = true }
@@ -137,7 +139,6 @@ jsonwebtoken = { workspace = true }
predicates = { workspace = true }
pretty_assertions = { workspace = true }
sha2 = { workspace = true }
-sqlx = { workspace = true }
tar = { workspace = true }
tokio-tungstenite = { workspace = true }
vt100 = { workspace = true }
diff --git a/codex-rs/cli/src/main.rs b/codex-rs/cli/src/main.rs
index 67bb615f2a..b90a4210d3 100644
--- a/codex-rs/cli/src/main.rs
+++ b/codex-rs/cli/src/main.rs
@@ -71,6 +71,7 @@ mod exec_server_telemetry;
mod marketplace_cmd;
mod mcp_cmd;
mod mcp_login;
+mod migrate_nfs_db;
mod migrate_rollouts;
mod plugin_cmd;
mod queue_cmd;
@@ -219,6 +220,9 @@ enum Subcommand {
/// Inspect or migrate legacy local sessions to paginated thread history.
MigrateRollouts(migrate_rollouts::MigrateRolloutsCommand),
+ /// [experimental] Migrate configured SQLite databases to DELETE mode in place.
+ MigrateNfsDb(migrate_nfs_db::MigrateNfsDbCommand),
+
/// Unarchive a saved session by id or session name.
Unarchive(SessionArchiveCommand),
@@ -1601,6 +1605,19 @@ async fn cli_main(
)?;
migrate_rollouts::run(command, root_config_overrides).await?;
}
+ Some(Subcommand::MigrateNfsDb(command)) => {
+ reject_remote_mode_for_subcommand(
+ root_remote.as_deref(),
+ root_remote_auth_token_env.as_deref(),
+ "migrate-nfs-db",
+ )?;
+ migrate_nfs_db::run(
+ command,
+ root_config_overrides,
+ loader_overrides_for_profile(interactive.config_profile_v2.as_ref())?,
+ )
+ .await?;
+ }
Some(Subcommand::Unarchive(cmd)) => {
let output = run_session_archive_cli_command(
codex_tui::SessionArchiveAction::Unarchive,
@@ -1974,12 +1991,13 @@ fn profile_v2_for_subcommand<'a>(
| Subcommand::Unarchive(_)
| Subcommand::Fork(_)
| Subcommand::Mcp(_)
+ | Subcommand::MigrateNfsDb(_)
| Subcommand::Sandbox(_)
| Subcommand::Debug(DebugCommand {
subcommand: DebugSubcommand::PromptInput(_),
}) => Ok(Some(profile_v2)),
_ => anyhow::bail!(
- "--profile only applies to runtime commands and `codex mcp`: `codex`, `codex exec`, `codex review`, `codex resume`, `codex queue`, `codex archive`, `codex delete`, `codex unarchive`, `codex fork`, `codex mcp`, `codex sandbox`, and `codex debug prompt-input`."
+ "--profile only applies to runtime commands, `codex mcp`, and `codex migrate-nfs-db`: `codex`, `codex exec`, `codex review`, `codex resume`, `codex queue`, `codex archive`, `codex delete`, `codex unarchive`, `codex fork`, `codex mcp`, `codex migrate-nfs-db`, `codex sandbox`, and `codex debug prompt-input`."
),
}
}
@@ -2352,6 +2370,7 @@ fn unsupported_subcommand_name_for_strict_config(
Some(Subcommand::Mcp(_)) => Some("mcp"),
Some(Subcommand::Plugin(_)) => Some("plugin"),
Some(Subcommand::MigrateRollouts(_)) => Some("migrate-rollouts"),
+ Some(Subcommand::MigrateNfsDb(_)) => Some("migrate-nfs-db"),
#[cfg(any(target_os = "macos", target_os = "windows"))]
Some(Subcommand::App(_)) => Some("app"),
Some(Subcommand::Login(_)) => Some("login"),
diff --git a/codex-rs/cli/src/migrate_nfs_db.rs b/codex-rs/cli/src/migrate_nfs_db.rs
new file mode 100644
index 0000000000..254102d032
--- /dev/null
+++ b/codex-rs/cli/src/migrate_nfs_db.rs
@@ -0,0 +1,308 @@
+//! Convert configured databases to DELETE mode and keep their WAL originals in backup directories.
+//! Require confirmation before opening database files. All clients must remain stopped.
+//! Keep source descriptors open until SQLite closes. Do not checkpoint the WAL source.
+//! NFS must enforce POSIX locks across clients. Local descriptor checks cannot prove this.
+
+use anyhow::Context;
+use anyhow::ensure;
+use clap::Parser;
+use codex_config::LoaderOverrides;
+use codex_core::config::ConfigBuilder;
+use codex_utils_cli::CliConfigOverrides;
+use owo_colors::OwoColorize;
+use sqlx::ConnectOptions;
+use sqlx::Connection;
+use sqlx::SqliteConnection;
+use sqlx::sqlite::SqliteConnectOptions;
+use sqlx::sqlite::SqliteJournalMode;
+use sqlx::sqlite::SqliteLockingMode;
+use sqlx::sqlite::SqliteSynchronous;
+use std::fs::File;
+use std::io::ErrorKind;
+use std::io::Read;
+use std::io::Write;
+use std::path::Path;
+use std::path::PathBuf;
+use std::time::Duration;
+
+#[cfg(unix)]
+mod access;
+mod replacement;
+
+use replacement::Recovery;
+use replacement::Replacement;
+use replacement::regular_file_exists;
+
+#[derive(Debug, Parser)]
+#[command(
+ after_help = "Stop SQLite clients on every host and keep them stopped through cutover.\nThe NFS mount must support cross-client POSIX locks (no nolock/local_lock=all).\nThis command replaces configured databases in place and retains their WAL backups."
+)]
+pub(crate) struct MigrateNfsDbCommand {
+ /// Use a local directory with space for the database and WAL files.
+ /// The default is the system temporary directory.
+ #[arg(long, default_value_os_t = std::env::temp_dir())]
+ staging_dir: PathBuf,
+}
+
+pub(crate) async fn run(
+ command: MigrateNfsDbCommand,
+ config_overrides: CliConfigOverrides,
+ loader_overrides: LoaderOverrides,
+) -> anyhow::Result<()> {
+ ensure!(
+ cfg!(unix),
+ "migrate-nfs-db currently requires Unix filesystem locking and directory fsync"
+ );
+ let warning = "WARNING: This operation is unsafe under concurrency.";
+ if supports_color::on(supports_color::Stream::Stderr).is_some() {
+ eprintln!("{}", warning.red().bold());
+ } else {
+ eprintln!("{warning}");
+ }
+ eprintln!(
+ "Stop all Codex instances on every host that uses these databases.\nKeep them stopped until the migration completes successfully."
+ );
+ ensure!(
+ crate::confirm("Continue? [y/N]:")?,
+ "Migration cancelled. No databases were changed."
+ );
+ let config = ConfigBuilder::default()
+ .cli_overrides(
+ config_overrides
+ .parse_overrides()
+ .map_err(anyhow::Error::msg)?,
+ )
+ .loader_overrides(loader_overrides)
+ .build()
+ .await?;
+ // Check the merged config for an explicit log directory.
+ let effective_config = config.config_layer_stack.effective_config();
+ let skip_logs = effective_config.get("log_dir").is_some();
+ let sqlite = config.sqlite_config();
+ if !sqlite.home().try_exists()? {
+ println!("No databases found.");
+ return Ok(());
+ }
+ // Keep this file after release. Removing it lets two migrations lock different inodes.
+ let migration_lock = std::fs::OpenOptions::new()
+ .read(true)
+ .write(true)
+ .create(true)
+ .truncate(false)
+ .open(sqlite.home().join(".codex-nfs-migration.lock"))?;
+ migration_lock
+ .try_lock()
+ .context("another database migration is running")?;
+ for database in sqlite.runtime_db_paths() {
+ if skip_logs && database.path == sqlite.logs_db_path() {
+ println!("Skipped logs database: log_dir is configured.");
+ continue;
+ }
+ migrate(&database.path, &command.staging_dir).await.with_context(|| format!(
+ "migration failed for {}. Keep all Codex instances stopped. Correct the error and rerun codex migrate-nfs-db",
+ database.path.display()
+ ))?;
+ }
+ println!("Migration completed successfully. You can restart Codex.");
+ Ok(())
+}
+
+#[expect(
+ clippy::disallowed_methods,
+ reason = "Migration needs dedicated exclusive connections, not the runtime's WAL pool"
+)]
+async fn migrate(source: &Path, staging_dir: &Path) -> anyhow::Result<()> {
+ let replacement = Replacement::new(source)?;
+ if let Recovery::Installed = replacement.resume().await? {
+ println!(
+ "Migrated database: {}\nWAL backup: {}",
+ source.display(),
+ replacement.backup_directory.display()
+ );
+ return Ok(());
+ }
+ let exists = regular_file_exists(source)?;
+ for suffix in ["-wal", "-shm", "-journal"] {
+ let mut path = source.as_os_str().to_owned();
+ path.push(suffix);
+ let sidecar_exists = regular_file_exists(Path::new(&path))?;
+ ensure!(
+ exists || !sidecar_exists,
+ "database is missing but a SQLite sidecar exists"
+ );
+ }
+ if !exists {
+ return Ok(());
+ }
+ let source_file = File::open(source)?;
+ #[cfg(unix)]
+ access::require_private_database(&source_file)?;
+ // The private directory protects WAL contents even on a shared /tmp.
+ let staging = tempfile::Builder::new()
+ .prefix("codex-nfs-migration-")
+ .tempdir_in(staging_dir)
+ .context("cannot create local staging directory")?;
+ let staged_database = staging.path().join("database.sqlite");
+ let options = SqliteConnectOptions::new()
+ .filename(source)
+ // Set this mode before SQLite first accesses the WAL.
+ // SQLite then locks the database file without shared memory across NFS client kernels.
+ .locking_mode(SqliteLockingMode::Exclusive)
+ .synchronous(SqliteSynchronous::Full)
+ .busy_timeout(Duration::ZERO)
+ .disable_statement_logging();
+ let mut connection = SqliteConnection::connect_with(&options).await.context(
+ "cannot open source database exclusively; close its SQLite clients on all hosts",
+ )?;
+
+ // Closing any descriptor for an inode can release this process's POSIX record locks
+ // for that inode.
+ // Keep both source files open until SQLite closes its connection, including after an error.
+ let mut source_files = vec![source_file];
+ let result: anyhow::Result<bool> = async {
+ {
+ let mut handle = connection.lock_handle().await?;
+ // SAFETY: SQLx's guard prevents its worker from accessing this open connection.
+ // This db_config option accepts an int and an optional output pointer to an int.
+ let status = unsafe {
+ libsqlite3_sys::sqlite3_db_config(
+ handle.as_raw_handle().as_ptr(),
+ libsqlite3_sys::SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE,
+ /*onoff*/ 1,
+ std::ptr::null_mut::<i32>(),
+ )
+ };
+ ensure!(
+ status == libsqlite3_sys::SQLITE_OK,
+ "cannot disable source checkpoint on close: {status}"
+ );
+ }
+ let mode: String = sqlx::query_scalar("PRAGMA journal_mode")
+ .fetch_one(&mut connection)
+ .await
+ .context(
+ "cannot access source database exclusively; close its SQLite clients on all hosts",
+ )?;
+ if mode == "delete" {
+ ensure!(
+ !regular_file_exists(&replacement.replacement_path())?,
+ "unfinished backup exists"
+ );
+ println!("Already in DELETE mode: {}", source.display());
+ return Ok(false);
+ }
+ ensure!(
+ mode == "wal",
+ "source database must be in WAL mode (found {mode})"
+ );
+ // BEGIN EXCLUSIVE alone blocks only WAL writers. EXCLUSIVE locking_mode also blocks readers.
+ // The mode keeps the database lock after ROLLBACK.
+ sqlx::raw_sql("BEGIN EXCLUSIVE; ROLLBACK;")
+ .execute(&mut connection)
+ .await
+ .context(
+ "cannot lock source database exclusively; close its SQLite clients on all hosts",
+ )?;
+
+ let mut wal_path = source.as_os_str().to_owned();
+ wal_path.push("-wal");
+ match File::open(wal_path) {
+ Ok(file) => source_files.push(file),
+ Err(error) if error.kind() == ErrorKind::NotFound => {}
+ Err(error) => return Err(error).context("cannot open source WAL"),
+ }
+ for (file, name) in source_files
+ .iter_mut()
+ .zip(["database.sqlite", "database.sqlite-wal"])
+ {
+ let mut target = File::create(staging.path().join(name))?;
+ copy_buffered(file, &mut target).context("cannot stage source database and WAL")?;
+ }
+ let mut copy = SqliteConnection::connect_with(
+ &SqliteConnectOptions::new()
+ .filename(&staged_database)
+ .locking_mode(SqliteLockingMode::Exclusive)
+ .journal_mode(SqliteJournalMode::Delete)
+ .synchronous(SqliteSynchronous::Full)
+ .disable_statement_logging(),
+ )
+ .await
+ .context("cannot convert staged database to DELETE")?;
+ let validated = validate_delete_database(&mut copy)
+ .await
+ .context("staged database failed validation");
+ let closed = copy.close().await;
+ validated?;
+ closed?;
+
+ replacement.prepare_backup_directory()?;
+ let mut temporary = tempfile::NamedTempFile::new_in(&replacement.backup_directory)?;
+ copy_buffered(&mut File::open(&staged_database)?, temporary.as_file_mut())
+ .context("cannot write replacement copy")?;
+ // Use the open handle. Closing another source descriptor can release SQLite's locks.
+ temporary
+ .as_file()
+ .set_permissions(source_files[0].metadata()?.permissions())?;
+ #[cfg(unix)]
+ access::require_private_database(temporary.as_file())?;
+ temporary.as_file().sync_all()?;
+ temporary
+ .into_temp_path()
+ .persist_noclobber(replacement.replacement_path())
+ .context("cannot save replacement copy")?;
+ File::open(&replacement.backup_directory)?.sync_all()?;
+ for file in &source_files {
+ file.sync_all()?;
+ }
+ replacement.move_original_to_backup()?;
+ Ok(true)
+ }
+ .await;
+ let closed = connection.close().await;
+ drop(source_files);
+ let changed = result?;
+ closed.context("cannot close source database. Keep clients stopped")?;
+ if changed {
+ replacement.install()?;
+ println!(
+ "Migrated database: {}\nWAL backup: {}",
+ source.display(),
+ replacement.backup_directory.display()
+ );
+ }
+ Ok(())
+}
+
+async fn validate_delete_database(connection: &mut SqliteConnection) -> anyhow::Result<()> {
+ let mode: String = sqlx::query_scalar("PRAGMA journal_mode")
+ .fetch_one(&mut *connection)
+ .await?;
+ ensure!(
+ mode == "delete",
+ "database did not enter DELETE journal mode"
+ );
+ let integrity: String = sqlx::query_scalar("PRAGMA integrity_check(1)")
+ .fetch_one(connection)
+ .await
+ .context("database failed integrity check")?;
+ ensure!(
+ integrity == "ok",
+ "database failed integrity check: {integrity}"
+ );
+ Ok(())
+}
+
+fn copy_buffered(source: &mut File, destination: &mut File) -> std::io::Result<()> {
+ // Use large reads to avoid the fallback to small reads for copy_file_range on NFSv4.1.
+ let mut buffer = vec![0; 1024 * 1024];
+ loop {
+ let bytes = match source.read(&mut buffer) {
+ Err(error) if error.kind() == ErrorKind::Interrupted => continue,
+ result => result?,
+ };
+ if bytes == 0 {
+ return Ok(());
+ }
+ destination.write_all(&buffer[..bytes])?;
+ }
+}
diff --git a/codex-rs/cli/src/migrate_nfs_db/access.rs b/codex-rs/cli/src/migrate_nfs_db/access.rs
new file mode 100644
index 0000000000..46b57af080
--- /dev/null
+++ b/codex-rs/cli/src/migrate_nfs_db/access.rs
@@ -0,0 +1,133 @@
+//! Reject databases with access permissions that replacement cannot preserve.
+//! Accept only files owned by the current user with no group or other access.
+
+use anyhow::Context;
+use anyhow::ensure;
+use std::fs::File;
+use std::os::unix::fs::MetadataExt;
+
+pub(super) fn require_private_database(file: &File) -> anyhow::Result<()> {
+ let metadata = file.metadata()?;
+ // SAFETY: geteuid has no preconditions.
+ let user = unsafe { libc::geteuid() };
+ ensure!(
+ metadata.uid() == user,
+ "database must be owned by the current user"
+ );
+ ensure!(
+ metadata.mode() & 0o077 == 0,
+ "shared database access is not supported: group and other permissions must be absent"
+ );
+ check_acl(file).context("cannot verify private database access")
+}
+
+#[cfg(target_os = "linux")]
+fn check_acl(file: &File) -> anyhow::Result<()> {
+ use std::os::fd::AsRawFd;
+
+ // POSIX ACL grants are limited by the group mode bits checked above.
+ // NFSv4 named entries can grant access independently of those bits.
+ let mut buffer = vec![0u8; 65536];
+ // SAFETY: The descriptor is open. The name and writable buffer are valid for this call.
+ let size = unsafe {
+ libc::fgetxattr(
+ file.as_raw_fd(),
+ c"system.nfs4_acl".as_ptr(),
+ buffer.as_mut_ptr().cast(),
+ buffer.len(),
+ )
+ };
+ if size < 0 {
+ let error = std::io::Error::last_os_error();
+ return match error.raw_os_error() {
+ Some(libc::ENODATA | libc::EOPNOTSUPP) => Ok(()),
+ _ => Err(error.into()),
+ };
+ }
+ let mut bytes = &buffer[..size as usize];
+ let read_word = |bytes: &mut &[u8]| -> anyhow::Result<u32> {
+ let (word, rest) = bytes
+ .split_at_checked(/*mid*/ 4)
+ .context("invalid NFSv4 ACL")?;
+ *bytes = rest;
+ Ok(u32::from_be_bytes(word.try_into()?))
+ };
+ let entries = read_word(&mut bytes)?;
+ for _ in 0..entries {
+ let kind = read_word(&mut bytes)?;
+ let _flags = read_word(&mut bytes)?;
+ let permissions = read_word(&mut bytes)?;
+ let length = read_word(&mut bytes)? as usize;
+ let (name, rest) = bytes
+ .split_at_checked(length)
+ .context("invalid NFSv4 ACL")?;
+ ensure!(
+ matches!(name, b"OWNER@" | b"GROUP@" | b"EVERYONE@"),
+ "databases with named NFSv4 ACL entries are not supported"
+ );
+ ensure!(kind <= 1, "unsupported NFSv4 ACL entry type");
+ // Other users can read attributes and ACLs, and synchronize. Reject all other grants.
+ const READ_ATTRIBUTES: u32 = 0x80;
+ const READ_ACL: u32 = 0x20000;
+ const SYNCHRONIZE: u32 = 0x100000;
+ ensure!(
+ kind != 0
+ || name == b"OWNER@"
+ || permissions & !(READ_ATTRIBUTES | READ_ACL | SYNCHRONIZE) == 0,
+ "shared database access through an NFSv4 ACL is not supported"
+ );
+ bytes = rest
+ .get((4 - length % 4) % 4..)
+ .context("invalid NFSv4 ACL padding")?;
+ }
+ ensure!(bytes.is_empty(), "invalid NFSv4 ACL trailing data");
+ Ok(())
+}
+
+#[cfg(target_os = "macos")]
+fn check_acl(file: &File) -> anyhow::Result<()> {
+ use std::ffi::c_void;
+ use std::os::fd::AsRawFd;
+
+ unsafe extern "C" {
+ fn acl_get_fd(fd: libc::c_int) -> *mut c_void;
+ fn acl_get_entry(
+ acl: *mut c_void,
+ entry_id: libc::c_int,
+ entry: *mut *mut c_void,
+ ) -> libc::c_int;
+ fn acl_free(acl: *mut c_void) -> libc::c_int;
+ }
+ // SAFETY: The descriptor is open. The returned ACL remains valid until acl_free.
+ let acl = unsafe { acl_get_fd(file.as_raw_fd()) };
+ if acl.is_null() {
+ let error = std::io::Error::last_os_error();
+ return match error.raw_os_error() {
+ // ENOENT means the open file has no extended ACL.
+ Some(libc::ENOENT | libc::ENOTSUP) => Ok(()),
+ _ => Err(error.into()),
+ };
+ }
+ let mut entry = std::ptr::null_mut();
+ // SAFETY: The ACL and output pointer are valid. Zero selects ACL_FIRST_ENTRY on macOS.
+ let status = unsafe {
+ acl_get_entry(acl, /*entry_id*/ 0, &mut entry)
+ };
+ let error = std::io::Error::last_os_error();
+ // SAFETY: This call releases the ACL returned by acl_get_fd exactly once.
+ unsafe { acl_free(acl) };
+ ensure!(
+ status != 0,
+ "databases with extended macOS ACLs are not supported"
+ );
+ ensure!(
+ error.raw_os_error() == Some(libc::EINVAL),
+ "cannot read database ACL: {error}"
+ );
+ Ok(())
+}
+
+#[cfg(not(any(target_os = "linux", target_os = "macos")))]
+fn check_acl(_file: &File) -> anyhow::Result<()> {
+ anyhow::bail!("database ACL checks are not supported on this operating system")
+}
diff --git a/codex-rs/cli/src/migrate_nfs_db/replacement.rs b/codex-rs/cli/src/migrate_nfs_db/replacement.rs
new file mode 100644
index 0000000000..09c3b71f6f
--- /dev/null
+++ b/codex-rs/cli/src/migrate_nfs_db/replacement.rs
@@ -0,0 +1,252 @@
+//! Move the WAL files into a backup directory, then install the validated DELETE copy.
+//! Resume an interrupted replacement from the files that remain on disk.
+//! All clients must remain stopped. The caller must hold the migration lock.
+//! Sync both directories after each step before changing more files.
+
+use anyhow::Context;
+use anyhow::ensure;
+use sqlx::ConnectOptions;
+use sqlx::Connection;
+use sqlx::SqliteConnection;
+use sqlx::sqlite::SqliteConnectOptions;
+use std::fs;
+use std::fs::File;
+use std::io::ErrorKind;
+use std::io::Write;
+use std::path::Path;
+use std::path::PathBuf;
+
+const MARKER: &[u8] = b"codex-nfs-migration-v1\n";
+const SIDECARS: [&str; 3] = ["-wal", "-shm", "-journal"];
+
+pub(super) enum Recovery {
+ // The caller must check and lock the source before starting a new replacement.
+ InspectSource,
+ // Recovery installed the saved copy. No new replacement is necessary.
+ Installed,
+}
+
+pub(super) struct Replacement {
+ source: PathBuf,
+ pub(super) backup_directory: PathBuf,
+ backup_database: PathBuf,
+}
+
+impl Replacement {
+ pub(super) fn new(source: &Path) -> anyhow::Result<Self> {
+ let name = source.file_name().context("database needs a file name")?;
+ let mut directory = source.as_os_str().to_owned();
+ directory.push("_wal_migration_backup");
+ let directory = PathBuf::from(directory);
+ Ok(Self {
+ source: source.to_path_buf(),
+ backup_database: directory.join(name),
+ backup_directory: directory,
+ })
+ }
+
+ pub(super) fn replacement_path(&self) -> PathBuf {
+ self.backup_directory.join("delete.sqlite")
+ }
+
+ // Call only while the original database is locked. Rebuild an unused copy on every attempt.
+ pub(super) fn prepare_backup_directory(&self) -> anyhow::Result<()> {
+ if self.backup_directory.try_exists()? {
+ ensure!(
+ !regular_file_exists(&self.backup_database)?,
+ "WAL backup already exists"
+ );
+ if regular_file_exists(&self.replacement_path())? {
+ fs::remove_file(self.replacement_path())?;
+ }
+ } else {
+ let builder = fs::DirBuilder::new();
+ #[cfg(unix)]
+ let builder = {
+ use std::os::unix::fs::DirBuilderExt;
+ let mut builder = builder;
+ builder.mode(0o700);
+ builder
+ };
+ builder.create(&self.backup_directory)?;
+ let mut marker = File::create_new(self.backup_directory.join("migration-v1"))?;
+ marker.write_all(MARKER)?;
+ marker.sync_all()?;
+ }
+ self.sync_directories()
+ }
+
+ pub(super) fn move_original_to_backup(&self) -> anyhow::Result<()> {
+ ensure!(
+ !regular_file_exists(&self.backup_database)?,
+ "WAL backup already exists"
+ );
+ // Move the main file first. An incomplete switch must not look like an intact source.
+ fs::rename(&self.source, &self.backup_database)?;
+ self.sync_directories()?;
+ self.move_sidecars_to_backup()
+ }
+
+ fn move_sidecars_to_backup(&self) -> anyhow::Result<()> {
+ for suffix in SIDECARS {
+ let source = with_suffix(&self.source, suffix);
+ let destination = with_suffix(&self.backup_database, suffix);
+ if regular_file_exists(&source)? {
+ ensure!(
+ !regular_file_exists(&destination)?,
+ "backup sidecar already exists: {}",
+ destination.display()
+ );
+ fs::rename(source, destination)?;
+ }
+ }
+ self.sync_directories()
+ }
+
+ pub(super) fn install(&self) -> anyhow::Result<()> {
+ for suffix in ["", "-wal", "-shm", "-journal"] {
+ ensure!(
+ !regular_file_exists(&with_suffix(&self.source, suffix))?,
+ "database or sidecar already exists at the installation path"
+ );
+ }
+ // A hard link installs the file atomically without replacing an unexpected database.
+ fs::hard_link(self.replacement_path(), &self.source)?;
+ self.finish_installation()
+ }
+
+ fn finish_installation(&self) -> anyhow::Result<()> {
+ self.sync_directories()?;
+ fs::remove_file(self.replacement_path())?;
+ self.sync_directories()
+ }
+
+ fn sync_directories(&self) -> anyhow::Result<()> {
+ File::open(&self.backup_directory)?.sync_all()?;
+ File::open(
+ self.source
+ .parent()
+ .context("database needs a parent directory")?,
+ )?
+ .sync_all()?;
+ Ok(())
+ }
+
+ #[expect(
+ clippy::disallowed_methods,
+ reason = "Inspect the prepared copy without runtime initialization"
+ )]
+ pub(super) async fn resume(&self) -> anyhow::Result<Recovery> {
+ match fs::symlink_metadata(&self.backup_directory) {
+ Err(error) if error.kind() == ErrorKind::NotFound => {
+ return Ok(Recovery::InspectSource);
+ }
+ Err(error) => return Err(error.into()),
+ Ok(metadata) => ensure!(
+ metadata.is_dir(),
+ "backup path already exists and is not a directory"
+ ),
+ }
+ let marker = self.backup_directory.join("migration-v1");
+ ensure!(
+ regular_file_exists(&marker)? && fs::read(&marker)? == MARKER,
+ "backup directory already exists without a valid migration marker: {}",
+ self.backup_directory.display()
+ );
+ let backup_exists = regular_file_exists(&self.backup_database)?;
+ let replacement_exists = regular_file_exists(&self.replacement_path())?;
+ let source_exists = regular_file_exists(&self.source)?;
+ #[cfg(unix)]
+ if backup_exists {
+ super::access::require_private_database(&File::open(&self.backup_database)?)?;
+ }
+ #[cfg(unix)]
+ if replacement_exists {
+ super::access::require_private_database(&File::open(self.replacement_path())?)?;
+ }
+ // No original files moved yet. The caller must lock the source and rebuild the copy.
+ if !backup_exists {
+ for suffix in SIDECARS {
+ ensure!(
+ !regular_file_exists(&with_suffix(&self.backup_database, suffix))?,
+ "backup has a SQLite sidecar without its original database"
+ );
+ }
+ ensure!(
+ source_exists,
+ "original database is missing from both source and backup"
+ );
+ return Ok(Recovery::InspectSource);
+ }
+ // Installation finished, or the replacement is missing. The caller must check the source.
+ if !replacement_exists {
+ ensure!(
+ source_exists,
+ "replacement is missing. Preserve the WAL backup and restore it before retrying"
+ );
+ return Ok(Recovery::InspectSource);
+ }
+ // An existing source must be the link installed before the interruption.
+ if source_exists {
+ let same_file = {
+ #[cfg(unix)]
+ {
+ use std::os::unix::fs::MetadataExt;
+ let source = fs::metadata(&self.source)?;
+ let prepared = fs::metadata(self.replacement_path())?;
+ (source.dev(), source.ino()) == (prepared.dev(), prepared.ino())
+ }
+ #[cfg(not(unix))]
+ {
+ false
+ }
+ };
+ ensure!(
+ same_file,
+ "another database already exists at the installation path"
+ );
+ self.finish_installation()?;
+ return Ok(Recovery::Installed);
+ }
+
+ // The original is in the backup. Check the replacement before installing it.
+ let mut copy = SqliteConnection::connect_with(
+ &SqliteConnectOptions::new()
+ .filename(self.replacement_path())
+ .read_only(true)
+ .immutable(true)
+ .disable_statement_logging(),
+ )
+ .await?;
+ let checked = super::validate_delete_database(&mut copy)
+ .await
+ .context("saved replacement failed validation");
+ let closed = copy.close().await;
+ checked?;
+ closed?;
+ self.move_sidecars_to_backup()?;
+ self.install()?;
+ Ok(Recovery::Installed)
+ }
+}
+
+pub(super) fn regular_file_exists(path: &Path) -> anyhow::Result<bool> {
+ match fs::symlink_metadata(path) {
+ Err(error) if error.kind() == ErrorKind::NotFound => Ok(false),
+ Err(error) => Err(error.into()),
+ Ok(metadata) => {
+ ensure!(
+ metadata.is_file(),
+ "path already exists and is not a regular file: {}",
+ path.display()
+ );
+ Ok(true)
+ }
+ }
+}
+
+fn with_suffix(path: &Path, suffix: &str) -> PathBuf {
+ let mut value = path.as_os_str().to_owned();
+ value.push(suffix);
+ value.into()
+}