One base class, five shapes of failure

Everything extends MongrelDBException, which extends \Exception, so a single catch at the boundary still works when you do not care about the specifics, and that is the entire hierarchy:

MongrelDBException
├── ConnectionException   // daemon unreachable, network error
├── AuthException         // 401 Unauthorized, 403 Forbidden
├── NotFoundException     // 404 Not Found
├── ConstraintException   // 409 Conflict
└── QueryException        // 400 Bad Request, 500 Internal Server Error

The mapping lives in one place, a match on the response status inside the client, and it is deliberately boring; 401 and 403 both become AuthException even though the fixes differ, a 401 means your credentials were rejected while a 403 means you authenticated fine and simply lack the grant, because from the caller’s side both are the same category of problem, an auth-layer failure you cannot retry past, and the message tells you which half of it you are looking at. Where the mapping gets opinionated is 404, which the client detects two ways: a 404 status maps to NotFoundException directly, and on top of that the client inspects the parsed error envelope for a not found: message prefix regardless of status, because “that table does not exist” deserves its own type even when the server phrases it inside a broader error envelope.

The one that carries real weight: ConstraintException

Most of the hierarchy is just names, but ConstraintException earns its existence by carrying two extra properties, errorCode and opIndex, and those two fields are what turn a batch failure from a mystery into a diff:

use Visorcraft\MongrelDB\Exceptions\ConstraintException;

try {
    $tx = $db->beginTransaction();
    $tx->insert('users', ['email' => 'ada@example.com', 'name' => 'Ada']);
    $tx->insert('users', ['email' => 'grace@example.com', 'name' => 'Grace']);
    $tx->insert('users', ['email' => 'ada@example.com', 'name' => 'Ada again']);
    $tx->commit();
} catch (ConstraintException $e) {
    // $e->errorCode === 'UNIQUE_VIOLATION'
    // $e->opIndex  === 2
    // the whole batch rolled back atomically
}

The errorCode is the server’s own string code, UNIQUE_VIOLATION, FK_VIOLATION, CHECK_VIOLATION, TRIGGER_VALIDATION, or the generic CONFLICT, and the opIndex tells you which operation inside the atomic batch tripped the constraint, zero-based, so when a forty-operation transaction fails you know exactly which insert to look at instead of bisecting your own code. Because the engine evaluates constraints at commit time and the batch is atomic, a ConstraintException also carries a guarantee you can build on: nothing partially applied, no cleanup pass, the database is exactly where it was before commit() was called, which is the property that makes retrying safe once you have fixed the offending row.

Why status-shaped exceptions beat a single DatabaseException

The old PHP database extensions trained a generation of us to check return values, mysql_query returned false and you called mysql_error() and hoped the string was parseable, and the PDO era improved that to a single exception class with a SQLSTATE code stuffed in getCode(), which meant every serious codebase grew its own switch statement mapping 23000 to “probably a duplicate key.” The shape of the failure was always there, it was just encoded in a place the type system could not see, so the compiler could not help you and your IDE could not autocomplete the recovery path. Putting the shape in the class name instead means catch (AuthException) is a complete sentence, it means a static analyzer with unchecked-exception tracking enabled can tell you that you handle constraint violations but not connection failures, and it means the retry policy for a transient ConnectionException never accidentally swallows a permanent QueryException, because those are different types and PHP’s catch semantics keep them apart for free.

There is a tradeoff worth naming, and it is that the hierarchy is shallow on purpose; the client does not try to give every server error code its own class, because a deep hierarchy is its own kind of failure, the kind where you version your exceptions and break everyone’s catch blocks on a minor release. Five leaves and one rich class is the line we picked, the wire stays the source of truth through errorCode for anything finer-grained, and if the daemon ever grows a genuinely new failure mode that callers must handle differently, that is a deliberate API change and not an accident of a new status string. That is the whole design: HTTP already classified the error, the client just refuses to throw the classification away on the way into PHP.

