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", []))

Take a connection, waiting for one if the pool is at capacity.

The wait is real: the calling task parks on the permit and other tasks in the loop keep running, so a connection released by another task wakes this one. With acquire_timeout_ms set, a wait longer than the budget raises QueryError.

An idle connection past max_lifetime_ms, or one that fails the AsyncDriver::ping probe under pre_ping, is closed and skipped rather than handed back — in both cases the slot is refilled, so a stale connection does not shrink the pool. Raises Closed if the pool has been closed, ConnectError if the ward holds back or refuses a new connection, and whatever make raised if opening a fresh connection fails.

Return the connection with release — or use with_conn, which does so on every path.

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

The hard ceiling on concurrent checkouts: max_size + overflow.

Close every idle connection and mark the pool closed. Connections still lent out are not cut off — each closes as it is released back — so this is the graceful half of a shutdown. After this, acquire raises Closed. Idempotent.

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.

Return a connection so a later acquire can reuse it, and wake one waiter.

The reset hook runs first; under overflow, a connection that pushed the open set above max_size is closed instead of idled so the pool settles back to its steady-state size. A connection returned to a closed pool is closed immediately, so no handle outlives close_all. Every path releases the permit exactly once.

Take a connection only if the pool is not at capacity, returning None instead of waiting. This is the load-shedding counterpart of acquire: a caller that would rather refuse work than queue can pick its own answer. Health and lifetime eviction apply exactly as in acquire, and a genuine failure while opening a fresh connection still propagates.

Run f with a pooled connection and return that connection afterwards, whether f returns or raises. This is the leak-proof way to use the pool.

A @moondb.Driver seen as an @moondb.AsyncDriver, so a backend whose work happens inside a C call can be handed to code written against the asynchronous seam — the checkpoint store of an agent framework, a retrieval index, a server that runs one event loop for every dependency.

The two traits are method-for-method identical, so the bridge is a delegation and nothing more: each async method calls its blocking twin and returns its result. There is no thread, no queue and no wake-up, because there is nothing to wait for — SQLite steps a sqlite3_stmt and returns.

What the bridge does not do is as important. The call runs on the task's own thread, so it occupies the event loop for as long as the driver takes: that is the right trade for a backend answering in microseconds out of the page cache, and the wrong one for a backend answering in milliseconds over a socket — a networked backend implements @moondb.AsyncDriver itself, where the wait is real and other tasks keep running through it. Nor does the bridge serialise: a driver that is not safe to use from two tasks at once is still not safe here, so give each task its own connection, or park them behind @moondb/apool.AsyncPool, which hands one connection to one caller at a time.

What it does keep is everything beyond the base contract: prepare hands back the driver's own server-side handle rather than a buffered re-run, query_stream keeps the driver's live cursor rather than materialising the result, and dialect and capabilities come from the wrapped driver, so a query layer sees the real backend underneath.

test "a blocking driver behind the async seam" {
let db = @blocking.Blocking::new(@moondb.MockDriver::new())
assert_eq(db.dialect(), @moondb.Dialect::Sqlite)
assert_true(db.capabilities().savepoints)
}

A blocking driver's @moondb.Cursor behind the asynchronous seam.

The default async query_stream materialises the whole result and hands back an array cursor, which is exactly the memory bound streaming exists to avoid. This adapter pulls from the wrapped cursor instead, so a backend that steps a prepared statement one row at a time keeps doing so — and the drain discipline is the wrapped cursor's: it must be read to None or closed.

A blocking driver's @moondb.Stmt behind the asynchronous seam.

The default async prepare would keep the SQL text and re-run the driver's execute/query on every call, which throws away the thing a prepared handle exists for. This adapter keeps the wrapped handle instead, so the SQLite sqlite3_stmt — compiled, planned and bound — is what each run reaches.

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

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

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

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

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

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

The driver this adapter wraps, for the methods the contract does not carry — a backend's own connection controls, an index rebuild, a file handle.

driver, presented as an @moondb.AsyncDriver.

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

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

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

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

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

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

cursor, presented as an @moondb.AsyncCursor.

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

@moondb.AsyncStmt's bind, callable on the value directly.

@moondb.AsyncStmt's bind_named, callable on the value directly.

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

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

stmt, presented as an @moondb.AsyncStmt.

@moondb.AsyncStmt's params, callable on the value directly.

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

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

@moondb.AsyncStmt's sql, callable on the value directly.

Run the conformance matrix against one live connection and report, case by case, which parts of the @moondb.AsyncDriver contract the backend honours.

