Struct PgConnection 

pub struct PgConnection { /* private fields */ }

A raw PostgreSQL connection.

Implementations

impl PgConnection

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

Get the cancel key for this connection.

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

Cancel a running query on a PostgreSQL backend. This opens a new TCP connection and sends a CancelRequest message. The original connection continues running but the query is interrupted.

impl PgConnection

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

Connect to PostgreSQL server without authentication (trust mode).

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.

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_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_unix( socket_path: &str, user: &str, database: &str, password: Option<&str>, ) -> PgResult<Self>

Connect to PostgreSQL server via Unix domain socket.

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 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>.

Example

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

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 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 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?;
}

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).

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.

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.