It reflects an architectural decision we made before writing the eighth client, and it has visible tradeoffs.

The two-tier model

MongrelDB clients come in two flavors:

1. Tier 1 (in-process native): the engine runs in your process. No daemon, no serialization, no network hop. You get the same sub-10µs single-row write path as the embedded Rust API itself.
2. Tier 2 (HTTP): a pure-language client connects to a running mongreldb-server over HTTP. There is one round-trip per query, in the low-millisecond range.

We have three Tier 1 entry points today: Rust (direct, native), Python (PyO3, via MongrelDB Kit), and TypeScript / Node (NAPI addon, via either Kit or crates/mongreldb-node). The other nine are Tier 2: PHP, Go, Java/Kotlin, C#/.NET, Ruby, Swift, Zig, D, and Nim.

This is not because we could not write native bindings for the other nine. It is because we chose not to.

Why two tiers exist

Twenty-five years of SQLite have produced one clear lesson: the embedded path beats the network path every time, when you have a choice. Native bindings for an embedded database are the better-sqlite3 model, and it is hard to argue with. We picked that model for Rust, TypeScript, and Python.

The other nine do not fit cleanly. The C toolchain story in each of them has, at best, one platform with first-class support and a long tail of platforms with rough edges:

• Ruby has gem build and Fiddle. Native extensions work on MRI/YARV, less cleanly on JRuby and TruffleRuby.
• PHP has PECL. PECL extensions work everywhere PHP installs, but every install means a separate Makefile, an phpize, and a php-config check. The pure-PHP client we shipped this month exists precisely because that build matrix is painful.
• Swift has SwiftPM on macOS. On Linux, the Swift toolchain is real but second-tier. The cost is per-platform build scripts.
• Java has JNI. JNI still works in 2026, but it is a generation-old API, and every JVM in the install path is another moving part.
• C# has P/Invoke. That part is fine. The complications come from cross-platform packaging, RID resolution, and what to do about self-contained versus framework-dependent deployments.
• Go, Zig, D, Nim all have C FFI stories that work, but each brings an extra build-time dependency on a Rust compiler or C toolchain that the language’s users did not sign up for.

Native bindings for those nine would mean nine more CI matrices, nine more sets of release artifacts, and a permanent maintenance cost on every engine change. We chose to ship pure-language HTTP clients instead, with a real latency tradeoff we will not pretend away.

What the HTTP tier looks like

A Tier 2 client speaks a JSON-over-HTTP protocol to mongreldb-server. The protocol mirrors the native API surface: writes land at PUT /tables/{name}/put (or batch through POST /kit/txn), hybrid queries at POST /kit/query. Encoding is plain UTF-8 JSON for most requests; binary values go over base64. It is not exotic.

Latency for a single-row write over HTTP on loopback is dominated by axum’s handler dispatch, JSON parse/serialize, and the TCP round trip, not the engine.

To put a number on it: on a release build over loopback HTTP, single-row PUT /tables/bench/put measured p50 ~0.22 ms, p99 ~0.62 ms, with ~4,000 ops/s sustained. Single-row commit was nearly identical, p50 ~0.21 ms, p99 ~0.53 ms. fsync is in the commit path but does not dominate on this hardware.

That is fine for most PHP, Ruby, Java, and Go workloads, where the unit of work is rarely one row. It is not fine for Python and Node code that wants the sub-10µs native path, which is exactly why Tier 1 exists for those two.

The C ABI and why it exists separately

The newest crate in the repository is mongreldb-ffi. It exposes a stable C ABI over the engine: a fixed set of extern "C" functions for opening a database, beginning a transaction, putting a row, committing, and a handful of query helpers. Public structs and enums are #[repr(C)]. Opaque handles (mongreldb_database_t, mongreldb_transaction_t) wrap Arc<Database> and friends so language runtimes can hold them by pointer.

It is not yet what the Tier 1 clients call into. Rust and PyO3 call into mongreldb-core directly. The NAPI addon also calls into mongreldb-core directly. The C ABI exists so that future Tier 1 clients can land on top of it.

Three reasons we did this:

1. Stability. A C ABI is a contract you can hold to across major versions of the engine. Rust API surfaces drift; the C ABI does not.
2. Reuse across FFI stacks. Swift (@_cdecl), Ruby (Fiddle on MRI), Go (cgo), Java (JNI), Zig (@cImport), Nim (direct C import), and every other language with a working C FFI all consume C headers. One crate, many targets.
3. Decoupling. The C ABI can change without the engine changing, and vice versa. That means we can ship and version the FFI surface independently of the engine, which we will need to do.

The current mongreldb-ffi is small on purpose. It exposes the minimum surface needed for an “open, write a few thousand rows, commit, query, close” workflow, plus error and panic-safety plumbing (mongreldb_last_error, mongreldb_last_error_code, mongreldb_free_error_string, free functions for every allocated handle). We will extend it as we add Tier 1 bindings for more languages.

Picking the right tier

If you are writing Rust, Python, or TypeScript / Node against MongrelDB, use the Tier 1 binding. You get in-process speed, no daemon to run, and the same mongreldb-core API surface used by our own server. The NAPI and PyO3 clients are not wrappers; they are first-class Rust compiled to a shared library and bound through standard FFI machinery. For Node specifically, the raw mongreldb-node NAPI addon (the better-sqlite3 model, cd crates/mongreldb-node && npm install && npm run build) is the lowest-overhead path. Kit wraps the same engine behind a typed object API if you would rather skip the build step.

If you are writing PHP, Go, Java/Kotlin, C#/.NET, Ruby, Swift, Zig, D, or Nim, use the Tier 2 HTTP client. Run mongreldb-server alongside your app (systemd, container, sidecar), point the client at it, and you get the same engine underneath with a network in the middle.

If your language is not on the list, the C ABI is the on-ramp. Either we already have a Tier 1 prototype and we can wire you up, or you can ship your own binding on top of mongreldb-ffi and we will help you land it on the org.

What we are shipping next

We will keep extending Tier 2 to languages where maintaining a pure-language HTTP client is the right call, including maintenance and small feature work on the eight new clients.

We have no specific Tier 1 language conversion committed. mongreldb-ffi is the on-ramp; what we land on top of it will be picked per language when the engineering case is clear.

Where to find each client

The wire protocol for Tier 2 is documented at docs/08-daemon. The C ABI surface lives in crates/mongreldb-ffi. For each client’s install command and examples, see its repository.

If you maintain a language we do not yet support, file an issue with the language name. The C ABI makes the answer shorter than it used to be. For the release announcement and install commands for the eight new HTTP clients, see the companion post.