The interface

A fixed-ceiling connection pool over any Driver. Opening a database connection is expensive — a TCP handshake and auth round trip for a networked backend — so a server hands out a small set of connections and reuses them instead of opening one per request.

The pool is generic in the concrete driver D rather than holding &Driver trait objects, so acquire gives back the real driver type and a caller keeps access to backend-specific methods (SQLite's exec_script, a driver's prepared-statement handle). new takes a make factory that opens one fresh connection; the pool calls it only when no idle connection is available and the open count is still below max_size.

Beyond plain reuse, the pool keeps a connection healthy over its lifetime.

* **pre-ping** (pre_ping) — before an idle connection is handed back it is probed with Driver::ping; a connection that fails the probe is closed and skipped, so a caller never receives a connection the backend has already dropped. * **max lifetime** (max_lifetime_ms) — a connection older than this is retired on acquire and replaced with a fresh one, so long-lived pools recycle connections a load balancer or the server may have aged out. Age is measured with an injected clock, exactly as database/sql swaps nowFunc in tests; the default clock disables the check. * **acquire timeout** (acquire_timeout_ms) — the wait budget an exhausted acquire is allowed. See the note on synchrony below.

It is synchronous and single-threaded by design — moondb's base contract is sync, and MoonBit's pure backends have no shared-memory threads — so acquire never truly blocks: nothing else can return a connection while one call waits. A request that finds the pool exhausted therefore fails immediately rather than sleeping; acquire_timeout_ms is carried into that failure's message and is the budget a driver running on an async runtime honours when it layers real waiting on top. Use try_acquire for the non-raising "give me one only if free" path. The reuse, ceiling, health, and lifecycle bookkeeping all live here.

The counting is moonpool's Pool: live, idle and lent, each lent connection's birth recognised on its way back so max_lifetime counts from creation. So is the optional ward in front of the database: backoff after failed connects, a token bucket spacing reconnections, a breaker, a shedder. This type adds only what needs a driver — opening, closing, probing.

Take a connection: reuse an idle one if the pool has a healthy, unexpired one (the common path, avoiding a fresh handshake), otherwise open a new one through make as long as the open count is below max_size.

An idle connection past max_lifetime_ms, or one that fails the Driver::ping probe when pre_ping is on, is closed and dropped rather than handed back; the pool then tries the next idle connection or opens a fresh one. Raises QueryError if the pool is exhausted (all max_size connections are checked out), ConnectError if the ward holds back or refuses a new connection, or Closed if it has been closed. The caller must return the connection with release — or use with_conn, which does so even on error.

The configured acquire wait budget in milliseconds (0 = fail immediately).

Close every idle connection and mark the pool closed. Connections still checked out are not touched — each is closed as it is released back. After this, acquire raises Closed. Idempotent.

This is the graceful half of a shutdown: nothing in flight is cut off. To wait for the rest, poll in_use_count until it reaches zero — this pool is synchronous, so the waiting belongs to whatever async layer owns it.

How many connections are currently idle (checked in and reusable).

How many connections are checked out right now. A shutdown that wants to wait for borrowed connections to come home polls this after close_all: the close empties the idle set, so what is left is exactly what is still in use.

Whether close_all has been called.

The configured maximum connection lifetime in milliseconds (0 = unlimited).

The pool's ceiling on simultaneously open connections.

Build a pool whose connections come from make.

* max_size caps how many connections may be open at once (in use plus idle); it defaults to 10, and must be positive. * max_lifetime_ms retires a connection older than this many milliseconds on acquire (0, the default, means no age limit). Enforcing it requires a real clock; with the default clock every connection reads as age 0. * pre_ping turns on the Driver::ping health probe before an idle connection is reused (off by default). * acquire_timeout_ms records the wait budget for an exhausted acquire; 0 (the default) means "fail immediately". In this synchronous pool the wait is always degenerate (see the type doc), so the value serves the error message and an async layer above. * clock returns a monotonically non-decreasing millisecond reading and exists so max_lifetime is testable and portable; it defaults to a constant 0, which disables age-based retirement. * ward is moonpool's, none by default. A ward that times anything needs a real clock. * rand draws from [0, 1) for the ward's breaker and backoff jitter; without it the pool draws from a system-seeded generator. * cpu reads the processor load in thousandths for the ward's shedder; without it the load reads as zero and the shedder never sheds.

