Pgwire

pkg/sql/pgwire/ implements the PostgreSQL v3 wire protocol. Clients using libpq, JDBC, asyncpg, pgx, npgsql, or any other Postgres driver connect to CockroachDB through this package.

Files

File	Purpose
pkg/sql/pgwire/server.go	The listener; accepts connections and dispatches to per-conn handlers
pkg/sql/pgwire/conn.go	Per-connection state machine
pkg/sql/pgwire/auth.go	Authentication dispatch (cert / password / JWT / OIDC / LDAP)
pkg/sql/pgwire/hba/	pg_hba.conf-style auth rules
pkg/sql/pgwire/identmap/	pg_ident.conf-style identity mapping
pkg/sql/pgwire/pgwirebase/	Wire-encoding helpers reused outside pgwire
pkg/sql/pgwire/pgerror/	Postgres-compatible error envelopes
pkg/sql/pgwire/pgnotice/	Notice (non-error) emission

Connection flow

sequenceDiagram
  participant C as client
  participant L as pgwire.Server
  participant A as auth.go
  participant E as connExecutor
  C->>L: TCP connect (TLS optional)
  C->>L: StartupMessage (user, database, options)
  L->>A: dispatch by hba rules
  A->>C: AuthenticationRequest (md5 / scram / cert / jwt / …)
  C->>A: response
  A->>L: ok
  L->>E: hand off conn
  loop per statement
    C->>E: Query / Bind / Execute / Sync
    E->>C: RowDescription / DataRow / CommandComplete
  end

Authentication

pkg/sql/pgwire/auth.go chooses the authenticator using pg_hba.conf rules stored in system.settings. Supported methods:

• cert — TLS client cert + CN.
• password — bcrypt or SCRAM-SHA-256.
• jwt_token — opaque JWT validated against pkg/security/jwtauth/.
• gss — GSSAPI (Kerberos) via pkg/ccl/gssapiccl/.
• ldap — LDAP bind, optionally with group→role mapping.
• cert_password — combined.
• trust and reject — debugging only.

SCRAM and password

CockroachDB stores hashes Postgres-compatible. SCRAM-SHA-256 is the default; bcrypt is supported for backwards compatibility.

Extended-query protocol

The full extended-query protocol is implemented: Parse / Bind / Execute / Describe / Sync / Close. Cursor-based pagination is supported, as is COPY-from-STDIN and COPY-to-STDOUT.

Cancel-request

Pgwire's "cancel request" frame is honored to cancel in-flight queries; pkg/sql/pgwire/cancel.go and connExecutor cooperate to interrupt.

Related pages

• systems/sql — what the connection drives.
• systems/security — authenticators.
• features/multi-tenant — tenant routing happens before pgwire dispatches to a connExecutor.