waxing gibbous · a statute of moondb
moonpostgres
The PostgreSQL implementation of the Driver contract — extended query, a statement cache, server-side cursors, COPY streamed in both directions, and results in either wire format.
Enactment
What it is
moonpostgres connects to a PostgreSQL server and implements Driver against it. It speaks the $1, $2, … placeholder token and binds parameters out-of-band.
Install
moon add moonbitstack/moonpostgres
Placeholder
$1, $2, … positional — PostgreSQL's native numbered placeholders, bound server-side. A :name statement is rewritten to them at prepare time and the slot names are kept, so bind_named takes a map.
Prepared statements
prepare sends Parse under a name cached by SQL text, so a repeated statement binds instead of re-parsing; Close reclaims it and drops the cache entry.
Streaming
PgRowStream reads one response off the wire; PgCursor is a DECLARE/FETCH cursor the server holds open, a batch per round trip; copy_in_stream and copy_out_stream move COPY data one chunk at a time, so a 100 MB load never sits in memory.
Result format
Text by default; binary = true on query, query_stream or prepare_stmt asks for the binary format, chosen per column from its type — so one row can carry both. float4 and timestamptz stay text on purpose: their binary form would not read back as the value their text form does. A prepared handle describes the columns once and pays nothing per run.
Auth
trust cleartext MD5 SCRAM-SHA-256, with SASLprep, channel binding and server-signature verification TLS.
Coverage
execute query transaction close query_stream (live) prepare dialect LISTEN/NOTIFY CancelRequest binary results ping (default).
Addition
Servers that speak this protocol
PostgreSQL is not the only server that answers its wire protocol, and the driver needs no change to reach one: the startup handshake, the extended query protocol, the binary formats and the error mapping are what the protocol defines, not what one vendor defines. What differs is the SQL on top, and that is written down rather than discovered mid-statement.
openGauss 7.0
Verified against a real server, in CI, with the shared conformance matrix: 12 of 12. Logins work under password_encryption_type = 0 (MD5); the default SHA-256 and SM3 exchanges are not implemented by this driver, and the server refuses the connection. Its SQL has gaps a caller has to plan around: no ON CONFLICT … DO UPDATE, no DOMAIN, no LISTEN, an empty string stored as NULL, and BackendKeyData's pid that is not pg_backend_pid(). capabilities() still describes the driver, so read notifications as "implemented here", not "served there".
CockroachDB v24.3
Same protocol, same twelve cases passing. No LISTEN/NOTIFY and no DROP TYPE … CASCADE; cursors, COPY, savepoints and RETURNING all work. moonckdb is the package that names the server (server_of) and reports notifications: false for it, so a subscriber polls instead of failing.