PostgreSQL Proxy V1 Supported Subset

Status: stable release-candidate surface for 1.0.0-rc.1.

InterLock exposes a PostgreSQL protocol 3.0 listener. It is a governed proxy, not a complete PostgreSQL server implementation.

Connection And Source Selection

• The startup database selects a registered PostgreSQL source.
• The startup user identifies the InterLock identity’s PostgreSQL username.
• InterLock authenticates the client before opening the source connection.
• The password exchange accepts the identity’s dedicated PostgreSQL password or an allowed InterLock API key.
• Source service credentials come from the source configuration or secret reference; they are never supplied by the agent.
• Production requires client TLS at the listener or explicitly trusted TLS offload. Upstream PostgreSQL TLS uses certificate and hostname verification in production.

V1 requests PostgreSQL cleartext password authentication inside the protected TLS channel. Clients must not use the V1 listener without TLS.

Supported Frontend Messages

Message	V1 behavior
StartupMessage	PostgreSQL protocol 3.0 only
SSLRequest	Supported when listener TLS is configured
CancelRequest	Opaque InterLock key is translated to the live upstream session; unknown or stale keys close silently
Query (Q)	Governed Simple Query flow
Parse (P)	Parsed and governed before forwarding
Bind (B)	Tracks statement-to-portal state
Describe (D)	Supported with bounded response forwarding
Execute (E)	Governed result collection, redaction, and audit
Flush (H)	Bounded collection; pending Execute rows are redacted and audited
Sync (S)	Completes bounded Extended Query response processing
Close (C)	Cleans statement or portal tracking and forwards upstream
Terminate (X)	Closes the session

Prepared statement parameters are forwarded using PostgreSQL protocol semantics. Unresolved or previously denied prepared statements and portals fail closed.

Explicitly Unsupported In V1

• GSS encryption negotiation.
• COPY frontend and backend streaming, including COPY FROM PROGRAM.
• PostgreSQL replication protocol.
• Transparent pass-through of unknown protocol extensions.

Unsupported behavior returns SQLSTATE 0A000 or closes the connection when a safe protocol recovery is impossible. Applications requiring COPY must use an origin connection outside the InterLock V1 proxy, subject to their organization’s policy; those operations are not governed by this listener.

Cancel keys are generated by InterLock and scoped to the lifetime of the client session. The origin server’s process id and secret key are never exposed to the client. A cancel connection receives no response, matching PostgreSQL wire semantics; unknown, malformed, and stale keys are ignored and closed.

SQL Governance

All statements are parsed with the PostgreSQL dialect before execution. Multi-statement requests are evaluated in full. InterLock derives operation, schemas, tables, columns, volatility/session effects, and write risk.

• Source roles must allow every requested action/resource.
• Policy may deny, redact, rate-limit, classify, or cap write risk.
• Risky writes queue for approval.
• Unknown, mutating, session-changing, and side-effecting SQL fails closed or receives conservative write treatment.
• Multi-statement, session-dependent, volatile, and write SQL is not eligible for deterministic read caching.

This includes conservative handling for DML, DDL, GRANT/REVOKE, role and search-path changes, sequence mutation, notifications, advisory locks, data-modifying CTEs, SELECT INTO, and COPY forms.

Redaction, Caching, And Audit

• Simple and Extended Query rows are collected within configured result limits, PII-scanned, policy-redacted, then sent to the client.
• Cache entries contain only the governed response and are scoped by source, identity, team, mapped role, grant version, policy/redaction decision, parameters, and source generation.
• Writes are never cached and invalidate relevant deterministic dependencies.
• Every accepted, denied, queued, cached, failed, and executed operation emits canonical audit metadata.

Bounds And Failure Behavior

The listener applies configurable limits for startup frames, regular frames, collected results, client connections, startup/auth/frame/idle timeouts, and upstream response phases. A timeout or malformed partial frame closes the connection if continuing could desynchronize protocol parsing.

Common SQLSTATE behavior:

SQLSTATE	Meaning in the proxy
08004	Connection or upstream credential/source rejection
28000	Client authentication or required TLS failure
42501	Source-role, policy, or write-safety denial
53400	Rate/limit condition
54000	Protocol frame or result limit exceeded
57014	Timeout/cancel-like proxy termination
0A000	Unsupported V1 feature

Error message text is not a stable API. Clients should branch on SQLSTATE.

Client Compatibility Target

The V1 release candidate targets psql, Psycopg 3, asyncpg, PostgreSQL JDBC, and pgx/Go for supported operations. A client may be listed as certified only when its dated report is tied to the release commit.

Certified today: asyncpg only. It is the sole client that drives the V1 listener in the test suite, over both the API-key and the pg_username credential forms.

The other four are targets with no evidence behind them. That distinction is published rather than left to the reader because the sentence above previously read “must certify” and named all five, which describes an intention in the grammar of a completed obligation - the same failure this document set exists to prevent. psql in particular is what an operator reaches for first, and the setup walkthrough documents connecting with it; that path is exercised by hand, not by a gate, and the extended-protocol behaviour a JDBC or pgx driver relies on is materially different from asyncpg’s.