How many connections the pool has open in total: those checked out plus those sitting idle. Never exceeds max_size.

How many connections may be opened above max_size when the pool is busy.

Whether the pre-ping health probe is enabled.

Return a connection to the idle set so a later acquire can reuse it, preserving the birth time it was opened with so max_lifetime keeps counting from creation rather than resetting on every checkout. A connection released back into a closed pool is closed immediately rather than pooled, so no handle outlives close_all.

Take a connection only if one is immediately available — an idle one or fresh headroom under max_size — returning None instead of raising when the pool is exhausted or its ward says no. This is the non-blocking counterpart of acquire, so a caller can choose to shed load or retry. Health and lifetime eviction apply exactly as in acquire; a genuine failure while opening a fresh connection (the make factory raising) still propagates.

Run f with a pooled connection, returning it afterwards whether f returns or raises. This is the leak-proof way to use the pool: the release happens on every path, so a raising query never strands a connection checked out.

A connection pool for an @moondb.AsyncDriver — the counterpart of @moondb/pool.Pool for a backend reached over the network.

It exists because a synchronous pool cannot do the one thing an exhausted pool is supposed to do: wait. In @moondb/pool.Pool nothing can return a connection while a caller is inside acquire, so a full pool fails immediately and acquire_timeout_ms only reaches the error message. Here the caller is a task in an event loop: other tasks keep running while it waits, so a full pool parks the caller on a permit and wakes it when a connection comes home. And it is what makes overflow and a real timeout meaningful.

The division of labour mirrors the sync pool: @moonpool keeps the accounting — live, idle, lent, each connection's birth time — and this type adds what only a driver can do (opening, probing, resetting, closing) plus the permit that makes an exhausted acquire wait.

let pool : @apool.AsyncPool[@postgres.PgConn] = @apool.AsyncPool::new(
() => @postgres.PgConn::connect("db", 5432, "app", "secret", "app"),
max_size=8,
overflow=2,
pre_ping=true,
acquire_timeout_ms=3000L,
reset=conn => conn.rollback() catch { _ => () },
)

let rows = pool.with_conn(conn => conn.query("SELECT 1", []))

How long an acquire may wait for a permit in milliseconds (0 = no limit).

The hard ceiling on concurrent checkouts: max_size + overflow.

How many connections are idle and reusable right now.

How many connections are lent out right now.

Whether close_all has been called.

The configured connection lifetime in milliseconds (0 = unlimited).

The steady-state ceiling on open connections.

Build a pool whose connections come from make, which runs inside the event loop and may await the handshake.

* max_size caps the steady-state number of open connections (default 10) and must be positive. * overflow is how many connections may be opened above max_size while every steady-state connection is lent; a connection that came from that allowance is closed on return rather than idled, so the pool settles back to max_size. * max_lifetime_ms retires a connection older than this on acquire (0, the default, means no age limit). Enforcing it requires a real clock. * pre_ping probes an idle connection with AsyncDriver::ping before handing it out, closing it and trying the next if the backend has dropped it. * acquire_timeout_ms is how long a caller may wait for a permit before failing (0, the default, means wait as long as it takes — the pool never gives up on its own). * reset runs on return before the connection becomes reusable: roll back a leftover transaction, clear session state. A reset that raises closes the connection instead of pooling it. * clock returns monotonic milliseconds and defaults to a constant 0, which disables age-based retirement; rand/cpu feed the ward's jitter and shedder.

How many connections the pool has open: lent plus idle.

How many connections may be opened above max_size while the pool is busy.

Whether the pre-ping probe is enabled.

A live connection to a SQLite database. Open it with SqliteDriver::open; it implements @moondb.Driver, so a moondb query layer can drive it directly. The opaque sqlite3* is carried as its pointer bits in handle.

A statement SQLite prepares once and runs many times.

prepare compiles the SQL into a sqlite3_stmt and keeps it alive; bind resets the compiled program and binds a fresh set of values, so a loop over a thousand rows pays for parsing and planning once. close finalises the statement. A :name statement is rewritten to ? at prepare time and remembers the slot names, so bind_named works without the caller numbering anything.

