Struct PgConnection 

pub struct PgConnection { /* private fields */ }

A raw PostgreSQL connection.

Implementations

impl PgConnection

pub fn get_cancel_key_bytes(&self) -> (i32, &[u8])

Get the full cancel key bytes for this connection.

pub fn get_cancel_key(&self) -> (i32, i32)

Legacy cancel key accessor (process_id, secret_key_i32).

Compatibility-only: valid for protocol 3.0 4-byte cancel keys. For protocol 3.2 extended keys, this returns (process_id, 0).

pub async fn cancel_query_bytes( host: &str, port: u16, process_id: i32, secret_key: &[u8], ) -> PgResult<()>

Cancel a running query using bytes-native cancel key.

pub async fn cancel_query( host: &str, port: u16, process_id: i32, secret_key: i32, ) -> PgResult<()>

Legacy i32 cancel API wrapper (protocol 3.0-style 4-byte key).

impl PgConnection

pub async fn connect( host: &str, port: u16, user: &str, database: &str, ) -> PgResult<Self>

Connect to PostgreSQL server without authentication (trust mode).

Arguments

• host — PostgreSQL server hostname or IP.
• port — TCP port (typically 5432).
• user — PostgreSQL role name.
• database — Target database name.

pub async fn connect_with_password( host: &str, port: u16, user: &str, database: &str, password: Option<&str>, ) -> PgResult<Self>

Connect to PostgreSQL server with optional password authentication. Includes a default 10-second timeout covering TCP connect + handshake.

Startup requests protocol 3.2 by default and performs a one-shot retry with protocol 3.0 only when startup fails due to explicit protocol-version rejection from the server.

pub async fn connect_with_options( host: &str, port: u16, user: &str, database: &str, password: Option<&str>, options: ConnectOptions, ) -> PgResult<Self>

Connect to PostgreSQL with explicit enterprise options.

Negotiation preface order follows libpq:

1. If gss_enc_mode != Disable → try GSSENCRequest on fresh TCP
2. If GSSENC rejected/unavailable and tls_mode != Disable → try SSLRequest
3. If both rejected/unavailable → plain StartupMessage

The StartupMessage protocol version behavior is the same as connect_with_password: request protocol 3.2 first, then retry once with 3.0 only on explicit protocol-version rejection.

pub async fn connect_with_password_and_auth( host: &str, port: u16, user: &str, database: &str, password: Option<&str>, auth_settings: AuthSettings, ) -> PgResult<Self>

Connect to PostgreSQL server with optional password authentication and auth policy.

pub async fn connect_tls( host: &str, port: u16, user: &str, database: &str, password: Option<&str>, ) -> PgResult<Self>

Connect to PostgreSQL server with TLS encryption. Includes a default 10-second timeout covering TCP connect + TLS + handshake.

pub async fn connect_tls_with_auth( host: &str, port: u16, user: &str, database: &str, password: Option<&str>, auth_settings: AuthSettings, ca_cert_pem: Option<&[u8]>, ) -> PgResult<Self>

Connect to PostgreSQL over TLS with explicit auth policy and optional custom CA bundle.

pub async fn connect_mtls( host: &str, port: u16, user: &str, database: &str, config: TlsConfig, ) -> PgResult<Self>

Connect with mutual TLS (client certificate authentication).

Arguments

• host - PostgreSQL server hostname
• port - PostgreSQL server port
• user - Database user
• database - Database name
• config - TLS configuration with client cert/key

Example

let config = TlsConfig {
    client_cert_pem: include_bytes!("client.crt").to_vec(),
    client_key_pem: include_bytes!("client.key").to_vec(),
    ca_cert_pem: Some(include_bytes!("ca.crt").to_vec()),
};
let conn = PgConnection::connect_mtls("localhost", 5432, "user", "db", config).await?;

pub async fn connect_mtls_with_password_and_auth( host: &str, port: u16, user: &str, database: &str, password: Option<&str>, config: TlsConfig, auth_settings: AuthSettings, ) -> PgResult<Self>

Connect with mutual TLS and optional password fallback.

