What a pure embedded engine gets to skip

The reason pure embedded engines are simple is not that their authors were lazy; it is that cross-process coordination is genuinely hard to get right, and skipping it buys you an enormous amount of freedom. If only one process ever opens the file, then the page cache is always coherent because nothing outside the process can invalidate it, the WAL append order is the commit order because nobody else is appending, and every lock the engine takes can be a normal in-process mutex, which is fast, debuggable, and impossible to leave dangling after a crash. LMDB pays real money to escape part of this, with a shared memory-mapped lock table so many reader processes can coexist with one writer, and SQLite’s WAL mode does the same trick with its -shm shared-memory index, and both designs work, but both also inherit the failure modes of shared-memory concurrency: stale reader slots, processes that died holding a slot, recovery logic that has to run before anyone trusts the file again.

MongrelDB’s writer path assumes in-process coordination all the way down, from the group-commit sequencer that batches transactions under one WAL lock, to the per-table guards that let independent readers skip the writer lock, to the lock manager that tracks key and predicate conflicts inside a commit. Making all of that safe across processes would mean rebuilding it on top of shared memory or a lock file protocol, and the result would be a slower, stranger engine whose main new feature is “two processes can corrupt things in more interesting ways.” So the design decision was to keep the engine single-opener and let the kernel arbitrate that rule between cooperating processes, which is a weaker guarantee than a hard barrier and a much stronger one than a comment in the README, and the next section is about exactly how weak and how strong.

Two lock files and one syscall

When you call Database::open, the engine canonicalizes the path, hashes that canonical path, and opens a lock file named .mongreldb-<hash>.lock in the parent directory of the database root, so the lock sits next to the database directory rather than inside it and even Database::create on a path that does not exist yet can take the lock before writing a single byte, then takes an exclusive advisory lock on it through the fs2 crate, which is flock(2) on Unix and LockFileEx on Windows, so the same code path holds on every supported platform. A second exclusive lock lands on _meta/.lock inside the database root itself, which is the legacy lock that protects the durable root descriptor, and between the two files the open is pinned against both “another process opened the same canonical path” and “another process opened the same on-disk root through a different route.” The locks are advisory, which means they only stop cooperating openers, and that is exactly the right threat model here, because the enemy is the accidental second open, the overlapping deploy, the cron job that started before the app finished shutting down, not an attacker who is already in a position to flock your files, since that attacker can just read the bytes directly. The locks are also only as good as the filesystem underneath them, and flock is a local-filesystem contract whose semantics over NFS have historically ranged from “emulated through fcntl” to “silently per-client,” so the honest deployment rule is to keep the database root on local disk and treat a network mount as a way to lose the guarantee without an error message.

The failure is a typed error, MongrelError::DatabaseLocked, carrying the path and the underlying message, so application code can pattern-match on it instead of scraping an errno string, and the default behavior is fail-fast: one try_lock_exclusive call, no retry, no sleep, you find out immediately that someone else owns the database, which is the same default SQLite ships with and the same default you want in a service that would rather crash-loop visibly than queue behind a lock holder.

Same process, same file, still no

The cross-process lock says nothing about the case where your own process opens the same database twice, which happens more often than anyone admits, usually when two subsystems each decide they own database initialization and nobody notices until the second open in a test. MongrelDB keeps a process-wide open registry keyed on two things at once: the canonical path you asked for, and the file identity of the durable root, which is the device-and-inode pair the filesystem reports, so opening ./data and then opening a symlinked or bind-mounted alias that resolves to the same bytes still collides on the identity key even when the paths look different to string comparison. Either collision fails immediately with DatabaseLocked and a message that tells you the actual fix, which is to share the existing Arc<Database> instead of opening again, because the handle is designed to be shared and all of its internal concurrency is already sorted out.

This is one of those checks that costs nothing at runtime and saves an afternoon, because the alternative failure mode is two Database instances in one process, each with its own page cache and its own view of the WAL, discovering each other’s writes only through the filesystem, which is the kind of bug that passes CI and eats a weekend in production.

Waiting politely when you actually want to wait

Fail-fast is the right default for a service, but it is the wrong default for a batch job or a migration runner whose honest answer to “the database is busy” is “then wait a moment,” and for those callers the engine mirrors SQLite’s busy_timeout with OpenOptions::lock_timeout_ms:

use mongreldb_core::{Database, OpenOptions};

// A deploy-time migration runner that should wait out a rolling restart
// instead of dying the moment the old process still holds the lock.
let db = Database::open_with_options(
    "./data",
    OpenOptions::default().with_lock_timeout_ms(5_000),
)?;

With a non-zero timeout the open retries the exclusive lock on a backoff schedule that starts at 1ms, stretches to 10ms, then caps at 50ms per attempt, all bounded by a single deadline so the total elapsed time never exceeds your budget even if the lock holder releases at the tail of a sleep; the doc comment suggests 1,000 to 5,000ms for SQLite-style workloads, and that range is honest, because anything longer usually means the lock holder is stuck rather than busy. Two details make this nicer than the average retry loop: the engine counts lock waits and open failures in atomic counters that surface in the stats snapshot, so “how often do opens contend” is an observable number rather than a guess, and the cross-process test suite does not trust the engine to test itself, it spawns a subprocess that grabs a raw flock(2) on _meta/.lock while bypassing the engine entirely, which proves the behavior you see through Database::open is exactly the behavior the kernel enforces, with no bookkeeping in between that could drift.

The tradeoff, stated plainly

What you give up with a single-opener engine is the SQLite-WAL party trick, where a reporting process and an application process read the same file at the same time without talking to each other, and if your architecture depends on that shape, MongrelDB is telling you something you should listen to rather than work around. What you get back is a writer whose page cache is never invalidated underneath it, a WAL whose append order is the commit order with no shared-memory recovery dance, and a clean answer to the legitimate multi-process case, which is that mongreldb-server holds the lock and speaks HTTP to everyone else, so “two processes, one database” becomes “one process owns the storage, the rest are clients,” which is the shape you would have ended up at anyway once the second process needed auth, auditing, or a schema migration. The modern equivalent of the old “just open the file from both places” instinct is running the daemon next to the app and letting the client libraries do what client libraries do, and the lock file is what keeps the old instinct from silently winning the day someone acts on it.