@moondb.Cursor's close, callable on the value directly.

@moondb.Cursor's next, callable on the value directly.

@moondb.Driver's begin, callable on the value directly.

@moondb.Driver's capabilities, callable on the value directly.

@moondb.Driver's close, callable on the value directly.

@moondb.Driver's commit, callable on the value directly.

@moondb.Driver's dialect, callable on the value directly.

Run a semicolon-separated script (e.g. a schema DDL block) in one call. Unlike execute, this uses SQLite's multi-statement exec path and binds no parameters. Raises @moondb.QueryError with SQLite's message on failure.

@moondb.Driver's execute, callable on the value directly.

Whether close has been called. Once closed, every statement raises @moondb.Closed rather than touching the freed sqlite3*.

Open (or create) the database at path. Use ":memory:" for a private in-memory database. Raises @moondb.ConnectError if the file cannot be opened.

@moondb.Driver's ping, callable on the value directly.

@moondb.Driver's prepare, callable on the value directly.

Compile sql into a reusable statement. A statement using :name parameters is rewritten to SQLite's ? spelling first.

@moondb.Driver's query, callable on the value directly.

@moondb.Driver's query_stream, callable on the value directly.

@moondb.Driver's rollback, callable on the value directly.

@moondb.Cursor's close, callable on the value directly.

@moondb.Cursor's next, callable on the value directly.

A live connection to a PostgreSQL backend, already past the startup handshake and sitting at ReadyForQuery. Runs the v3 frontend/backend protocol over a single @socket.Tcp. Not safe for concurrent use by multiple tasks: one statement must complete (drain to ReadyForQuery) before the next begins, as the wire protocol is a strict request/response pipeline per connection.

