What a procedure is in MongrelDB

The definition you install is an array that mirrors the engine’s StoredProcedure struct field for field, and the only fields you do not own are the ones the server recomputes on install, so you send placeholders for those and it fills in the truth:

$db->createProcedure([
    'name' => 'users_by_status',
    'version' => 1,
    'mode' => 'read_only',
    'params' => [
        ['name' => 'status', 'ty' => 'varchar', 'nullable' => false],
    ],
    'body' => [
        'steps' => [
            [
                'kind' => 'native_query',
                'id' => 'scan',
                'table' => 'users',
                'conditions' => [
                    [
                        'kind' => 'bitmap_eq',
                        'column_id' => 3,
                        'value' => ['kind' => 'param', 'value' => 'status'],
                    ],
                ],
                'limit' => 100,
            ],
        ],
        'return_value' => ['kind' => 'step_rows', 'value' => 'scan'],
    ],
    // Server-assigned; the install path recomputes all three.
    'checksum' => '',
    'created_epoch' => 0,
    'updated_epoch' => 0,
]);

Three things in there are doing real work. The mode is either read_only or read_write, and the engine enforces it, so a procedure that only reads can never quietly start writing underneath you. The params are typed against the same type vocabulary the columns use, each with a name, a nullable flag, and an optional default, which means the contract of the procedure is declared data and not a comment in a wiki. And the body is a list of steps whose values can reference each other, because a value in MongrelDB’s procedure language is one of literal, param, step_rows, step_row, step_scalar, object, or array; the param kind dereferences a named call argument, and the step_* kinds consume the output of an earlier step, so a write procedure can read something in step one and feed it into a put or upsert in step two, all inside one committed call, with no client round trip in the middle.

The lifecycle from PHP

Once the definition exists, the rest of the lifecycle is four more calls and none of them involve SQL strings:

use Visorcraft\MongrelDB\Database;

$db = new Database('http://127.0.0.1:8090', token: $token);

// Install or replace: POST /procedures with the definition from the section above.
$created = $db->createProcedure($definition);

// List everything installed: GET /procedures.
$names = array_column($db->procedures(), 'name');

// Fetch one definition back, checksum and all.
$def = $db->procedure('users_by_status');

// Call it. Named arguments map onto the declared params.
$rows = $db->callProcedure('users_by_status', args: ['status' => 'active']);

// Retire it: DELETE /procedures/users_by_status.
$db->dropProcedure('users_by_status');

The call path is the piece PHP fits better than any client language I have used for this, because the server expects the call arguments as a JSON object keyed by param name and PHP’s associative arrays are exactly that shape, so $db->callProcedure('users_by_status', args: ['status' => 'active']) sends {"status":"active"} and each key dereferences the param of the same name in the body; the args: label at the call site is ordinary PHP 8 named-argument syntax on the method itself, but the real mapping runs through the array keys, which is worth saying precisely because callProcedure('users_by_status', status: 'active') would not work, and the habit of naming arguments that PHP developers picked up in 8.0 still lines up nicely with a contract where every param is declared with a name and a type on the server side. One implementation detail in the client is worth knowing because it explains a whole class of confusing bugs you will now never have: callProcedure casts the args array to an object before encoding, since an empty PHP array serializes as [], a JSON sequence, while the server requires {}, a map, and that one cast is the difference between a procedure with no arguments working and the server rejecting your payload shape.

What steps can do

The step vocabulary covers the operations the engine can commit atomically: native_query reads a table through conditions (pk, bitmap_eq, bitmap_in, range, range_f64, is_null, is_not_null, and fm_contains for full-text substring matching) with an optional projection and limit, and put, upsert, delete_by_pk, and delete_rows mutate, with returning on the writes when you want the rows back. Because every value in a step can be a param reference or a step_scalar from earlier in the list, the read-then-write pattern that usually takes an application-side transaction, select the id, compute something, insert the child row, compresses into one call:

[
    'kind' => 'put',
    'id' => 'record_hit',
    'table' => 'counters',
    'cells' => [
        ['column_id' => 1, 'value' => ['kind' => 'param', 'value' => 'key']],
        ['column_id' => 2, 'value' => ['kind' => 'literal', 'value' => ['Int64' => 1]]],
    ],
    'returning' => true,
]

Two value shapes in that block deserve a sentence of their own, because they look asymmetric until you know why they differ: a literal wraps one of the engine’s typed values in a one-key tag, ['Int64' => 1], since the wire format has to know whether your 1 is an integer, a float, or a decimal128 before it can check the value against the column type, while a param value is a bare string because it carries no data at all and merely names the call argument to substitute at execution time.

Managing the catalog of procedures is a DDL operation, so installing, listing, describing, and dropping all require a principal with DDL permission, while calling one runs under the normal transaction discipline with the caller’s table grants checked the same way any other operation would be; the procedure is not a way to escape permissions, it is a way to pre-arrange work the caller was already allowed to do.

The honest tradeoff

The constraint to design around is that procedures called over the HTTP endpoint execute in the core engine, which does not host the SQL query layer, so a sql_query step is rejected there and your read steps are built from the native conditions instead; that is a deliberate boundary, because arbitrary SQL at call time is what the /sql endpoint is for, and the procedure surface stays limited to operations the engine can validate, checksum, and commit deterministically. The old world gave you unlimited power inside the procedure and paid for it with unreviewable string soup drifting in the catalog, the modern equivalent is a definition that is data, with a version you bump when the body changes and a checksum the server owns, and if you genuinely need free-form SQL in the middle of a procedure the honest answer is that MongrelDB has decided you do not, at least not over this endpoint, which is a smaller toolbox and, on the Fridays when the old catalog procedures used to break, a noticeably quieter one.

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.