Module grpc 

gRPC transport for Hyper database.

This module provides gRPC-based connectivity to Hyper servers as an alternative to the PostgreSQL wire protocol over TCP.

gRPC transport is always available - no feature flags required.

Architecture

The gRPC transport uses Protocol Buffers for message serialization and returns query results in Apache Arrow IPC format. This provides:

• Better support for load balancing
• Built-in streaming for large result sets
• HTTP/2 multiplexing
• Easier integration with service meshes

Limitations

The gRPC interface is read-only:

• Only SELECT queries are supported
• No INSERT, UPDATE, DELETE, or DDL operations
• No COPY protocol for bulk data insertion

For write operations, use the standard TCP connection.

Message Size Limits

By default, the client uses a 64 MB message size limit (DEFAULT_MAX_MESSAGE_SIZE). This is important when using TransferMode::Sync, which returns all results in a single gRPC response. For TransferMode::Adaptive (default) or TransferMode::Async, results are streamed in smaller chunks, making large message sizes less critical.

use hyperdb_api_core::client::grpc::{GrpcConfig, TransferMode};

// For SYNC mode with large results, increase the limit
let config = GrpcConfig::new("http://localhost:7484")
    .database("large_data.hyper")
    .transfer_mode(TransferMode::Sync)
    .max_message_size(256 * 1024 * 1024); // 256 MB

Parameterized Queries

gRPC supports parameterized queries using QueryParameters and ParameterStyle:

use hyperdb_api_core::client::grpc::{GrpcClient, GrpcConfig, QueryParameters, ParameterStyle};

let mut client = GrpcClient::connect(config).await?;

// Dollar-numbered parameters ($1, $2, ...) - use from_json_value for mixed types
let params = QueryParameters::from_json_value(&serde_json::json!([42, "Alice"]))?;
let result = client.execute_query_with_params(
    "SELECT * FROM users WHERE id = $1 AND name = $2",
    params,
    ParameterStyle::DollarNumbered,
).await?;

// Named parameters (:id, :name, ...)
let params = QueryParameters::json_named()
    .add("id", &42i64)?
    .add("name", &"Alice")?
    .build();
let result = client.execute_query_with_params(
    "SELECT * FROM users WHERE id = :id AND name = :name",
    params,
    ParameterStyle::Named,
).await?;

Example

use hyperdb_api_core::client::grpc::{GrpcClient, GrpcConfig};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = GrpcConfig::new("http://localhost:7484")
        .database("my_database.hyper");

    let mut client = GrpcClient::connect(config).await?;

    // Execute a query and get Arrow IPC bytes
    let arrow_data = client.execute_query_to_arrow("SELECT * FROM users").await?;

    // Or get parsed results
    let result = client.execute_query("SELECT id, name FROM users").await?;
    // Process Arrow data...

    Ok(())
}

Structs

GrpcChunkStream

Streaming producer of Arrow IPC byte chunks from a gRPC query.

GrpcChunkStreamSync

Blocking wrapper around GrpcChunkStream.

GrpcClient

Async gRPC client for Hyper database.

GrpcClientSync

Synchronous wrapper around GrpcClient.

GrpcColumnInfo

Column information from a gRPC query result.

GrpcConfig

Configuration for gRPC connections to Hyper servers.

GrpcError

gRPC-specific error information.

GrpcQueryResult

Result of a gRPC query execution.

GrpcResultChunk

A single chunk of gRPC query results.

JsonNamedParamsBuilder

Builder for named JSON parameters.

Enums

OutputFormat

The output formats currently supported by HyperService

ParameterStyle

Parameter style for SQL queries.

QueryParameters

Query parameters for gRPC queries.

TransferMode

The requested result transfer mode. By default, we recommend using ADAPTIVE for most workloads.

Constants

DEFAULT_MAX_MESSAGE_SIZE

Default maximum message size for gRPC requests/responses (64 MB).