A COPY … FROM STDIN in progress: write_chunk(#write_chunk) pushes pieces as they are produced and finish(#finish) closes the stream and reports what the server did with it.

The stream owns the connection until finish (or fail(#fail)); writing after either is a QueryError. Chunks are passed through as COPY data messages, so a caller can stream a file of any size without materialising it.

A COPY … TO STDOUT in progress: the server sends the data in pieces and read_chunk(#read_chunk) hands them over one at a time, so a table or a query result larger than memory can be written straight to a file or a socket.

The stream owns the connection's single-response pipeline until it ends: read it to None (or cancel(#cancel) it) before the next statement. The chunks are the server's own framing — COPY text rows are newline-terminated, CSV rows likewise, binary rows are length-prefixed — so a caller writes them out verbatim.

A server-side cursor: DECLARE … CURSOR opens it inside the current transaction and next_batch(#next_batch) pulls at most batch rows per round trip.

This is the cursor for a result too large to hold, and it is different from PgRowStream, which streams one statement's response: the server owns the position, so the connection is free between fetches, and the rows already read are never resent. It requires an open transaction — a cursor declared outside one is closed by the implicit commit at the end of the statement.

The parameters needed to reach a PostgreSQL backend — a connection descriptor, not a connection. connect(PgDriver::connect) opens the live PgConn, which is the thing that implements the driver seam.

It exists so a caller can carry connection settings around (a config value, a pool factory) and open a connection from them on demand, the way a DSN string works elsewhere.

A forward-only cursor that reads a query's rows off the wire on demand instead of buffering them, the streaming counterpart to query, for results too large to materialise (asyncpg's cursor. It is bound to its PgConn, which is a single-statement pipeline: the stream must be drained (next returns None) or [closed](PgRowStream::close) before another statement runs on that connection.

A statement PostgreSQL prepares once, on the server, and runs many times.

prepare sends Parse for the statement's text under a generated name, so the parse and the plan survive between calls; each execute/query sends only Bind/Describe/Execute with new values. The name comes from the connection's statement cache keyed by the SQL text, so preparing the same text twice reuses one server-side statement rather than allocating a second.

A :name statement is preprocessed here — rewritten to $1, $2, … and the slot names remembered — which is what makes bind_named work without the caller numbering the parameters. A statement written with ? is translated the same way execute translates it, and a bare ? that is the JSONB operator is left alone.

The byte channel a connection speaks the PostgreSQL v3 protocol over.

A real connection uses a socket — plain, or a TLS session layered on one. The protocol code above it, though, only ever needs three things: read exactly n bytes, write these bytes, close. Pulling that out of PgConn is what lets the state machine (statement sequencing, the streaming guard, error draining, COPY, notifications) be tested against a scripted peer with no machine and no server behind it: pipe(PgWire::pipe) hands it one end of an in-memory pipe pair and the test plays the server on the other.

It is an enum rather than a trait object because the two transports have different concrete types already (@tcp.Conn, @io.PipeRead + @io.PipeWrite) and a closed set keeps the dispatch a match with no allocation.

Bind ('B'): bind params (all text format) to the unnamed statement, producing the unnamed portal, and request all result columns in text format.

Bind ('B') params to a named (or unnamed) prepared statement, producing a named (or unnamed) portal. All parameters and result columns use text format.

CancelRequest: Int32 length 16, Int32 request code 80877102, then the backend process id and secret key from BackendKeyData. Sent on a new connection to ask the server to cancel the query running on the old one.

Close ('C') for a named prepared statement: the server frees it and answers CloseComplete. A Sync follows so the message reaches a ready state on its own.

CopyData ('d'): one chunk of COPY data.

CopyDone ('c'): the client has sent every COPY chunk.

CopyFail ('f'): abort a COPY FROM STDIN with a message.

Describe ('D') the unnamed portal, so the server sends a RowDescription before the DataRows (giving column names + type OIDs for decoding).

Execute ('E') the unnamed portal with no row limit (0 = all rows).

Parse ('P'): prepare the unnamed statement from sql (with $n placeholders). Zero declared parameter types — the server infers them.

Parse ('P') into a named prepared statement, so a later Bind can reuse it without re-parsing. An empty name is the unnamed statement.

PasswordMessage ('p'): the auth response token (cleartext, or the md5… digest), as a C string.

Simple Query ('Q'): one SQL string, no bound parameters.

SASLInitialResponse ('p'): the chosen mechanism name, then the length-prefixed client-first SCRAM message (PG protocol §55.2.1).

SASLResponse ('p'): the raw client-final SCRAM message, no length prefix.

SSLRequest: Int32 length 8, Int32 request code 80877103. Sent before the startup message; the server answers a single byte — S to begin a TLS handshake, N to continue in cleartext.

StartupMessage: protocol version 3.0 (196608) plus the user / database parameters and a client_encoding=UTF8 request, terminated by an empty key.

Sync ('S'): close the extended-query batch; the server replies ReadyForQuery.

Terminate ('X'): ask the backend to close the connection.

Concatenate two byte strings. A small helper the MD5 auth path and message framing lean on; MoonBit's Bytes is immutable so this allocates once.

The number of ? placeholders translate_placeholders would consume — the count of parameters a statement expects. Shares the same scanner discipline so ?? escapes and quoted/comment spans do not count.

Decode PostgreSQL bytea hex text (\xDEADBEEF) back to raw bytes. A value not in hex form (legacy escape format) rides back as its UTF-8 bytes.

Decode a text-format result cell (raw, already UTF-8) tagged with its column oid into a Value. is_null marks a wire NULL (length -1), which decodes to Null regardless of type. Boolean, integer, floating-point, numeric, uuid, json/jsonb and the date/time OIDs decode to their typed cases; an OID the table does not know — an enum or a domain — rides back as Text, exactly the dialect-neutral contract moondb documents.

Encode a bound parameter to its text-format bytes, or None for SQL NULL (which the Bind message sends as a length of -1). Binding is out-of-band — the value never touches the SQL string — so this is the injection-safe path.

* integers / doubles / bools render to their canonical PostgreSQL text literals (t/f for booleans); * Text passes through UTF-8; * Blob uses the bytea hex format (\x + lowercase hex), which the server accepts for a text-format bytea parameter.

The pg_type OID of bool, as a column description reports it.

The pg_type OID of bytea, as a column description reports it.

The pg_type OID of date.

The pg_type OID of float4, as a column description reports it.

The pg_type OID of float8, as a column description reports it.

The pg_type OID of int2, as a column description reports it.

The pg_type OID of int4, as a column description reports it.

The pg_type OID of int8, as a column description reports it.

The pg_type OID of json.

The pg_type OID of jsonb.

The pg_type OID of numeric.

The pg_type OID of time.

The pg_type OID of timestamp.

The pg_type OID of timestamptz.

The pg_type OID of timetz.

The pg_type OID of uuid.

Parse a floating-point literal from PostgreSQL text (123.45, -1e10, Infinity, NaN), or None if malformed. Handles sign, fraction, and a base-10 exponent; the special IEEE tokens PostgreSQL emits are recognised.

Parse a base-10 Int, or None if s is not a well-formed integer. Used to decode int2/int4 result text; a parse failure falls back to Text so a surprising server rendering never silently becomes a wrong number.

Parse a base-10 Int64, or None on any non-digit (after an optional sign).

"md5" + hex(md5(hex(md5(password + user)) + salt)).

It is what the server asks for and nothing else uses it, which is why the shape is stated rather than assembled from parts a caller might reorder.

The backend process id, from BackendKeyData.

@moondb.AsyncDriver's capabilities, callable on the value directly.

@moondb.AsyncDriver's dialect, callable on the value directly.

Whether close(PgConn::close) has been called. A closed connection refuses further statements with @moondb.Closed.

Whether a PgRowStream is still outstanding. While one is, this connection refuses new statements — the wire is a single-statement pipeline — until the stream is drained or [closed](PgRowStream::close).

A session parameter the server reported (server_version, client_encoding, TimeZone, …), or None if it has not been reported.

How many rows the finished COPY reported, or 0 while it is still running.

Build a connection descriptor. Does not connect: PostgreSQL I/O is async, so the connection is opened by connect(PgDriver::connect) inside an event loop.

Close the channel. Idempotent at the transport level, so a double close after a failed handshake is harmless.

Wrap the client end of an in-memory pipe pair: from_server is where the peer's writes arrive, to_server is where this connection's writes go. Used by the offline protocol tests; a live connection never takes this path.

Wrap a socket — plain, or the TLS session @tcp.Conn::client returned.

SASLprep (RFC 4013) on a password before SCRAM: map the non-ASCII space characters to U+0020, drop the "commonly mapped to nothing" code points, then NFKC-normalize. An ASCII password is returned unchanged, which is the common case; a non-ASCII one would otherwise derive a different key from the server's stored verifier.

Build the SCRAM client-final message and the expected server signature from the server's first message (RFC 5802). client_first_bare is n=…,r=clientnonce; server_first is r=nonce,s=salt,i=iters. Returns (client_final_message, server_signature) — the client sends the first and verifies the server's v= against the base64 of the second.

The SCRAM ClientProof for the AuthMessage: ClientKey XOR HMAC(StoredKey, AuthMessage), where ClientKey = HMAC(SaltedPassword, "Client Key") and StoredKey = SHA256(ClientKey) (RFC 5802 §3).

The SCRAM ServerSignature: HMAC(ServerKey, AuthMessage), ServerKey = HMAC(SaltedPassword, "Server Key"). The client verifies the server's v= against this to authenticate the server (RFC 5802 §3).

Rewrite moondb's dialect-neutral ? positional placeholders into PostgreSQL's numbered $1, $2, … form. moondb fixes the calling convention (an ordered params array) but leaves the placeholder spelling to the driver; PostgreSQL's extended-query protocol requires $n, so a query layer that emits ? for portability is translated here before Parse.

A ? is only a placeholder in SQL text — never inside a single-quoted string literal, a dollar-quoted string, a "-quoted identifier, or a -- / /* */ comment. Those spans are scanned through verbatim so a literal ? in data or a comment is left untouched and does not shift the parameter numbering. A literal ? an application genuinely needs in output can be written ??, which collapses to a single ? (mirroring JDBC-style escaping).

Decode UTF-8 bytes to a String. PostgreSQL text values, column names, and error fields all arrive UTF-8 (the startup message negotiates client_encoding). Decodes the ASCII fast path directly and multi-byte sequences by code point; malformed input yields U+FFFD rather than raising, matching a lenient text codec.

The server's initial Handshake packet (protocol version 10), decoded down to the fields the client needs: the 20-byte auth salt, the negotiated capabilities, and the auth-plugin name that selects the scramble.

A cursor over one decoded MySQL packet payload. Every field type the protocol uses — fixed-width little-endian integers, length-encoded integers and strings, NUL-terminated strings, and raw byte runs — is read through this, advancing a position and raising MysqlError::ProtocolError on any short read. It holds no socket: the transport reads a full payload into Bytes first, then parses it here, which is what lets the whole codec be tested off any backend.

The server's reply to COM_STMT_PREPARE: the statement handle and how many parameters and result columns the statement has.

Substitute the ordered params for the ? placeholders in sql, producing the UTF-8 query bytes a COM_QUERY carries.

The text protocol has no out-of-band parameter binding — that arrives with prepared statements (COM_STMT_PREPARE, binary protocol) in a later round — so values are rendered as escaped literals here. The scanner tracks single-, double-, and backtick-quoted spans (honouring backslash escapes) so a literal ? inside a string or identifier is never mistaken for a placeholder, and it raises when the placeholder and parameter counts disagree.

Build the client's HandshakeResponse41 payload for user/password/database.

mysql_native_password and caching_sha2_password (MySQL 8's default, fast-path scramble here and full auth driven in MysqlConn::connect) are both handled directly. For any other plugin the client advertises mysql_native_password and sends a native token, so a native-capable account authenticates and otherwise the server drives an AuthSwitchRequest the connection layer answers (native or caching_sha2) or rejects. Only a server that requires a non-native plugin and does not offer pluggable auth is rejected here. client_ed25519 is answered by the connection layer when MariaDB switches to it.

SSLRequest: Int32 length 8, Int32 request code 80877103. Sent before the startup message; the server answers a single byte — S to begin a TLS handshake, N to continue in cleartext.

COM_STMT_CLOSE (0x19): the statement id; the server answers nothing.

COM_STMT_EXECUTE (0x17) for statement id, binding params out-of-band. Every non-NULL parameter is declared as VAR_STRING (or BLOB for bytes) and sent length-encoded; the server coerces it to the column type. The NULL bitmap uses bit i for parameter i, LSB first.

COM_STMT_PREPARE (0x16): the SQL text follows the command byte.

Build the materialised rows of a text-protocol result set from its column definitions and the raw row packets. This is the pure heart of query: the socket transport collects columns and row_payloads, and every cell decode happens here, off any backend.

Bytes → String, lossily (server version, error text, text-protocol cells).

The caching_sha2_password full-auth token: the NUL-terminated password XORed with the nonce (cycled), then RSA-OAEP encrypted under the server's public key.

seed is the 20 random octets OAEP masks with. MySQL's own client draws them from OpenSSL; here they are a parameter, because this package has no entropy source and a caller that reuses a seed should have to write that down.

The caching_sha2_password fast-auth scramble: SHA256(pw) XOR SHA256( SHA256(SHA256(pw)) ‖ nonce ), 32 bytes. An empty password sends an empty token.

The CLIENT_CONNECT_WITH_DB capability flag of the connection handshake.

The CLIENT_LONG_FLAG capability flag of the connection handshake.

The CLIENT_LONG_PASSWORD capability flag of the connection handshake.

CLIENT_MULTI_RESULTS: one statement may answer with more than one result set — what a stored procedure's CALL needs. Without it the server rejects a procedure that returns rows (ER_SP_BADSELECT).

CLIENT_MULTI_STATEMENTS: one COM_QUERY may carry several ;-separated statements.

The CLIENT_PLUGIN_AUTH capability flag of the connection handshake.

The CLIENT_PROTOCOL_41 capability flag of the connection handshake.

The CLIENT_SECURE_CONNECTION capability flag of the connection handshake.

The CLIENT_SSL capability flag of the connection handshake: the client will begin a TLS handshake after an SSLRequest packet.

The CLIENT_TRANSACTIONS capability flag of the connection handshake.

Concatenate two byte strings. A small helper the MD5 auth path and message framing lean on; MoonBit's Bytes is immutable so this allocates once.

Decode one binary-protocol result row against columns into a @moondb.Row. The row header is 0x00, then a NULL bitmap offset by two bits, then each non-NULL value in the column's binary type.

Map one text-protocol cell (None = the 0xFB NULL sentinel) onto a @moondb.Value using the column's declared type. Integers narrow to Int except BIGINT, which keeps 64 bits; FLOAT/DOUBLE become Double; binary-collation strings become Blob; everything else (VARCHAR, TEXT, DECIMAL, temporal types as ISO text, JSON) becomes Text.

The status-flags word of an EOF packet (0xFE, warnings LE16, status LE16), or 0 for a packet that is not a protocol-41 EOF.

Whether an EOF packet's status word says another result set follows.

Whether payload is an AuthSwitchRequest (0xFE lead byte with a body — the length is what tells it apart from a 5-byte EOF, exactly as is_eof_packet keys off < 9).

Whether payload is an EOF packet (first byte 0xFE, fewer than 9 bytes — which is what tells it apart from a row whose first cell is an 8-byte length-encoded value).

Whether payload is an ERR packet (first byte 0xFF).

Whether payload is an OK packet (first byte 0x00, at least 7 bytes).

MariaDB's MARIADB_CLIENT_CACHE_METADATA capability flag of the connection handshake.

MariaDB's MARIADB_CLIENT_COM_MULTI capability flag of the connection handshake.

MariaDB's MARIADB_CLIENT_EXTENDED_METADATA capability flag of the connection handshake.

MariaDB's MARIADB_CLIENT_PROGRESS capability flag of the connection handshake.

MariaDB's MARIADB_CLIENT_STMT_BULK_OPERATIONS capability flag of the connection handshake.

The MariaDB client_ed25519 response: the 64-byte Ed25519 signature of the server's 32-byte challenge, keyed by the password.

MariaDB keys the signature with the password itself, where RFC 8032 would expand a 32-byte seed — the derivation PrivateKey::of_secret exists for. The plugin signs unconditionally, so an empty password expands to SHA-512("") and still yields a valid signature.

A one-line rendering, e.g. ServerError(1146, 42S02): Table 'test.t' doesn't exist.

The mysql_native_password challenge response: SHA1(password) XOR SHA1(salt ++ SHA1(SHA1(password))), 20 bytes. An empty password produces an empty response (the server accepts a zero-length token).

Whether the cursor has consumed the whole payload.

Read n raw bytes.

Read a length-encoded string (the string<lenenc> type), returning None for the 0xFB NULL sentinel that appears in text-protocol rows.

Read a length-encoded unsigned integer (the int<lenenc> type). The 0xFB NULL sentinel and 0xFF are rejected here — NULL only has meaning inside a row, which lenenc_bytes handles.

Wrap a decoded packet payload for reading from the start.

Peek the next byte without advancing; -1 at end of payload.

Bytes not yet consumed.

Read everything left in the payload (an EOF-terminated string field).

Skip n bytes.

Read a NUL-terminated string, consuming the terminator.

Read one byte as an Int in 0..=255.

Read an n-byte little-endian unsigned integer.

Decode an AuthSwitchRequest into the plugin name the server wants and the fresh 20-byte auth salt for it. The trailing NUL that follows the scramble is dropped so the salt feeds native_password_scramble directly.

Decode a column-definition packet (protocol 41). Only the fields that steer text decoding are kept; catalog/schema/table names and the length/decimals fields are read past.

The 32-byte nonce from a client_ed25519 AuthSwitchRequest. MariaDB sends exactly NONCE_BYTES (= 32) with no NUL terminator and the client signs all of them, so — unlike the native scramble — the full 32 bytes are read raw rather than through the NUL-stripping parse_auth_switch_request.

Decode a full ERR packet (including its 0xFF marker) into the MysqlError::ServerError it represents.

Parse a protocol-10 initial Handshake payload. An ERR packet in its place (0xFF, e.g. "Host is blocked" / "Too many connections") is surfaced as a MysqlError::ServerError.

Decode an OK packet (including its 0x00 marker).

The RSA public key inside the PEM SubjectPublicKeyInfo the server sends.

Classify a raw handshake version string and recover the real version.

MariaDB 10+ prefixes its version with the fake 5.5.5- sentinel (MySQL 5.5.5 was never released), so pre-10 clients that gate on the leading 5. still connect. Strip it to get the true version — e.g. 5.5.5-11.4.2-MariaDB-ubu2404 → 11.4.2-MariaDB-ubu2404 as ServerKind::MariaDB; a plain 8.0.35 is returned unchanged as ServerKind::MySQL.

Decode the COM_STMT_PREPARE_OK packet: 0x00, statement id (LE32), column count (LE16), parameter count (LE16), one reserved byte, warning count (LE16).

Append a length-encoded string (its lenenc length prefix, then the bytes).

Append a length-encoded unsigned integer.

Append raw bytes followed by a NUL terminator.

Append an n-byte little-endian unsigned integer.

SERVER_MORE_RESULTS_EXISTS: the status flag that says another result set follows the one just terminated.

A live MySQL connection over a raw TCP socket, speaking the wire protocol in pure MoonBit. This is the asynchronous, full-fidelity driver: it owns the socket for its whole lifetime, so begin/commit/rollback bracket a real server-side transaction. The synchronous @moondb.Driver adapter (MysqlDriver) is layered on top for the moondb contract.

Framing is the classic 3-byte little-endian length + 1-byte sequence id header; the transport transparently reassembles the 0xFFFFFF continuation frames a large payload is split into.

A synchronous @moondb.Driver over MySQL — the adapter that lets a moondb query layer (moonorm) talk to MySQL through the same contract as the SQLite and Postgres drivers.

## The async wall, and what it means here

moonbitlang/async sockets are asynchronous, but @moondb.Driver's methods are synchronous, and MoonBit forbids calling an async function from a non-async one. The bridge is @async.run_async_main, which spins an event loop, runs an async body to completion, and returns — the same hook the toolchain uses to enter async fn main.

A socket does **not** survive across two such event loops (each tears its file descriptors down; verified empirically), so every execute/query opens a fresh connection, authenticates, runs its one statement, and closes. That is correct and efficient enough for autocommit work — which is exactly what the moondb roundtrip is — but it means a transaction cannot be held open across separate Driver calls. begin/commit/rollback therefore raise a clear error directing callers to the asynchronous MysqlConn API, which owns its socket for its whole lifetime and brackets real transactions. This is a language constraint, not a shortcut, and it is documented in the README.

A forward-only cursor that reads a query's rows off the wire on demand instead of buffering them, the streaming counterpart to query, for results too large to materialise at once (mysql_use_result. Bound to its MysqlConn, a single-command pipeline: the stream must be drained (next returns None) or [closed](MysqlRowStream::close) before another statement runs on that connection.

A statement MySQL prepares once and runs many times.

prepare sends COM_STMT_PREPARE and keeps the server-side handle; every execute/query sends only the statement id and the values, which is both cheaper than re-parsing and the path that binds binary payloads without hex expansion. close sends COM_STMT_CLOSE, after which the handle raises Closed.

A :name statement is rewritten to MySQL's ? spelling at prepare time and the slot names are kept, so bind_named works without the caller counting anything. A handle belongs to the connection that prepared it: one wire, one statement at a time.

@moondb.AsyncDriver's capabilities, callable on the value directly.

Close the socket (best-effort, idempotent).

@moondb.AsyncDriver's dialect, callable on the value directly.

The dialect (MySQL or MariaDB) reported by the server's handshake.

@moondb.Driver's begin, callable on the value directly.

@moondb.Driver's capabilities, callable on the value directly.

@moondb.Driver's close, callable on the value directly.

@moondb.Driver's commit, callable on the value directly.

@moondb.Driver's dialect, callable on the value directly.

@moondb.Driver's execute, callable on the value directly.

Configure a driver. host defaults to loopback, port to 3306; password and database may be empty. tls turns on TLS for the connection.

@moondb.Driver's ping, callable on the value directly.

@moondb.Driver's prepare, callable on the value directly.

@moondb.Driver's query, callable on the value directly.

@moondb.Driver's query_stream, callable on the value directly.

@moondb.Driver's rollback, callable on the value directly.