pgwire: speak the Postgres wire protocol from your own Rust service

A protocol library, not a database

pgwire is a Rust library that implements the PostgreSQL wire protocol, and the framing the README gives is a build a Postgres compatible access layer for your data service. It provides the essential APIs needed to write Postgres compatible servers and clients, and the comparison the project draws is with hyper, but for the Postgres wire protocol instead of HTTP. That framing tells you the shape of the adoption. You keep your own storage and your own query logic, and pgwire handles the bytes on the wire, so tools that already speak Postgres, psql among them, can talk to your service without knowing anything about it. The README also points at datafusion-postgres as a more complete library built on top of pgwire, using datafusion as the query engine and adding a pg_catalog implementation, which is the shape most adopters will end up with.

Six parts to the protocol, and two of them are missing

The About section explains the protocol itself, and it is the place to start because it defines the scope of the library. Startup is the client to server handshake and authentication. Simple Query is the text based query protocol, where queries are strings and the server is allowed to stream data back. Extended Query is the newer sub protocol that can cache a query on the server and reuse it with new parameters. Copy moves data to and from the server. Replication and Logical Replication are the last two, and both are listed as not implemented in the status checklist, along with the streaming replication protocol message and the logical streaming replication protocol message. The same section makes a point that is easy to miss and that explains the library's appeal, since the wire protocol has no semantics about SQL at all, so you can use any query language, any data format or even natural language to interact with the backend. Responses are always encoded in data row format, with a field description header that names the field, its type and its format.

Authentication coverage, including the gap in GSSAPI

The status checklist details the handshake in useful detail. The frontend to backend interaction over TCP is marked done, and within it the SSL Request and Response with PostgreSQL 17 direct SSL negotiation is done, as is GSSAPI Request and Response, with the caveat spelled out in the same line, that GSSAPI encryption is not supported. Under Startup, protocol negotiation is done, and so are no authentication, clear-text password authentication, Md5 password authentication, SASL SCRAM authentication with both SCRAM-SHA-256 and SCRAM-SHA-256-PLUS, and SASL OAUTH. That is a broad spread, and the two entries that matter commercially are SCRAM and OAuth. The reason to look closely is the GSSAPI note, because a site that relies on Kerberos for database access will find the handshake present and the encryption absent, which is the kind of detail that is easier to discover in a design review than in production.

Simple, extended, copy, cancel and notify

The message layer beyond the handshake is well covered. Simple Query and Response are done, and so is Extended Query and Response, which the checklist breaks down into Parse, Bind, Execute, Describe and Sync. Termination, Cancel, Error and Notice, Copy and Notification are all marked done. Data types are handled in text format and in binary format, with the binary implementation living in the separate postgres-types crate rather than inside pgwire itself. The distinction that matters at the application layer is between the two query paths. Simple Query is what a psql session uses, where each statement is a string and the server may stream rows as it goes. Extended Query is the prepared statement path, with parameters bound separately, and the response part is identical to the simple one according to the README. If your service wants to serve both psql and a driver that uses prepared statements, you need to implement both handlers.

The server API is the finished half of the library

The usage section says that to use pgwire in your server application you need to implement two key components, a startup processor and a query processor. Adding a SimpleQueryHandler to your application gives you psql command line tool compatibility, and the ExtendedQueryHandler is required for more language drivers, additional prepared statement support and binary encoding. The API checklist shows how much of that surface is ready. On the server side, the Startup APIs are done, including the AuthSource API for fetching and hashing passwords and a Server parameters API that the README marks as ready but not very good. The Simple Query API, the Extended Query API with its QueryParser API for transforming a prepared statement, the ResultSet builder and encoder API, the Query Cancellation API, the Error and Notice API, the Copy API with copy-in, copy-out and copy-both, and transaction state are all done. The client side is thinner. Startup, Simple Query, Extended Query, Query Cancellation and transaction state are done, while the ResultSet decoder API, the Error and Notice API and the Copy API are not, and the README says plainly that for a general purpose Postgres driver you should use rust-postgres instead.

The sample programs show the shapes people build

The list of sample programs doubles as documentation of what the library is good for. The sqlite program uses an in-memory SQLite database at its core and serves it over the Postgres protocol, with both simple and extended query implementations, and you run it with cargo run --features _sqlite --example sqlite. The server program returns fixed results, and the secure server adds SSL support, while the scram program shows how to configure a stronger authentication mechanism and the transaction program shows how to control transaction state at the wire protocol level. The oauth and keycloak_oauth programs cover Postgres 18 OAuth authentication. Some programs have moved out, with the DuckDB and DataFusion ones now living in their own repositories, which separates the protocol layer from the query engine work. The projects using pgwire are a good proxy for the kind of service it suits, and the list includes GreptimeDB, a cloud native time series database, the risinglight OLAP database, PeerDB, a Postgres first ETL and ELT tool, CeresDB from AntGroup, dozer, a real time data platform, and a Postgres compatibility layer called pg_catalog.

Dual licensed and feature gated, with a recent last push

The crate is published on crates.io as pgwire, with the documentation on docs.rs, the licence declared as MIT and Apache 2.0 with both licence files in the repository, and the manifest setting edition 2024 with a rust-version floor of 1.89. The dependency list is organised by capability, which is the useful part of it. The async runtime group brings tokio, tokio-util, futures, async-trait, pin-project and rand, the TLS group brings tokio-rustls and rustls-pki-types, the authentication group brings md5, hex, base64, ring, aws-lc-rs, stringprep and x509-certificate, the OAuth group brings jsonwebtoken, rsa and reqwest, and the types group brings postgres-types, chrono and rust_decimal. Most of these are optional, so a service that only needs a Tokio server over TLS does not have to compile the OAuth stack. The repository adds a flake.nix and flake.lock for Nix users, a pgbench directory, a prek.toml for pre-commit hooks, a release.toml, and separate unit and integration test directories. The three listed releases are v0.40.6 and v0.40.7, both on 2026-08-17, and v0.41.0 on 2026-09-05, and the last push was on 2026-10-18 with the repository not archived.

Editorial conclusion

pgwire fits a team that already has a query engine or an embedded database and wants existing Postgres clients and tools to talk to it, since the wire protocol is the interoperability contract that matters and pgwire handles the framing, authentication and type encoding underneath. It is the wrong choice if you need replication, because both streaming replication and logical replication are marked as not implemented, and it is a poor fit if you need a client library, because the frontend API is still in progress and the README points you to rust-postgres for a general purpose driver. Before you adopt it, confirm that your clients only need simple or extended queries, pick the authentication method your users will accept, since GSSAPI encryption is not supported, and read the status checklist rather than assuming parity with PostgreSQL.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. README
4. Releases
5. sunng87/pgwire on GitHub