pgwire

The pgwire client/frontend API is currently under development. It is specifically designed for building components like PostgreSQL proxies that require full access to the wire protocol.

Note: If you are looking for a general-purpose PostgreSQL driver for application development (rather than building a proxy or protocol-level tool), it is recommended to use rust-postgres instead.

The libpq-client can be executed either with a default connection string or by providing a custom PostgreSQL connection string as a command-line argument. Upon execution, the client connects to the server and runs SELECT version() to verify the connection.

# Run with default connection string
./client

# Run with custom connection string
./client "host=localhost port=5432 dbname=postgres"

To build the libpq-client, you must have the libpq development library installed on your system.

Prerequisites:

• Debian/Ubuntu: libpq-dev
• CentOS/RHEL: postgresql-devel

Use make to compile the client and make clean to remove build artifacts.

The PgWireClient is designed to work with the futures ecosystem:

• Stream: It implements Stream<Item = Result<PgWireBackendMessage, PgWireError>>, allowing you to asynchronously iterate over messages sent by the PostgreSQL server.
• Sink: It implements Sink<PgWireFrontendMessage>, allowing you to send protocol messages to the server using methods like send(), feed(), or flush().

The SessionExtensions struct provides a type-safe, per-connection typed extension store. It allows different parts of your server (like authentication handlers or query handlers) to store and retrieve arbitrary state that is automatically cleaned up when the connection closes. It uses TypeId for lookups and supports interior mutability via Arc and RwLock.

// Define a custom state type
struct MyCustomState { pub count: i32 }

// Inside a handler with access to ClientInfo
let state = client.session_extensions().get_or_insert_with(|| {
    MyCustomState { count: 0 }
});

// Access or modify the state
// Note: Since it's an Arc, you may need to wrap the inner data in a Mutex/RwLock

To build a full PostgreSQL server, you must implement the various handler traits for the protocol components. These handlers are aggregated by the PgWireServerHandlers trait. Implement PgWireServerHandlers on a single struct to serve a complete connection.

Supported protocol components and their corresponding traits:

• Startup & authentication: StartupHandler
• Simple query: SimpleQueryHandler
• Extended query: ExtendedQueryHandler
• Copy: CopyHandler
• Cancellation: CancelHandler

pgwire is designed as a layered library for building PostgreSQL-compatible servers and clients. It provides three distinct levels of abstraction that can be composed based on your needs:

1. Protocol layer: Provides raw message definitions and codecs via the messages module. This is the lowest level and is available even without any features enabled.
2. Message handler layer: Uses handler traits (e.g., StartupHandler, SimpleQueryHandler) to manage protocol state. You implement on_ prefixed methods for protocol bookkeeping, which then dispatch to do_ prefixed methods where you implement your specific query or authentication logic.
3. High-level API layer: Provides ready-to-use components for common tasks, such as AuthSource for authentication, QueryParser/PortalStore for extended queries, and ConnectionManager for query cancellation.

The DecodeContext struct is used during the decoding process to track the current state of the connection. This is critical for handling messages that depend on the connection phase, such as SSL/GSS negotiation or the initial startup sequence.

Key fields include:

• protocol_version: The ProtocolVersion currently in use.
• awaiting_frontend_ssl: True if the connection is waiting for SSL negotiation.
• awaiting_frontend_startup: True if the connection is waiting for a startup message.
• awaiting_backend_ssl_response: True if the backend is waiting for an SSL response.
• awaiting_backend_gss_response: True if the backend is waiting for a GSS encryption response.

let mut ctx = DecodeContext::default();
// ctx.awaiting_frontend_ssl is true by default
// ctx.awaiting_frontend_startup is true by default

The MaybeTls enum is a wrapper that allows the server to treat plain TCP, Unix domain sockets, and TLS-encrypted streams uniformly. It implements AsyncRead and AsyncWrite, enabling the PgWireMessageServerCodec to operate on any of these underlying transport types without knowing if the connection is encrypted.

#[non_exhaustive]
pub enum MaybeTls {
    Plain(TcpStream),
    #[cfg(unix)]
    Unix(UnixStream),
    #[cfg(any(feature = "_ring", feature = "_aws-lc-rs"))]
    Tls(Box<TlsStream<TcpStream>>),
}