That choice has a consequence worth stating up front, which is that the HTTP surface is not an accident or a shim, it is the contract, the same one the PHP client, the Kit SDKs, and your own shell scripts all speak, so it is worth walking through what mongreldb-server actually exposes and why the surface is shaped the way it is.

The shape of the surface

The daemon is an axum router, and the routes fall into a few deliberate groups rather than one flat pile. The operational group is what your monitoring talks to: /health for liveness, /build-info for the exact version and build metadata, /capabilities for what this build supports, /metrics for Prometheus-style scraping, /audit for the audit log, and /history/retention for reading and setting retention policy. Admin operations sit under /admin/drain and /admin/reload, with cluster membership workflows under /admin/cluster/* when the binary is built with the cluster feature, and that grouping exists so your firewall rules and your reverse proxy ACLs can treat “is it alive” traffic and “reconfigure the server” traffic as different trust levels, because they are.

The data group is the part a client touches on every request, and it starts with the table primitives: GET and POST /tables to list and create, DELETE /tables/{name} to drop, POST /tables/{name}/put to write a row, GET /tables/{name}/count, and POST /tables/{name}/commit. On top of that sits the SQL surface, which is where most real work happens, a single POST /sql that takes a JSON body and returns a JSON result, plus POST /sql/continue for paged results, GET /queries/{query_id} for status on a running query, and POST /queries/{query_id}/cancel when you want it dead.

The /sql request is the contract

The request body for /sql is where the interesting engineering lives, because a single POST carrying a SQL string is what every toy HTTP database does, and the difference between a toy and a transport is everything else in the envelope:

{
  "sql": "UPDATE products SET price = price * 0.9 WHERE category = 'clearance'",
  "format": "json",
  "query_id": "q-7f3a2c",
  "timeout_ms": 5000,
  "max_output_rows": 10000,
  "max_output_bytes": 4194304,
  "idempotency_key": "import-run-42-batch-7"
}

Every field except sql is optional, and each one exists because a real failure mode demanded it. timeout_ms and the output limits mean a runaway statement dies on the server’s terms rather than streaming gigabytes into a client that stopped caring, the query_id ties the request to the /queries/{query_id}/cancel endpoint so an operator or a watchdog can kill it from a different connection entirely, and idempotency_key is the storage-layer dedupe we covered in an earlier post, so a retry after a network drop replays the receipt instead of re-executing the write, which is exactly the property a batch import like the one above needs. The format field is a different kind of knob, a per-request serialization choice rather than a guard: JSON is the default, but "arrow" returns Arrow IPC file bytes instead, which is the honest answer to “JSON text is slow” for the analytical case where you are moving real row volume, same endpoint, same auth, same query, different bytes on the wire.

Reads ride the same envelope, and a paged SELECT adds a pagination block to the request: page_size_rows bounds by count, max_page_bytes bounds by serialized size, and max_page_tokens bounds by an estimated token count the server computes as ceil(projected_json_bytes / 4), which is a crude heuristic and deliberately documented as one in the response itself, but crude and server-side beats every client inventing its own truncation logic after the damage is done.

Cursors that tell the truth

A paged response comes back with the page and a continuation:

{
  "status": "completed",
  "rows": [ /* up to page_size_rows row objects */ ],
  "next_cursor": "9f2c...",
  "page": {
    "offset": 0,
    "row_count": 500,
    "total_rows": 18342,
    "byte_count": 241118,
    "estimated_tokens": 60280,
    "expires_at_ms": 1786963200000,
    "snapshot": "retained_result",
    "token_estimate": "ceil(projected_json_bytes/4)"
  }
}

Yes, the server really ships the formula itself as a literal string in every paged response, and that is deliberate rather than redundant: any client reading estimated_tokens can see exactly how the number was produced without opening our docs, so nobody mistakes the estimate for a precise tokenizer count.

