The engine crates own WAL, MVCC, tables, indexes, transactions, compaction, backup, recovery, and DataFusion query execution. Embedded clients call those capabilities through native Rust, NAPI, Python, C ABI, or JNI surfaces. mongreldb-server links the same engine and adds sessions, credentials, HTTP or gRPC transport, resource ceilings, and multi-process ownership.

Embedded mode owns the root directly

A native application opens a database directory and the engine takes an exclusive lock on that storage core. Threads inside the process share the same Database; identity-specific handles can share one core through the database manager, but a second independent process cannot open the same root and hope filesystem locking will merge their transaction histories.

This is the right shape for desktop applications, local-first tools, edge jobs, test harnesses, and services where one process already owns the lifecycle. Calls avoid a transport hop, typed values stay native longer, and Arrow IPC can move columnar results without turning every cell into a JSON object.

The cost is application ownership. A process crash is also a database-process crash, native artifacts must ship for the target platform, blocking work must leave latency-sensitive runtime threads, and backup or maintenance has to respect the open handle.

Server mode centralizes ownership

mongreldb-server opens the root once and accepts multiple client processes. The typed Kit HTTP surface covers schema, transactions, query, scored retrieval, search, and maintenance. Native gRPC carries Protobuf control messages and Arrow IPC batches over HTTP/2 with TLS. A MySQL-compatible listener supports existing client workflows for the SQL surface.

The server boundary is where authentication, row and column policy, request deadlines, AI candidate ceilings, session limits, cancellation, and audit behavior become centralized instead of repeated in every application process. Language-native HTTP clients can stay pure Clojure, Go, PHP, Ruby, Swift, or Zig while one Rust daemon carries the engine.

The cost is the service itself. Somebody must start it, stop it, upgrade it, monitor it, provision TLS and credentials, and decide what happens when the process is unavailable. Local HTTP is simpler than a remote cluster, but it is still a network protocol and an operational component.

Shared semantics do not require identical APIs

Both modes use the same tables, RowIds, index families, transactions, and SQL planner, but the safest public surface can differ. Trusted embedded SQL may use a Boolean ANN predicate because the host application owns the work. Remote ranked queries use scored table functions and typed endpoints with deadlines and candidate ceilings so one request cannot turn an authenticated server into an unbounded vector worker.

Likewise, an embedded handle can preserve session-scoped views and prepared state for its lifetime, while a stateless HTTP route may create a fresh SQL session unless the server protocol explicitly associates requests with a durable session. The engine behavior is shared; connection lifetime is not.

Trying to hide those differences behind one magical interface would make the simple embedded path carry server concepts and the server path inherit unsafe local assumptions. The useful contract is same storage truth and query meaning, with an honest boundary around ownership and transport.

The latency evidence

The current qualification fixtures measure a warm embedded begin/get/rollback point path at 1.037 microseconds p50 and 1.434 microseconds p95 on the documented benchmark host. A warm loopback HTTP SQL point query measured 1.287 milliseconds p50, 2.070 milliseconds p95, and 2.396 milliseconds p99 in one current fixture.

Those are not a protocol microbenchmark over identical work. The HTTP result includes request handling, session lookup, SQL planning, and JSON serialization, while the embedded result is a native point operation. The numbers show the scale of the boundary, not a clean subtraction that assigns every extra microsecond to TCP.

A service doing one row per request will feel that boundary more than a service moving one Arrow batch or committing a useful transaction per request. Batching is not a workaround for a slow server; it is how a remote database protocol stops making transport overhead the unit of work.

Choose ownership before syntax

Embed when one process can own the root, native distribution is acceptable, and local-call latency matters. Run the server when many processes or languages need the same database, when centralized credentials and limits matter, or when native packaging is more expensive than one local daemon.

MongrelDB Viewer supports both boundaries. Direct mode embeds the official engine and takes the root lock; Server mode connects through the official client and leaves ownership with the daemon. The Viewer guide compares which maintenance operations are available through each path.

A project can start embedded and move to the daemon without converting the storage model, but application code still has to acknowledge that a function call became a request, that identities and failure modes changed, and that a remote result can time out after the server committed work. Same engine is a useful migration property. It is not permission to ignore the network.

Current deployment and client details live in the 35-language matrix and the engine README.md.