pub async fn connect_unix( socket_path: &str, user: &str, database: &str, password: Option<&str>, ) -> PgResult<Self>

Connect to PostgreSQL server via Unix domain socket.

impl PgConnection

pub async fn close(self) -> PgResult<()>

Gracefully close the connection by sending a Terminate message. This tells the server we’re done and allows proper cleanup.

impl PgConnection

pub fn requested_protocol_minor(&self) -> u16

Startup protocol minor requested by this connection.

pub fn negotiated_protocol_minor(&self) -> u16

Startup protocol minor negotiated with the server.

impl PgConnection

pub async fn copy_in_raw( &mut self, table: &str, columns: &[String], data: &[u8], ) -> PgResult<u64>

Fastest bulk insert using COPY protocol with pre-encoded data. Accepts raw COPY text format bytes, no encoding needed. Use when caller has already encoded rows to COPY format.

Format

Data should be tab-separated rows with newlines: 1\thello\t3.14\n2\tworld\t2.71\n

pub async fn copy_export(&mut self, cmd: &Qail) -> PgResult<Vec<Vec<String>>>

Export data using COPY TO STDOUT (AST-native). Takes a Qail::Export and returns rows as Vec<Vec<String>>.

Example

let cmd = Qail::export("users")
    .columns(["id", "name"])
    .filter("active", true);
let rows = conn.copy_export(&cmd).await?;

pub async fn copy_export_stream_raw<F, Fut>( &mut self, cmd: &Qail, on_chunk: F, ) -> PgResult<()>

where F: FnMut(Vec<u8>) -> Fut, Fut: Future<Output = PgResult<()>>,

Stream COPY TO STDOUT chunks using an AST-native Qail::Export command.

Chunks are forwarded as they arrive from PostgreSQL, so memory usage stays bounded by network frame size and callback processing.

pub async fn copy_export_stream_rows<F>( &mut self, cmd: &Qail, on_row: F, ) -> PgResult<()>

where F: FnMut(Vec<String>) -> PgResult<()>,

Stream COPY TO STDOUT rows using an AST-native Qail::Export command.

Parses PostgreSQL COPY text lines into Vec<String> rows and invokes on_row for each row without buffering the full result.

impl PgConnection

pub async fn send(&mut self, msg: FrontendMessage) -> PgResult<()>

Send a frontend message.

pub async fn recv(&mut self) -> PgResult<BackendMessage>

Loops until a complete message is available. Automatically buffers NotificationResponse messages for LISTEN/NOTIFY.

pub async fn send_bytes(&mut self, bytes: &[u8]) -> PgResult<()>

Send raw bytes to the stream. Includes flush for TLS safety — TLS buffers internally and needs flush to push encrypted data to the underlying TCP socket.

pub fn buffer_bytes(&mut self, bytes: &[u8])

Buffer bytes for later flush (NO SYSCALL). Use flush_write_buf() to send all buffered data.

pub async fn flush_write_buf(&mut self) -> PgResult<()>

Flush the write buffer to the stream (single write_all + flush). The flush is critical for TLS connections.

impl PgConnection

pub async fn listen(&mut self, channel: &str) -> PgResult<()>

Subscribe to a notification channel.

conn.listen("price_calendar_changed").await?;

pub async fn unlisten(&mut self, channel: &str) -> PgResult<()>

Unsubscribe from a notification channel.

pub async fn unlisten_all(&mut self) -> PgResult<()>

Unsubscribe from all notification channels.

pub fn poll_notifications(&mut self) -> Vec<Notification>

Drain all buffered notifications without blocking.

Notifications arrive asynchronously from PostgreSQL and are buffered whenever recv() encounters a NotificationResponse. This method returns all currently buffered notifications.

pub async fn recv_notification(&mut self) -> PgResult<Notification>

Wait for the next notification, blocking until one arrives.

Unlike recv(), this does NOT use the 30-second Slowloris timeout guard. LISTEN connections idle for long periods — that’s normal, not a DoS attack.

Useful for a dedicated LISTEN connection in a background task.

