Skip to main content

Crate pg_stream

Crate pg_stream 

Source
Expand description

PgStream - Low-level Postgres wire protocol library.

This crate provides direct access to the Postgres frontend/backend protocol, allowing you to build custom database clients or tools without the overhead of higher-level abstractions.

§Overview

The crate is organized around a few core concepts:

  • Connection establishment via [ConnectionBuilder] with support for authentication and TLS
  • Message construction using the PgProtocol extension trait on any buffer
  • Frame reading from backend responses via PgConnection

§Example: Simple Query

use pg_stream::startup::{ConnectionBuilder, AuthenticationMode};
use pg_stream::PgProtocol;

let stream = tokio::net::TcpStream::connect("localhost:5432").await?;

let (mut conn, startup) = ConnectionBuilder::new("postgres")
    .database("mydb")
    .auth(AuthenticationMode::Password("secret".into()))
    .connect(stream)
    .await?;

// Execute a query
conn.query("SELECT 1");
conn.flush().await?;

// Read responses
loop {
    let frame = conn.recv().await?;
    // Process frame...
}

§Example: Prepared Statements

// Parse a prepared statement
conn.parse(Some("stmt"))
    .query("SELECT $1::int")
    .param_types(&[oid::INT4])
    .finish();
conn.flush().await?;

// Bind and execute
conn.bind(Some("stmt"))
    .finish(&[&42i32 as &dyn Bindable])
    .execute(None, 0)
    .sync();
conn.flush().await?;

§Protocol Messages

The PgProtocol trait provides methods for constructing all major frontend protocol messages on any buffer implementing BufMut:

§Authentication

Currently supported authentication modes:

§TLS Support

TLS can be negotiated using ConnectionBuilder::connect_with_tls with a custom async upgrade function.

§Performance Considerations

This crate is designed for low-level control and maximum performance:

  • Messages are buffered and sent together to minimize syscalls
  • Direct buffer manipulation with bytes::BytesMut
  • No unnecessary allocations in protocol framing
  • Zero-copy reads where possible

§Safety and Error Handling

This is a low-level crate with minimal safety guarantees:

  • No SQL injection protection - sanitize your inputs
  • Manual resource management - close your statements and portals
  • No connection pooling - manage connections yourself

Re-exports§

pub use connection::PgConnection;
pub use message::PgProtocol;

Modules§

auth
Authentication implementations for Postgres connections.
connection
Postgres connection handling.
message
Postgres wire protocol message encoding and decoding.
startup

Macros§

pg_frame
Encode a framed frontend message with a single-pass write.

Structs§

ErrorResponse
A zero-copy wrapper for an ErrorResponse message.

Enums§

PgMessage
A parsed PostgreSQL backend message.