Crate pg_stream

Crate pg_stream 

Source
Expand description

PgStream.

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 fluent API on PgStream
  • Frame reading from backend responses

§Example: Simple Query

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

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.put_query("SELECT 1")
    .flush()
    .await?;

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

§Example: Prepared Statements

// Parse a prepared statement
conn.put_parse("stmt", "SELECT $1::int", &[ParameterKind::Int4])
    .flush()
    .await?;

// Bind and execute
conn.put_bind("", "stmt", &[BindParameter::Text("42".to_string())], ResultFormat::Text)
    .put_execute("", None)
    .put_sync()
    .flush()
    .await?;

§Example: Function Calls

// Call sqrt(9) - note that OID 1344 may vary by Postgres version
conn.put_fn_call(1344, &[FunctionArg::Text("9".to_string())], FormatCode::Text)
    .flush()
    .await?;

§Protocol Messages

The crate provides methods for constructing all major frontend protocol messages:

§Authentication

Currently supported authentication modes:

  • [AuthenticationMode::Trust] - No authentication
  • [AuthenticationMode::Password] - Cleartext password

Other authentication methods (SASL, SCRAM, MD5, Kerberos, etc.) are not yet implemented and will return an error or panic.

§TLS Support

TLS can be negotiated using [ConnectionBuilder::connect_with_tls] with a custom async upgrade function. The builder handles SSL request negotiation with the server.

§Format Codes

The protocol supports text and binary formats for parameters and results. The crate automatically optimizes format code encoding:

  • If all parameters use text format (the default), no format codes are sent
  • If all parameters use the same format, a single format code is sent
  • Otherwise, individual format codes are sent for each parameter

§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

§Feature Flags

Currently, this crate has no optional features.

Modules§

messages
startup

Structs§

PgErrorResponse
A zero-copy representation of a Postgres ErrorResponse or NoticeResponse
PgStream
High-level Postgres protocol stream with type-safe message construction.
PgStreamProto
A low level Postgres protocol stream with buffered message building.