Why the split usually happens

The conventional wisdom, which is correct for most projects, is that an embedded database and a server database serve different enough audiences that splitting the crate reduces complexity for each audience. SQLite is embedded-only; it runs in your process, touches your memory space, and the only IPC is the filesystem. PostgreSQL is server-only; it runs as a daemon, manages its own process tree, and the only way to talk to it is through the wire protocol. Both are extremely good at what they do, and part of the reason is that neither one carries the baggage of the other mode.

When you try to do both in one codebase, the pressure to split shows up in the storage layer first, because an embedded engine wants direct memory access to pages and a server engine wants a page cache that is isolated from client memory, and those are different interfaces even if the underlying page format is the same. Then the pressure moves to transactions: an embedded engine can use thread-local state for the current transaction, while a server needs a session-scoped transaction context that survives across requests. By the time you reach the query executor, you are passing around enough context objects that the embedded path is paying a tax it does not need, and the server path is calling through indirections that an embedded call would skip.

The seam we picked instead

The decision we made early was that the engine crate, the thing that owns pages, WAL, transactions, indexes, and the query executor, is mode-agnostic, and the mode is applied at the boundary by the caller. When you load MongrelDB as an embedded library, you call the engine directly through a Rust function interface, and the transaction context lives in your thread. When you run mongreldb-server, the same engine crate is linked into the daemon binary, but there is a session layer between the HTTP handler and the engine call, and that session layer is the only code that knows about connections, authentication, and wire serialization.

The seam is narrow on purpose. It is roughly 800 lines of Rust that translate between “an HTTP request arrived with a SQL body and a session cookie” and “call engine::execute(sql, tx_context) with the right transaction handle.” That translation layer is the entire server-specific code path; everything below it, from the parser down to the page cache, is shared without branching on mode.

// The engine trait that both modes call. No mode flag, no feature gate.
pub trait Engine {
    fn execute(&self, sql: &str, ctx: &TxContext) -> Result<ResultSet>;
    fn begin(&self, opts: TxOptions) -> Result<TxContext>;
    fn commit(&self, ctx: TxContext) -> Result<()>;
}

// Embedded: call directly on the concrete type. Monomorphized, no vtable.
let engine: MongrelDB = MongrelDB::open(path)?;
let tx = engine.begin(TxOptions::default())?;
let result = engine.execute("SELECT * FROM users WHERE id = 1", &tx)?;

// Server: the session layer holds the engine as dyn Engine behind a
// trait object, because the session does not know the concrete type;
// it only knows it has something that implements Engine.
async fn handle_sql(req: HttpRequest, engine: &dyn Engine) -> HttpResponse {
    let session = req.session();
    let tx = session.current_tx_or_begin(engine)?;
    // execute is blocking; the server wraps it in spawn_blocking so the
    // async runtime is not stalled while the query runs.
    let result = tokio::task::spawn_blocking(move || {
        engine.execute(&req.body(), &tx)
    }).await??;
    session.maybe_commit(tx)?;
    HttpResponse::json(result)
}

The embedded caller never touches the session layer, the session layer never touches the filesystem directly, and neither side has a feature flag that conditionally compiles the other side out. Both paths exist in the same binary, and the optimizer handles dead-code elimination if you link the crate as a library and never spin up the HTTP listener.

What this buys you in practice

The first thing it buys you is testability, because every test you write against the engine trait runs identically in embedded mode and in server mode, and the only difference is whether there is an HTTP round-trip in the middle. Cross-language conformance tests for Kit, the SDK layer, all hit the server endpoint, but the expected results are generated by the embedded engine running in the test harness, which means a mismatch between the two is a real bug, not a test artifact. This is the kind of thing that sounds like a nice-to-have until you have shipped a database where the embedded path and the server path disagree about, say, how NULL sorts in a composite index, and then it becomes the thing you wish you had built from day one.

The second thing it buys you is deployment flexibility, because the engine crate that the daemon binary links can also be linked as a library into a CLI tool, a test runner, or an edge function, with no recompilation and no feature flags. The MongrelDB CLI is the server binary with a different entry point; it loads the engine, runs a query, prints the result, and exits, without ever binding a socket. The migration runner in Kit does the same thing, because it needs to apply migrations to a database file that might be local or remote, and the difference is just whether the engine handle came from MongrelDB::open(path) or from MongrelDB::connect(url).

The cost, which is real

The cost is that the server path routes every engine call through a trait object, which means a vtable lookup on every query, while the embedded path calls the concrete type directly and monomorphizes to static dispatch with no indirection. In the server path, where you are doing thousands of point lookups per second across concurrent sessions, that indirection is measurable at roughly 2 to 3 nanoseconds per call on modern hardware, which is below the noise floor for anything except a synthetic benchmark but is there, and a server that inlined its dispatch would not pay it. We judged this acceptable because the query parser, planner, and executor dominate the cost of any non-trivial query, and the vtable indirection vanishes into the overhead of actual work; the embedded path, meanwhile, pays nothing because the compiler sees the concrete type and devirtualizes the call.

The second cost is that the engine crate has to be disciplined about not reaching for session-level concepts, because once the storage layer knows about sessions, the embedded path starts carrying server baggage. This is a code review constraint, not a runtime cost, but it is the kind of architectural discipline that erodes if you are not watching for it; every PR that tries to sneak a session reference into the engine module is a PR that needs to be pushed back on, and the pushback is worth it because the seam is the entire reason the design works.

The modern equivalent

In 2008 the equivalent decision was choosing between linking against libsqlite3 and running mysqld, and the two worlds did not overlap because the engineering cost of supporting both modes in one codebase was higher than the benefit, given the hardware and the languages available at the time. Rust changes the math, because trait objects, zero-cost abstractions, and a borrow checker that enforces lifetime discipline make it possible to share code across modes without the runtime cost that a C or C++ codebase would pay, and the result is a database that can be embedded in your application today and deployed as a server tomorrow without changing a line of application code. That is the goal, and so far the seam is holding.