You pass next_cursor to POST /sql/continue and get the next page of the same retained result set, which matters because the snapshot is held server-side, so page two sees the same data page one saw even if writes landed in between. The cursor is HMAC-signed with a process-local key, and that detail is a deliberate tradeoff rather than an oversight: a tampered cursor is rejected instead of being treated as a query, and a server restart invalidates outstanding cursors, which means a client must be prepared to re-run the query after a failover. We could have made cursors durable across restarts, but that would mean persisting retained result sets or making cursors replayable queries with all the consistency questions that brings, and the honest contract is the simpler one: a cursor is a short-lived handle to a snapshot this process is holding for you, with an expires_at_ms that tells you exactly how short-lived, and when it is gone you start over.

Transactions, sessions, and the typed routes

Single-statement SQL is not the whole story, so POST /txn takes a batch of operations and applies them atomically, which is how the Kit layer implements its transaction commit and how any client can get all-or-nothing semantics over a transport that has no concept of a connection-held transaction. For callers that want the classic prepare-then-execute shape, the /sessions group provides it over HTTP: POST /sessions opens a session, POST /sessions/{id}/prepare registers a statement, POST /sessions/{id}/execute runs it with bound arguments, and DELETE on the statement or the session cleans up, so prepared-statement caching and parameter binding work the way you expect without the transport needing to keep a socket open per client.

