Struct GrpcConnection 

pub struct GrpcConnection { /* private fields */ }

A gRPC connection to a Hyper database (query-only).

Unlike Connection, this provides read-only access via gRPC with results in Apache Arrow IPC format. This is useful for:

• Load-balanced deployments where gRPC provides better routing
• Integration with Arrow-based data pipelines
• Scenarios where HTTP/2 benefits are needed

Limitations

gRPC connections only support SELECT queries. Attempting to execute DDL (CREATE, DROP), DML (INSERT, UPDATE, DELETE), or use features like prepared statements will result in an error.

Async vs Sync

This struct provides both async and sync APIs:

• connect() / execute_query() - blocking (uses internal tokio runtime)
• connect_async() / execute_query_async() - async (requires tokio runtime)

For applications already using tokio, the async methods are preferred.

Implementations

impl GrpcConnection

pub fn connect(endpoint: &str, database_path: &str) -> Result<Self>

Connects to a Hyper server via gRPC (blocking).

Arguments

• endpoint - The gRPC endpoint URL (e.g., “http://localhost:7484”)
• database_path - Path to the database to query

Example

let conn = GrpcConnection::connect(
    "http://localhost:7484",
    "my_database.hyper"
)?;

Errors

Returns crate::Error::Client wrapping a hyperdb_api_core::client::Error if the HTTP/2 channel cannot be established (endpoint unreachable, TLS handshake failure, auth rejection).

pub fn connect_with_config(config: GrpcConfig) -> Result<Self>

Connects to a Hyper server via gRPC with custom configuration (blocking).

Example

let config = GrpcConfig::new("http://localhost:7484")
    .database("my_database.hyper")
    .connect_timeout(Duration::from_secs(10))
    .header("x-custom-header", "value");

let conn = GrpcConnection::connect_with_config(config)?;

Errors

Returns crate::Error::Client if the HTTP/2 channel cannot be established with the supplied configuration.

pub fn execute_query_to_arrow(&mut self, sql: &str) -> Result<Bytes>

Executes a SQL query and returns raw Arrow IPC bytes (blocking).

This is the most efficient method when you need the raw Arrow data for processing with an Arrow library.

Example

let arrow_bytes = conn.execute_query_to_arrow("SELECT * FROM users")?;

// Process with arrow crate using the zero-copy helper
let rowset = hyperdb_api::ArrowRowset::from_bytes(arrow_bytes)?;

Errors

Returns crate::Error::Client if the gRPC server rejects the query or if the HTTP/2 channel fails mid-stream.

pub fn execute_query(&mut self, sql: &str) -> Result<GrpcQueryResult>

Executes a SQL query and returns a structured result (blocking).

The result contains the Arrow IPC data along with metadata about the query execution.

Example

let result = conn.execute_query("SELECT id, name FROM users")?;
println!("Query ID: {:?}", result.query_id());
println!("Columns: {}", result.column_count());
let arrow_data = result.into_arrow_data();

Errors

Returns crate::Error::Client if the gRPC server rejects the query or the HTTP/2 channel fails.

pub fn cancel_query(&mut self, query_id: &str) -> Result<()>

Cancels an in-flight gRPC query by its query_id (blocking).

This is the gRPC analogue of PG wire’s CancelRequest. Unlike PG wire — where the cancel opens a separate TCP connection — the gRPC cancel rides the existing HTTP/2 channel as a regular RPC, so it reuses this connection’s channel, database routing, and custom headers.

When you have a query_id

The server assigns a query_id for ASYNC-mode queries (long-running queries that the client polls). Read it from GrpcQueryResult::query_id after an async-mode execution. SYNC-mode queries typically complete before a cancel would be useful — drop the in-flight future instead.

Cancellation is best-effort: a successful Ok(()) return means the server acknowledged the cancel, not that the query had not already finished. Errors indicate a transport-level failure (channel closed, network error, auth expired) — useful for metrics, retry logic, or “cancel failed” UX.

Fallible by design

The Result<()> return is the explicit user-facing cancel API and is distinct from the Cancellable trait, which requires an infallible cancel(&self) method with no arguments. A GrpcConnection cannot implement Cancellable directly: the trait’s signature has nowhere to pass a query_id, and gRPC connections can carry many concurrent queries (so there is no unambiguous “the” query to cancel the way there is on a PG wire connection). If you need Cancellable-style fire-and-forget cancel for a future gRPC streaming result type, it will live on a per-query handle that wraps this method and swallows errors — mirroring impl Cancellable for hyperdb_api_core::client::Client.

Example

conn.cancel_query(query_id)?;

Errors

Returns crate::Error::Client on transport-level failures (channel closed, network error, auth expired). An unknown or already-finished query_id is not an error — the server returns Ok.

pub fn database(&self) -> Option<&str>

Returns the database path, if one is attached.

pub fn config(&self) -> &GrpcConfig

Returns the gRPC configuration.

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

Closes the connection (blocking).

Note: The connection is automatically closed when dropped.

Errors

Returns crate::Error::Client if the underlying HTTP/2 channel cannot be shut down cleanly.

Trait Implementations

impl Debug for GrpcConnection

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

Formats the value using the given formatter.