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.

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.

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

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

Export data using raw COPY TO STDOUT, returning raw bytes. Format: tab-separated values, newline-terminated rows. Suitable for direct re-import via copy_in_raw.

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.

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

Send raw bytes to the stream.

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. This is the only syscall in the buffered write path.

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

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.