## What it checks

The matrix is the contract's own text turned into cases: connect, bind and read back, prepare once and re-run, bracket a transaction, nest one through a savepoint, survive every @moondb.Value case the dialect has a column type for, and classify two failures the way the error model says they must be classified. Each case is one entry in the report, and a failure says what came back instead.

## What it does not check

It is a conformance suite, not a SQL-engine test: it says nothing about whether the backend's SQL is right, its planner fast, or its own extensions present. Nor does it check wire details — whether a driver offers a text or a binary result format is its own business, and both are expected to produce the same @moondb.Values.

## Using it

async test "the backend honours the contract" {
let conn = @moonpostgres.PgConn::connect(
"127.0.0.1", 5432, "postgres", "postgres", "test",
)
let report = @conformance.check(conn)
assert_eq(report.failures(), [])
}

A blocking driver goes through the bridge, and the suite then exercises the bridge as well:

async test "the embedded backend honours the contract" {
let db = @moonsqlite.SqliteDriver::open(":memory:")
let report = @conformance.check(@blocking.Blocking::new(db))
assert_eq(report.failures(), [])
}

The table it uses is created and dropped by the run, so the database needs no preparation beyond a connection allowed to create one. table names it when two runs share a database and would otherwise collide.

A case whose feature the driver reports as absent (capabilities().savepoints, for one) is recorded as skipped, with the reason, rather than quietly counted as a pass.

The same matrix over a blocking @moondb.Driver, bridged to the asynchronous seam so the cases are written once. The bridge is part of what the run exercises: an embedded backend's query_stream and prepare reach the suite through it.

How many cases it failed.

The cases that failed, one line each: what was checked and what came back. A test asserting a clean run wants this to be empty, and a person reading a red build wants exactly this.

Whether the backend honoured every applicable case. A skipped case does not make a report unclean — the backend said it could not, and the skip names why — but a failed one does.

How many cases the backend passed.

How many cases did not apply.

The skips, one line each, with the reason the backend gave.

One line a build log can carry: 14 passed, 1 skipped, 0 failed.

How many cases ran, skipped ones included.

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 a @moondb.Server error carrying SQLite's message and its result code on failure; DbError::kind gives the class.

@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. Parameters always go as text; formats says, one entry per result column, whether that column comes back in binary (1) or text (0). An empty formats is the protocol's own spelling of "all text".

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).

Describe ('D') a prepared statement, which answers with its parameter types and a RowDescription. That description is what a binary result needs before the Bind: the format code of each result column is chosen from its type.

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 char(n) (blank-padded).

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 name (an identifier column).

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.

The pg_type OID of varchar.

Parse a floating-point literal from PostgreSQL text (123.45, -1e10, Infinity, NaN), or None if malformed.

The three special tokens PostgreSQL emits are handled here; everything else goes to the language runtime's decimal-to-binary conversion, which rounds once and correctly. A hand-rolled mantissa × 10^exponent loop would not: multiplying by ten three hundred times drifts by several ULP, and 1e300 would come back as the double next to it — a value that then differs from the same column read in binary.

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.

Begin an explicit transaction (BEGIN).

Cancel the query currently running on this connection. PostgreSQL requires the request on a separate connection: this opens one, sends CancelRequest with the backend key, and closes it.

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

Close the connection: best-effort Terminate, then close the socket. Idempotent — a second call is a no-op.

Close a declared cursor.

Commit the current transaction (COMMIT).

Open a connection and complete the startup handshake: send StartupMessage, satisfy the authentication request (trust/AuthenticationOk, cleartext, MD5, or SASL/SCRAM-SHA-256), and drain server parameters up to the first ReadyForQuery. host may be a hostname or a literal IP; port is typically 5432. With tls, the connection first sends PostgreSQL's SSLRequest and negotiates TLS (a server that answers N is an error, not a silent downgrade), then runs SCRAM with channel binding when the server offers -PLUS. Raises ConnectError on any transport, TLS, or handshake failure.

Run a COPY … FROM STDIN, streaming data to the server in bounded chunks, and report the command tag's affected-row count. The convenience wrapper over copy_in_stream(#copy_in_stream) for a payload that is already in memory.

Start a COPY … FROM STDIN. Returns once the server has signalled it is ready for data.

