Skip to content

PostgreSQL Wire Protocol

xcon-db speaks pg-wire so that every language's PostgreSQL driver, ORMs and Grafana's pg datasource work without an xcon-specific client.

Connecting

postgres://<user>:<password>@host:5432/<db>?sslmode=disable
  • Auth is SCRAM-SHA-256 (the only mechanism offered). Cleartext never crosses the wire.
  • The user reaches only its own database; the database parameter defaults to the user name.
  • With -tls-cert/-tls-key set, SSLRequest is accepted (sslmode=require works); otherwise the server answers N and clients fall back to plain TCP.

Client notes

psql — works over the simple query protocol. \d-style meta commands query pg_catalog, which xcon-db does not emulate; use SHOW TABLES.

Go (pgx) — use simple protocol mode, since bind parameters are not supported:

conn, err := pgx.Connect(ctx,
  "postgres://firm1:secret@host:5432/firm1?sslmode=disable&default_query_exec_mode=simple_protocol")

Grafana — add a PostgreSQL datasource; write panel queries in the TS subset (SAMPLE BY for downsampling). Disable the query builder and write raw SQL.

JDBC / others — no-parameter statements over the extended protocol are supported (Parse/Bind/Describe/Execute without binds); parameterized prepared statements are rejected with a clear error — inline the literals.

Protocol surface

Feature Status
Simple query (Q), multi-statement ; ✅
Extended protocol without parameters ✅
Bind parameters ($1) ❌ inline literals
SCRAM-SHA-256 ✅ (with and without TLS)
TLS ✅ optional
pg_catalog / information_schema ❌ use SHOW TABLES
Transactions ❌ single-statement semantics; BEGIN is not accepted