impl PgConnection

pub async fn query_pipeline( &mut self, queries: &[(&str, &[Option<Vec<u8>>])], ) -> PgResult<Vec<Vec<Vec<Option<Vec<u8>>>>>>

Execute multiple SQL queries in a single network round-trip (PIPELINING).

pub async fn pipeline_ast( &mut self, cmds: &[Qail], ) -> PgResult<Vec<Vec<Vec<Option<Vec<u8>>>>>>

Execute multiple Qail ASTs in a single network round-trip.

pub async fn pipeline_ast_fast(&mut self, cmds: &[Qail]) -> PgResult<usize>

FAST AST pipeline - returns only query count, no result parsing.

pub async fn pipeline_bytes_fast( &mut self, wire_bytes: &[u8], expected_queries: usize, ) -> PgResult<usize>

FASTEST extended query pipeline - takes pre-encoded wire bytes.

pub async fn pipeline_simple_fast(&mut self, cmds: &[Qail]) -> PgResult<usize>

Simple query protocol pipeline - uses ‘Q’ message.

pub async fn pipeline_simple_bytes_fast( &mut self, wire_bytes: &[u8], expected_queries: usize, ) -> PgResult<usize>

FASTEST simple query pipeline - takes pre-encoded bytes.

pub async fn pipeline_ast_cached(&mut self, cmds: &[Qail]) -> PgResult<usize>

CACHED PREPARED STATEMENT pipeline - Parse once, Bind+Execute many.

1. Generate SQL template with $1, $2, etc. placeholders
2. Parse template ONCE (cached in PostgreSQL)
3. Send Bind+Execute for each instance (params differ per query)

pub async fn pipeline_prepared_fast( &mut self, stmt: &PreparedStatement, params_batch: &[Vec<Option<Vec<u8>>>], ) -> PgResult<usize>

ZERO-LOOKUP prepared statement pipeline.

• Hash computation per query
• HashMap lookup per query
• String allocation for stmt_name

Example

// Prepare once (outside timing loop):
let stmt = PreparedStatement::from_sql("SELECT id, name FROM harbors LIMIT $1");
let params_batch: Vec<Vec<Option<Vec<u8>>>> = (1..=1000)
    .map(|i| vec![Some(i.to_string().into_bytes())])
    .collect();
// Execute many (no hash, no lookup!):
conn.pipeline_prepared_fast(&stmt, &params_batch).await?;

pub async fn prepare(&mut self, sql: &str) -> PgResult<PreparedStatement>

Prepare a statement and return a handle for fast execution. PreparedStatement handle for use with pipeline_prepared_fast.

pub async fn pipeline_prepared_results( &mut self, stmt: &PreparedStatement, params_batch: &[Vec<Option<Vec<u8>>>], ) -> PgResult<Vec<Vec<Vec<Option<Vec<u8>>>>>>

Execute a prepared statement pipeline and return all row data.

pub async fn pipeline_prepared_zerocopy( &mut self, stmt: &PreparedStatement, params_batch: &[Vec<Option<Vec<u8>>>], ) -> PgResult<Vec<Vec<Vec<Option<Bytes>>>>>

ZERO-COPY pipeline execution with Bytes for column data.

pub async fn pipeline_prepared_ultra( &mut self, stmt: &PreparedStatement, params_batch: &[Vec<Option<Vec<u8>>>], ) -> PgResult<Vec<Vec<(Bytes, Bytes)>>>

ULTRA-FAST pipeline for 2-column SELECT queries.

impl PgConnection

pub async fn query_cached( &mut self, sql: &str, params: &[Option<Vec<u8>>], ) -> PgResult<Vec<Vec<Option<Vec<u8>>>>>

Execute a query with cached prepared statement. Like query(), but reuses prepared statements across calls. The statement name is derived from a hash of the SQL text. OPTIMIZED: Pre-allocated buffer + ultra-fast encoders.

pub async fn query_cached_with_result_format( &mut self, sql: &str, params: &[Option<Vec<u8>>], result_format: i16, ) -> PgResult<Vec<Vec<Option<Vec<u8>>>>>