Run a COPY … TO STDOUT and return everything it produced. The convenience wrapper over copy_out_stream(#copy_out_stream) for a result that does fit in memory.

Start a COPY … TO STDOUT and hand back the stream. Nothing is buffered: the first chunk is read by the first read_chunk.

Declare a cursor over sql inside the current transaction. batch is how many rows one FETCH asks for, and is the knob that trades round trips for memory.

Declare a server-side cursor over sql inside the current transaction. The caller must be inside an explicit transaction (begin); the cursor is closed by close_cursor or at commit/rollback.

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

Run a non-row statement (INSERT/UPDATE/DELETE/DDL) and report rows changed. last_insert_id is 0: the simple/extended protocols do not surface a generated key without a RETURNING clause (roadmap).

Fetch up to count rows forward from a declared cursor.

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).

Start listening on channel; next_notification then yields the payloads other sessions send with NOTIFY.

Block until a notification arrives on a channel this connection listens on, returning (channel, payload). Skips ParameterStatus and ReadyForQuery while waiting; an ErrorResponse raises.

Send a notification on channel, optionally carrying payload.

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

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

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

Parse sql on the server (or reuse the cached statement with the same text) and return the handle.

binary fixes the result format for the handle's whole life: each column is described once at prepare time and then bound in whichever format reads back the same value — binary where that is exact, text otherwise. A handle therefore pays for the description once instead of on every call, unlike PgConn::query.

Run a row-returning statement and materialise every row. Uses the simple Query protocol when params is empty and the result is text, and the extended Parse/Bind/Execute protocol (with ?→$n translation and out-of-band text-format binding) otherwise.

With binary, each result column whose type has an exact binary decoder is fetched in the binary format and the rest stay text — see decode_binary. Text is the default, and a binary result costs one extra round trip per call: the column types have to be described before the Bind can name a format for each.

Send sql (with bound params) and return a streaming cursor over its rows. binary asks for the same per-type binary result query does.

Roll back the current transaction (ROLLBACK).

Stop listening on channel (or every channel when channel is "*").

Abort the load (CopyFail with reason) and read the server's error. The connection stays usable; the rows already sent are rolled back with the statement.

Close the stream (CopyDone) and read the server's verdict, reporting the command tag's affected-row count.

Send one piece of COPY data. The chunk is framed here, so the caller only supplies the payload — rows in COPY's own format.

Abandon the stream: finish reading the server's response so the connection can run the next statement. Everything already read stays read.

The next chunk of copied data, or None once the server has finished. The command tag's row count is reported by rows(#rows) after the stream ends.

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

Close the cursor. Idempotent; a cursor also disappears with its transaction.

The next batch of rows, in order. An empty array means the cursor is exhausted.

Open the connection this descriptor points at. Call it inside an event loop (async test / async fn main); the returned PgConn is an @moondb.AsyncDriver.

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.

Abandon the stream early, draining any unread response to ReadyForQuery so the connection can run the next statement. Idempotent once the stream is done.

The next row, or None once the result is exhausted. Reads messages until a DataRow (updating the column metadata from any RowDescription first), and on ReadyForQuery marks the stream done. An ErrorResponse is drained to ReadyForQuery before raising, so the connection stays usable.

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.

Read exactly n bytes, waiting for them if the peer has not sent them yet.

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

Write every byte of bytes, then return. The peer sees them in one piece.

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.

streamed names the parameters whose value was already sent with COM_STMT_SEND_LONG_DATA: their type is still declared here — the server needs to know how to read the buffered bytes — but their value is not repeated.

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

COM_STMT_SEND_LONG_DATA (0x18): statement id, parameter index, then one slice of that parameter's value. The server appends slices in the order they arrive, answers nothing at all, and forgets the accumulated value once the statement is executed or reset — so the pieces must be sent immediately before the execute that binds them.

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).

How much of one parameter a COM_STMT_SEND_LONG_DATA packet carries, and the length at which a parameter stops travelling inside the execute packet and is streamed this way instead.

A packet is capped by the server's max_allowed_packet (64 MiB on MySQL 8 by default, 16 MiB on MariaDB), and the execute packet has to hold every parameter at once, so a value near that cap used to be un-sendable however it was encoded. One mebibyte is a sixteenth of the smaller default, which leaves room for the rest of the packet whatever the server is set to.

The parameter indexes, ascending, whose value is streamed rather than inlined. build_stmt_execute takes this list so it can leave their value bytes out.

The slices of parameter index to send with COM_STMT_SEND_LONG_DATA, in order. Empty when the value fits in the execute packet, which is the case for everything shorter than long_data_chunk and for NULL.

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.

Begin a server-side transaction.

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

Close the socket (best-effort, idempotent).

Commit the current transaction.

