Struct CoreWalSeam 

pub struct CoreWalSeam { /* private fields */ }

Real WAL seam backed by a live turso_core::Connection.

Implementations

impl CoreWalSeam

pub fn open(path: &str) -> Result<Self>

Open a writable connection at path and disable auto-checkpoint / auto-restart so the caller owns WAL maintenance. Requires turso_core with features = ["conn_raw_api"] (set in this crate’s Cargo.toml).

This takes turso’s whole-file exclusive fcntl lock, so it is mutually exclusive with any other process holding the database open — including upstream C SQLite (measured: examples/foreign_checkpoint_probe.rs probes D and G). That is correct for the restore/apply direction, which owns the destination file outright, and wrong for reading a live source: use Self::open_reader there.

pub fn open_reader(path: &str) -> Result<Self>

R858-B18 — open a read-only connection at path, taking no whole-file lock. This is the constructor the backup direction wants: a backup is a reader, and it must not lock out the application whose database it is reading.

OpenFlags::ReadOnly is what buys that, per handle and with no process-wide effect. turso_core-0.7.2/io/unix.rs:67-72 takes the exclusive lock only when env::var(ENV_DISABLE_FILE_LOCK).is_err() && !flags.intersects(ReadOnly | NoLock); io_uring.rs:463 and windows.rs:305 carry the identical condition, so this is not a unix-only accident. The LIMBO_DISABLE_FILE_LOCK=1 escape hatch reaches the same no-lock state but does it for every open in the process, including the writable ones — never use it here.

Two things this does NOT give you

1. No shared locking protocol. Getting in without a lock is not coordination: a foreign checkpoint can still land mid-read. That is what SourceFingerprint validation is for, and why raw_consistent_copy_live pairs the two rather than shipping this flag alone — the flag alone converts “refuses to open” into “may return a torn image”, which is strictly worse.
2. No escape from turso’s process-global registry. Database::open_file_with_flags consults DATABASE_MANAGER, keyed by file id, before it looks at the flags (lib.rs:940), and hands back an already-open Database with its own flags discarded. So in a process that already holds a writable handle on this exact file, this call returns that writable handle — same as snapshot.rs’s upload_base_snapshot doc records. Cross-process (the headscale case) is unaffected: the registry is per-process.

pub fn from_conn(conn: Arc<Connection>) -> Self

Wrap an already-open connection. The caller is responsible for having called wal_auto_actions_disable() on it.

Trait Implementations

impl WalInsertSeam for CoreWalSeam

fn wal_insert_begin(&self) -> Result<()>

Open a write transaction with auto-checkpoint/restart suppressed so our monotonically-numbered inserts aren’t reshuffled mid-session.

fn wal_insert_frame(&self, frame_no: u64, frame: &[u8]) -> Result<()>

Insert frame (a 24-byte header + page_size bytes of page data) at position frame_no (1-based, must be exactly prev + 1 — gaps error). Identical content at an already-written position is a no-op (the engine compares and returns OK).

fn wal_insert_end(&self, force_commit: bool) -> Result<()>

Close the session. With force_commit = false (the restore default) the engine drops any frames after the last commit frame — automatic crash-consistency for a tail captured mid-transaction. force_commit = true commits even an uncommitted suffix; not used by restore.

impl WalSeam for CoreWalSeam

fn wal_state(&self) -> Result<Watermark>

Snapshot the WAL position (checkpoint seq + max_frame).

fn wal_get_frame(&self, frame_no: u64, buf: &mut [u8]) -> Result<FrameInfo>

Fetch frame frame_no (1-based) into buf (must be WAL_FRAME_HEADER_SIZE + page_size bytes). Returns the page number the frame applies to and the post-frame DB size (in pages) — non-zero db_size marks a commit frame.

fn wal_auto_actions_disable(&self)

Take WAL ownership: turn off both the auto-checkpoint and the auto-WAL-restart so our watermark stays meaningful across calls. The in-tree consumer (cli/sync_server.rs) makes the same move at startup.

impl WarmApplier for CoreWalSeam

fn trim_page_cache(&self, target_kb: i64) -> Result<()>

Resize the underlying page cache toward target_kb kilobytes. Best-effort in the sense that turso_core’s page cache only evicts pages that aren’t pinned/dirty — harmless here, since an applier only ever holds pages it just wrote and is about to hand off to the engine, not mid-query state.