The /kit/* group is the typed surface the SDKs prefer, routes like /kit/schema, /kit/txn, /kit/query, /kit/search, /kit/retrieve, /kit/ann_rerank, and /kit/set_similarity, and the distinction from raw /sql is that these carry structured, validated payloads rather than SQL text, so the engine can enforce constraints and column types at the boundary and the client never has to serialize a query string. Stored procedures and triggers get their own REST-shaped resources, /procedures and /triggers with list, create, describe, replace, drop, and call, which keeps the admin-y operations discoverable with nothing more exotic than an HTTP client. And for the replication story, GET /wal/stream, GET /replication/snapshot, and GET /events are the streaming edges, the places where HTTP’s request-response shape bends into a long-lived stream because change capture genuinely is a stream.

What HTTP costs, and what it buys

The costs are real and worth naming. Every request carries headers and JSON parsing that a binary framing would shrink, there is no server push outside the streaming endpoints, and keep-alive and connection reuse are your responsibility through whatever HTTP client you bring, which is why the PHP client’s persistent cURL sharing on 8.5+ matters as much as it does. The server meets you halfway on the abuse cases: a request-bytes bound rejects oversized bodies with a structured 413 rather than an OOM, and an optional concurrency limit sheds load instead of queueing until the wheels come off.

What it buys is everything you did not have to build. Auth is middleware with three modes, a bearer token, HTTP Basic verified against the Argon2id-hashed catalog users, or both, and TLS, rate limiting, and request logging come from whatever proxy you already run rather than from database-specific features somebody has to reimplement. Debugging is curl from any machine that can reach the port, load balancing is the same layer-7 infrastructure the rest of your stack uses, and a new language gets a working client the day somebody writes a hundred lines around its standard HTTP library, which is exactly how the long tail of MongrelDB language clients exists at all. The twenty-year view is that every database that invented a wire protocol also invented a driver maintenance burden it is still paying down, and the modern equivalent of the mysql_* extension problem is a proprietary protocol that only three of your twenty supported languages talk fluently; HTTP is not the fastest transport you can imagine, it is the fastest one you can already use from everywhere, and for an engine whose whole pitch is meeting you where your code runs, that is the right trade.

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.

The full, current package and repository matrix lives on the MongrelDB language clients page. This article is about why the matrix has two tiers instead of pretending every language should load the same native library.

Tier 1 keeps the engine in-process

Nine clients can run MongrelDB inside the application process: Rust, TypeScript and Node.js, Python, C, C++, C# and .NET, Java, Kotlin, and Scala. They reach the engine through one of the native boundaries already supported by their runtime:

• Rust calls the engine crates directly.
• Node.js uses NAPI and returns large identifiers as BigInt.
• Python uses its native extension path.
• C and C++ use the stable C ABI.
• C# and .NET bind the C ABI through their native interop layer.
• Java, Kotlin, and Scala use the JNI shim.

The reward is no HTTP serialization or socket hop, direct access to native query calls, and efficient Arrow IPC movement for columnar results. The cost is packaging: every supported OS and architecture needs the right native artifact or a documented source-build path, and a client release has to stay on the same compatibility train as the engine it embeds.

The Node addon currently publishes prebuilt Linux x64 and arm64 binaries. Other platforms build from source or use RemoteDatabase against the daemon. That caveat belongs next to the install command, not in a troubleshooting page discovered after npm install fails on a release machine.

Tier 2 keeps the language native

Twenty-six clients connect to a running mongreldb-server over HTTP: Clojure, Crystal, D, Dart, Elixir, Erlang, F#, Fortran, Gleam, Go, Julia, Kotlin/Native, Lua, Mojo, Nim, Objective-C, Odin, Perl, PHP, PowerShell, R, Ruby, Swift, Tcl, V, and Zig.

Those packages use the language’s ordinary HTTP and JSON stack, so installing the client does not pull in a Rust compiler, linker, JNI library, platform-specific DLL, or NAPI binary. The daemon owns the database root, keeps the engine warm, enforces sessions and credentials, and supports multiple client processes without asking them to coordinate exclusive filesystem locks.

The cost is real. A local HTTP query crosses request routing, authentication, SQL planning or typed endpoint dispatch, JSON or Arrow serialization, and the loopback network stack. The Stage 1 qualification on the published benchmark host measured a warm loopback SQL point query at 1.287 milliseconds p50, 2.070 milliseconds p95, and 2.396 milliseconds p99; the warm embedded begin/get/rollback path on the same class of evidence measured 1.037 microseconds p50 and 1.434 microseconds p95, though those paths do not perform identical work and should not be presented as a clean protocol-only ratio.

The lesson is smaller than the numbers: use the native boundary when per-call latency and in-process ownership matter, and use the daemon when installation, multi-process access, or language reach matters more.

One C ABI supports several runtimes

The mongreldb-ffi crate exposes opaque handles, typed values, queries, transactions, authentication, DataFusion SQL returning Arrow IPC, and migration planning through a C-compatible boundary. mongreldb-kit-ffi adds schema, migration-runner, and query-builder operations, while mongreldb-jni gives JVM languages a dedicated shim over the same engine behavior.

Opaque handles matter because Rust structs are not an ABI. A C header can remain stable while internal ownership, caches, schedulers, and index implementations change behind it; the binding holds a handle, calls a documented function, receives a documented result, and never depends on the byte layout of an Arc<Database>.

This is less glamorous than generating thirty-five clients from one schema, but it is the difference between a language list and a language contract.

The engine contract stays the same

Both tiers expose the same storage concepts: database, table, schema, typed values, transaction, condition, SQL, and maintenance. The exact convenience layer varies by language, and not every binding has a typed helper for every scored retrieval surface, but the underlying index families and durability model do not change because a caller moved from Rust to PHP.

Remote ranked AI queries use bounded scored endpoints so the server can enforce deadlines, maximum work, candidate ceilings, and concurrency. Embedded code can use direct native conditions where the trusted application owns those limits. This is one of the places where forcing byte-for-byte API symmetry would be worse than preserving the same result semantics with a safer remote boundary.

Choosing a boundary

Use embedded mode when one process can own the storage root, the application can ship the native artifact, and local-call latency matters. Use the daemon when several processes or languages need the same database, when the runtime’s native packaging story is worse than operating one local service, or when centralized authentication and resource limits are required.

A desktop application may embed the engine and inspect it with MongrelDB Viewer. A service fleet may run one authenticated daemon and use language-native HTTP clients. A Node product may embed during local development and use RemoteDatabase in a multi-process deployment. The storage model remains the same, but the ownership boundary changes, which is exactly what a client architecture should make explicit.

Current install names, package status, and repository links are maintained on the 35-language matrix, because counts change and an old article should not be the package registry.