Execute a query with cached prepared statement and explicit result-column format.

pub async fn execute_simple(&mut self, sql: &str) -> PgResult<()>

Execute a simple SQL statement (no parameters).

pub async fn simple_query(&mut self, sql: &str) -> PgResult<Vec<PgRow>>

Execute a simple SQL query and return rows (Simple Query Protocol).

Unlike execute_simple, this collects and returns data rows. Used for branch management and other administrative queries.

SECURITY: Capped at 10,000 rows to prevent OOM from unbounded results.

pub async fn query_prepared_single( &mut self, stmt: &PreparedStatement, params: &[Option<Vec<u8>>], ) -> PgResult<Vec<Vec<Option<Vec<u8>>>>>

ZERO-HASH sequential query using pre-computed PreparedStatement. This is the FASTEST sequential path because it skips:

• SQL generation from AST (done once outside loop)
• Hash computation for statement name (pre-computed in PreparedStatement)
• HashMap lookup for is_new check (statement already prepared)

Example

let stmt = conn.prepare("SELECT * FROM users WHERE id = $1").await?;
for id in 1..10000 {
    let rows = conn.query_prepared_single(&stmt, &[Some(id.to_string().into_bytes())]).await?;
}

pub async fn query_prepared_single_with_result_format( &mut self, stmt: &PreparedStatement, params: &[Option<Vec<u8>>], result_format: i16, ) -> PgResult<Vec<Vec<Option<Vec<u8>>>>>

ZERO-HASH sequential query with explicit result-column format.

impl PgConnection

pub async fn identify_system(&mut self) -> PgResult<IdentifySystem>

Run IDENTIFY_SYSTEM on a replication connection.

pub async fn create_logical_replication_slot( &mut self, slot_name: &str, output_plugin: &str, temporary: bool, two_phase: bool, ) -> PgResult<ReplicationSlotInfo>

Create a logical replication slot.

slot_name and output_plugin are strict SQL identifiers.

pub async fn drop_replication_slot( &mut self, slot_name: &str, wait: bool, ) -> PgResult<()>

Drop a replication slot.

wait=true uses DROP_REPLICATION_SLOT <slot> WAIT.

pub async fn start_logical_replication( &mut self, slot_name: &str, start_lsn: &str, options: &[ReplicationOption], ) -> PgResult<ReplicationStreamStart>

Start logical replication in CopyBoth mode.

Requires a connection started with replication=database.

pub async fn recv_replication_message( &mut self, ) -> PgResult<ReplicationStreamMessage>

Receive the next logical replication stream message.

Uses a no-timeout read path so idle periods do not fail the stream.

pub async fn send_standby_status_update( &mut self, write_lsn: u64, flush_lsn: u64, apply_lsn: u64, reply_requested: bool, ) -> PgResult<()>

Send a standby status update (CopyData('r' ...)) to the server.

impl PgConnection

pub async fn begin_transaction(&mut self) -> PgResult<()>

Begin a new transaction. After calling this, all queries run within the transaction until commit() or rollback() is called.

pub async fn commit(&mut self) -> PgResult<()>

Commit the current transaction. Makes all changes since begin_transaction() permanent.

pub async fn rollback(&mut self) -> PgResult<()>

Rollback the current transaction. Discards all changes since begin_transaction().

pub async fn savepoint(&mut self, name: &str) -> PgResult<()>

Create a named savepoint within the current transaction. Savepoints allow partial rollback within a transaction. Use rollback_to() to return to this savepoint.

pub async fn rollback_to(&mut self, name: &str) -> PgResult<()>

Rollback to a previously created savepoint. Discards all changes since the named savepoint was created, but keeps the transaction open.

pub async fn release_savepoint(&mut self, name: &str) -> PgResult<()>

Release a savepoint (free resources, if no longer needed).

Trait Implementations

impl Drop for PgConnection

Drop implementation sends Terminate packet if possible. This ensures proper cleanup even without explicit close() call.

fn drop(&mut self)

Executes the destructor for this type.