Struct AsyncClient 

pub struct AsyncClient { /* private fields */ }

An asynchronous client for Hyper database.

This is the async equivalent of Client, designed for use in tokio-based async applications. All I/O operations are non-blocking.

Example

use hyperdb_api_core::client::{AsyncClient, Config};

#[tokio::main]
async fn main() -> hyperdb_api_core::client::Result<()> {
    let config = Config::new()
        .with_host("localhost")
        .with_port(7483)
        .with_database("test.hyper");

    let client = AsyncClient::connect(&config).await?;
    let rows = client.query("SELECT 1").await?;
    client.close().await?;
    Ok(())
}

Implementations

impl AsyncClient

pub async fn connect(config: &Config) -> Result<Self>

Connects to a Hyper server using the given configuration (async).

Example

let config = Config::new()
    .with_host("localhost")
    .with_port(7483)
    .with_database("test.hyper");

let client = AsyncClient::connect(&config).await?;

Errors

• Returns Error (connection) if the TCP connection cannot be established to config.host():config.port().
• Propagates any Error from the startup handshake — Error (auth) for missing/wrong credentials, Error (server) for server-side startup errors, Error (protocol) for out-of-sequence messages, or Error (I/O) for wire failure.

pub async fn connect_unix( socket_path: impl AsRef<Path>, config: &Config, ) -> Result<Self>

Connects to a Hyper server via Unix Domain Socket (async, Unix only).

Example

let socket_path = Path::new("/tmp/hyper/.s.PGSQL.12345");
let config = Config::new().with_database("test.hyper");
let client = AsyncClient::connect_unix(socket_path, &config).await?;

Errors

• Returns Error (connection) if the Unix domain socket cannot be connected.
• Propagates any error from the startup handshake (see Self::connect).

pub async fn connect_endpoint( endpoint: &ConnectionEndpoint, config: &Config, ) -> Result<Self>

Connects to a Hyper server using a ConnectionEndpoint (async).

This is a lower-level method that accepts a pre-parsed endpoint.

Errors

Delegates to Self::connect, Self::connect_unix, or Self::connect_named_pipe depending on the endpoint variant, and propagates their errors unchanged.

pub fn endpoint(&self) -> &ConnectionEndpoint

Returns the connection endpoint.

pub fn process_id(&self) -> i32

Returns the server process ID for this connection.

pub fn secret_key(&self) -> i32

Returns the secret key for cancel requests.

pub async fn cancel(&self) -> Result<()>

Cancels the currently executing query on this connection (async).

This method opens a separate connection to send a cancel request. For TCP endpoints, it opens a new TCP connection. For Unix domain sockets, it connects to the same socket path.

Errors

• Returns Error (connection) if a fresh cancel-side socket (TCP / UDS / named-pipe) cannot be opened to Self::endpoint.
• Returns Error (I/O) if writing the cancel request fails.

pub async fn query(&self, sql: &str) -> Result<Vec<Row>>

Executes a query and returns all result rows (async).

Errors

Propagates any Error from the underlying connection’s AsyncRawConnection::simple_query — Error (server) for server-side SQL errors, Error (I/O) / Error (closed) for transport failures, and Error (connection) if the connection is unhealthy. Row construction may also raise an Error when a DataRow cannot be decoded against its RowDescription.

pub async fn query_fast(&self, sql: &str) -> Result<Vec<StreamRow>>

Executes a query with HyperBinary format for better performance (async).

Errors

Same failure modes as Self::query.

pub async fn query_streaming( &self, sql: &str, chunk_size: usize, ) -> Result<AsyncQueryStream<'_>>

Executes a query with HyperBinary format and returns a streaming result reader (async).

This is the async mirror of Client::query_streaming. The returned AsyncQueryStream yields rows in chunks so callers can process arbitrarily large result sets with constant memory. The connection mutex is held for the duration of iteration; dropping the stream before completion issues a best-effort cancel and marks the connection desynchronized.

Errors

• Returns Error (connection) if the connection is unhealthy.
• Returns Error (I/O) if writing the Parse/Bind/Execute/Sync sequence fails on the transport.

pub async fn exec(&self, sql: &str) -> Result<u64>

Executes a command (INSERT/UPDATE/DELETE/DDL) and returns affected row count (async).

Errors

Same failure modes as Self::query — server-side SQL errors, transport failures, and unhealthy-connection state all surface as Error.

pub async fn parameter_status(&self, name: &str) -> Option<String>

Returns a server parameter value by name.

pub fn set_notice_receiver( &mut self, receiver: Option<Box<dyn Fn(Notice) + Send + Sync>>, )

Sets the notice receiver callback.

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

