corium-pgwire

A PostgreSQL wire-protocol front end for Corium SQL.

What it does

Speaks the PostgreSQL v3 frontend/backend protocol so ordinary PostgreSQL clients (psql, JDBC, psycopg, pgx, BI tools) can query and mutate Corium databases. Reads execute through corium-sql's SqlSession; supported DML is planned there and committed through the catalog's normal Corium transactor connection.

One server exposes a whole catalog of databases:

• serve — accepts connections on a TcpListener and handles each on its own task until a shutdown future resolves.
• DbCatalog — the async trait the server resolves databases through: list() enumerates the catalog and db(name) returns a fresh immutable snapshot. A write-capable implementation also provides transact(); its default implementation is read-only. Implementations open databases lazily and cache them, so one database (and its segment cache) is shared across all client connections.
• PgWireConfig — an optional required cleartext password and the reported server_version.

A connection picks its database with the standard startup database parameter and can switch at any time with USE <database>; SHOW DATABASES lists the catalog. The database is validated lazily, so a client may connect with an unknown default (for example the conventional postgres) and then USE a real one.

Protocol coverage

• Startup with TLS/GSSAPI negotiation declined (SSLRequest/GSSENCRequest answered with N).
• Trust or cleartext-password authentication.
• The simple query sub-protocol (Query), including multiple semicolon-separated statements.
• The extended query sub-protocol (Parse/Bind/Describe/Execute/ Sync/Close/Flush) with typed bound input parameters.
• Results use the text wire format. Common scalar input parameters accept text or binary format; array and text-timestamp inputs and binary results remain unsupported.
• INSERT, UPDATE, and DELETE over existing namespace projections, including RETURNING, execute as guarded autocommit statements. Concurrent basis changes are reported as serialization failures.
• Explicit transaction blocks track PostgreSQL's transaction status and allow reads, but reject writes until atomic multi-statement transactions exist.
• SET, RESET, and DISCARD are accepted as compatibility no-ops.
• USE <database> switches the active database and SHOW DATABASES lists the catalog.

Type mapping

Corium's SqlType/SqlValue are rendered into PostgreSQL types:

Parameter and result formats

Scalar parameters accept PostgreSQL text and binary encodings. Text timestamptz parameters accept ISO 8601 forms and require an explicit UTC offset because the server does not maintain a session time zone. Query results support both text and binary formats; array parameters remain unsupported.

Dependencies

• corium-sql, corium-db, corium-core — the database and its SQL projection.
• tokio — the async TCP server and framing I/O.
• async-trait — the DbCatalog trait; thiserror, tracing.

This is the crate behind the corium postgres-server command. See docs/sql.md and ADR-0013, and ADR-0015.

The CLI server remains read-only unless its operator passes --allow-writes. When enabled, the catalog commits through its cached corium-peer connection, so the configured Corium service principal and transactor authorization gate remain authoritative. PostgreSQL usernames/passwords are not yet mapped to Corium principals; per-user authentication and authorization parity is still future work.