Open a connection to host:port and complete the auth handshake against user/password, selecting database (empty for none). Works against both MySQL and MariaDB (the reported dialect is on server_kind).

mysql_native_password and caching_sha2_password (MySQL 8's default, including the RSA full-auth path on a cache miss) are handled directly, whether the server drives them from its default or via an AuthSwitchRequest. With tls, the connection sends an SSLRequest after the greeting and runs the whole handshake over TLS; the caching_sha2 full-auth step then sends the password in cleartext under TLS instead of RSA-encrypting it. A switch to any other plugin (e.g. client_ed25519, on the README roadmap) raises @moonmysql.MysqlError::UnsupportedError.

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

Run a non-row statement and report the rows affected and last insert id. With bound params it uses a prepared statement (binary protocol, out-of-band binding); without, the text protocol.

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

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

Ask the server to prepare sql and return the handle.

Run a row-returning statement and materialise every @moondb.Row. With bound params it uses a prepared statement (binary protocol); without, the text protocol.

Run a statement that answers with more than one result set and return every set, in the order the server sent them — a stored procedure's CALL, or a multi-statement packet. Values bind only on the prepared path, which has no multi-result protocol of its own, so params must be empty here.

Send a row-returning statement and return a streaming cursor over its rows. The column definitions and their terminating EOF are consumed up front; the rows themselves are read one at a time by next(MysqlRowStream::next).

Roll back the current transaction.

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.

Abandon the stream early, draining any unread rows to the terminating EOF so the connection can run the next statement. Idempotent once the stream is done.

The next row, or None at the EOF that ends the result set. An ErrorResponse mid-stream is raised.

A ClickHouse server, reached over its HTTP interface.

Every statement is one HTTP request on its own connection, which is what the interface itself is: stateless, one query in the body, its parameters in the URL. Nothing is held open between calls, so a connection can be shared by any number of tasks without a lock, and a close is bookkeeping rather than a round trip.

The driver asks for RowBinaryWithNamesAndTypes, so a column value crosses the wire in its own bytes rather than as the text the server would print, and reads the count of written rows back from the X-ClickHouse-Summary header.

let db = @clickhouse.ClickHouseConn::connect("127.0.0.1", user="default", database="default")
db.execute("CREATE TABLE hero (id Int32, name String) ENGINE = Memory", []) |> ignore
db.execute("INSERT INTO hero VALUES (?, ?)", [Int(1), Text("Nova")]) |> ignore
let rows = db.query("SELECT name FROM hero WHERE id = ?", [Int(1)])

ClickHouse has no transactions: begin, commit and rollback are recorded so a caller can see the state, but no statement is grouped with another.

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

Close the connection. The interface is stateless, so this only stops later calls with Closed.

Open a connection to host:port and prove the credentials with one SELECT 1. The HTTP interface is request-scoped, so "opening" is that round trip and nothing is retained.

The database this connection addresses.

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

Run a statement and discard its rows, reporting how many it wrote. ClickHouse's summary header carries the counts, so rows_affected is the server's number and not a guess.

Whether a begin is outstanding. Nothing is rolled back by it on this engine.

Whether the server answers SELECT 1, reported as a verdict rather than raised.

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

Run a row-returning statement and materialise the result.

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

What this server can do, as opposed to what the driver implements. @moondb.Capabilities::for_dialect describes the PostgreSQL implementation; CockroachDB is not PostgreSQL, and the difference that matters to a caller is notifications: LISTEN and NOTIFY do not exist there, so a query layer that plans to wait for a notification has to poll instead.

The rest of the PostgreSQL surface does hold on CockroachDB — cursors, savepoints, COPY in both directions, RETURNING — which is why this clears one flag and not a row of them.

Connect the way @moonpostgres.PgConn::connect does — the protocol is the same one, and there is nothing to translate.

The server a SELECT version() answer names. CockroachDB reports itself as CockroachDB CCL v24.3.0 (x86_64-…, built …), PostgreSQL as PostgreSQL 16.4 …, and a compatibility layer that borrows the string is still that layer.

Which server is behind this connection, asked rather than assumed.

The server's own version sentence, as it answered.

What this server can do, as opposed to what the driver implements. @moondb.Capabilities::for_dialect describes the PostgreSQL implementation; CockroachDB is not PostgreSQL, and the difference that matters to a caller is notifications: LISTEN and NOTIFY do not exist there, so a query layer that plans to wait for a notification has to poll instead.

The rest of the PostgreSQL surface does hold on CockroachDB — cursors, savepoints, COPY in both directions, RETURNING — which is why this clears one flag and not a row of them.

Connect the way @moonpostgres.PgConn::connect does — the protocol is the same one, and there is nothing to translate.

The server a SELECT version() answer names. CockroachDB reports itself as CockroachDB CCL v24.3.0 (x86_64-…, built …), PostgreSQL as PostgreSQL 16.4 …, and a compatibility layer that borrows the string is still that layer.

Which server is behind this connection, asked rather than assumed.

The server's own version sentence, as it answered.

A live connection to a DuckDB database, embedded in the process and reached through its C API — or, on the js target, through DuckDB's own WebAssembly build, which offers the same calls once it is instantiated.

On native the engine is not linked in: the stub loads the released shared library on the first call, which is what keeps this package a single small C file instead of a twenty-megabyte C++ build. MOONDUCKDB_LIBRARY names the library when the loader's default search does not find it. On js the engine is a build fetched before the run: see scripts/fetch_engine.sh.

The type, its methods and the trait are the same on both. Only open differs, because a WebAssembly module has to be instantiated before it can be called.

A statement DuckDB prepared once. DuckDB's PREPARE survives across runs, so a repeated INSERT binds new values to the same plan instead of being parsed again — which for an analytical engine is where most of the per-statement cost sits.

@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.

A semicolon-separated script, run as one call — for a schema block, where the statement-by-statement path would be a statement per line.

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

Whether close has been called.

Open (or create) the database at path. Use ":memory:" for a private in-memory database. Raises @moondb.ConnectError when the library cannot be loaded — the message says which name was looked for — or when the file cannot be opened.

@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.

@moondb.Stmt's bind, callable on the value directly.

@moondb.Stmt's bind_named, callable on the value directly.

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

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

Prepare sql on connection.

@moondb.Stmt's params, callable on the value directly.

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

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

@moondb.Stmt's sql, callable on the value directly.

A live connection to a SQL Server instance, speaking TDS 7.4 directly. Open it with SqlServerConn::connect; it implements @moondb.AsyncDriver, so a query layer written for PostgreSQL or MySQL drives it unchanged.

Every statement is either a SQL batch or an RPC to sp_executesql, and the answer is read out of the token stream — COLMETADATA, ROW, NBCROW, DONE, ERROR — rather than through a client library.

One SQL text compiled by the server, run with new values on every call.

The handle comes from sp_prepare and is released by sp_unprepare; between the two, a run is a sp_execute RPC that sends the handle and the values and nothing else — the statement text does not travel again.

A statement's declaration is part of what the server compiles: sp_prepare is told the type of every parameter, and those types come from the values. So a handle is compiled at the first bind that has values (or immediately, for a statement with no placeholders), and a later bind whose values declare different types drops the old handle and compiles a new one rather than sending values the plan did not expect.

The transport under the protocol.

A TLS configuration that encrypts without authenticating: SQL Server ships a self-signed certificate, and a driver that refused it would refuse every default install. Pass your own @tls.Client to connect to check the chain instead.

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

Copy rows into table, one cell per name in columns, and report how many rows the server took.

The rows travel in the protocol's bulk-load format: INSERT BULK declares the shape, then one message carries the column metadata and every row. Values are bound into that stream, never spliced into the statement, so a string containing a quote is a string.

let copied = conn.bulk_copy("hero", ["id", "name"], [
[@moondb.Int(1), @moondb.Text("Nova")],
[@moondb.Int(2), @moondb.Text("Ivan")],
])

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

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

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

Open a connection. encrypt defaults to true: the login packet carries a password, and prelogin is where the client says so. A server that answers "encryption not supported" gets a clear session, because the alternative is refusing to connect to it.

strict selects TDS 8.0, where TLS is not negotiated at all: it has already started before the first TDS byte, so prelogin and the login inside it are encrypted whether the server would have offered encryption or not. A server older than SQL Server 2022 fails the handshake — which is the point of asking for it.

The database the session is in.

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

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

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

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

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

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

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

@moondb.AsyncStmt's bind, callable on the value directly.

@moondb.AsyncStmt's bind_named, callable on the value directly.

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

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

@moondb.AsyncStmt's params, callable on the value directly.

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

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

@moondb.AsyncStmt's sql, callable on the value directly.

The configuration a TDS 8.0 session needs: the same permissive trust as permissive_tls, plus the ALPN protocol tds/8.0. The server uses ALPN to tell which protocol version a TLS connection that started before any TDS byte is carrying; without it the handshake is refused, so a caller who supplies their own configuration for a strict connection has to name the protocol themselves.