Closes the connection gracefully (async).

Errors

Returns Error (I/O) if writing the Terminate frame or flushing the async transport fails.

pub async fn batch_execute(&self, sql: &str) -> Result<()>

Executes a batch of statements separated by semicolons (async).

Errors

Same failure modes as Self::query.

pub async fn copy_in( &self, table_name: &str, columns: &[&str], ) -> Result<AsyncCopyInWriter<'_>>

Starts a COPY IN operation for bulk data insertion (async).

Errors

Delegates to Self::copy_in_with_format; see that method for concrete failure modes.

pub async fn copy_in_arc_with_format( &self, table_name: &str, columns: &[&str], format: &str, ) -> Result<AsyncCopyInWriterOwned>

Starts a COPY IN operation and returns an owned-handle writer whose lifetime is independent of this client. The writer holds an Arc-cloned reference to the underlying connection mutex, so it can be stored in structs that need a 'static-lifetime writer — e.g. N-API classes that can’t carry borrowed references across JS callbacks.

Errors

Same failure modes as Self::copy_in_with_format.

pub async fn copy_in_with_format( &self, table_name: &str, columns: &[&str], format: &str, ) -> Result<AsyncCopyInWriter<'_>>

Starts a COPY IN operation with a specified data format (async).

Errors

• Returns Error (connection) if the connection is unhealthy.
• Returns Error (server) if the server rejects the generated COPY ... FROM STDIN statement.
• Returns Error (I/O) on transport read/write failure.

pub async fn copy_out(&self, query: &str) -> Result<Vec<u8>>

Executes a COPY … TO STDOUT query and returns all output data (async).

Errors

• Returns Error (connection) if the connection is unhealthy.
• Returns Error (server) when the server rejects the statement.
• Returns Error (I/O) / Error (closed) on transport read/write failure.

pub fn is_alive(&self) -> bool

Returns true if the connection is alive.

pub async fn prepare(&self, query: &str) -> Result<AsyncPreparedStatement>

Prepares a statement for execution (async).

Errors

Delegates to Self::prepare_typed; see that method for the failure modes.

pub async fn prepare_typed( &self, query: &str, param_types: &[Oid], ) -> Result<AsyncPreparedStatement>

Prepares a statement with explicit parameter types (async).

Errors

• Returns Error (connection) if the connection is unhealthy.
• Returns Error (server) if the server rejects the Parse request (SQL syntax, unknown parameter OIDs, etc.).
• Returns Error (I/O) on transport read/write failure.

pub async fn close_statement( &self, statement: &AsyncPreparedStatement, ) -> Result<()>

Closes a prepared statement on the server (async).

Prefer the RAII AsyncPreparedStatement::close method on the statement itself — it consumes the statement and prevents the auto-close Drop path from double-closing.

Errors

Propagates any error from AsyncRawConnection::close_statement — unhealthy connection, server-side error during Close/Sync, or transport failure.

pub async fn execute_prepared<P: AsRef<[Option<Vec<u8>>]>>( &self, statement: &AsyncPreparedStatement, params: P, ) -> Result<Vec<Row>>

Executes a prepared statement with parameters (async).

Errors

Propagates any error from AsyncRawConnection::execute_prepared — unhealthy connection, parameter/type mismatch, server-side execution failure, or transport failure. Row construction may also raise an Error when a DataRow cannot be decoded.

pub async fn execute_prepared_no_result<P: AsRef<[Option<Vec<u8>>]>>( &self, statement: &AsyncPreparedStatement, params: P, ) -> Result<u64>

Executes a prepared statement that doesn’t return rows (async).

Errors

Same failure modes as Self::execute_prepared (excluding row-construction errors — this path never builds rows).

pub async fn execute_prepared_streaming<'a, P: AsRef<[Option<Vec<u8>>]>>( &'a self, statement: &AsyncPreparedStatement, params: P, chunk_size: usize, ) -> Result<AsyncPreparedQueryStream<'a>>

Executes a prepared statement with streaming results (async).

Returns an AsyncPreparedQueryStream that yields rows in chunks, keeping memory bounded regardless of result size. Async mirror of Client::execute_streaming.

Errors

• Returns Error (connection) if the connection is unhealthy.
• Returns Error (I/O) if writing the initial Bind/Execute/Sync sequence fails on the transport.

Trait Implementations

impl Cancellable for AsyncClient

fn cancel(&self)

Fire-and-forget cancel via PG wire protocol CancelRequest on a fresh connection. Uses synchronous I/O so it is callable from Drop impls. Errors are logged and swallowed because cancellation is best-effort and callers cannot meaningfully recover.

impl Debug for AsyncClient

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.