hyperdb_api_core/client/grpc/
mod.rs

1// Copyright (c) 2026, Salesforce, Inc. All rights reserved.
2// SPDX-License-Identifier: Apache-2.0 OR MIT
3
4//! gRPC transport for Hyper database.
5//!
6//! This module provides gRPC-based connectivity to Hyper servers as an
7//! alternative to the `PostgreSQL` wire protocol over TCP.
8//!
9//! gRPC transport is always available - no feature flags required.
10//!
11//! # Architecture
12//!
13//! The gRPC transport uses Protocol Buffers for message serialization and
14//! returns query results in Apache Arrow IPC format. This provides:
15//!
16//! - Better support for load balancing
17//! - Built-in streaming for large result sets
18//! - HTTP/2 multiplexing
19//! - Easier integration with service meshes
20//!
21//! # Limitations
22//!
23//! The gRPC interface is **read-only**:
24//! - Only SELECT queries are supported
25//! - No INSERT, UPDATE, DELETE, or DDL operations
26//! - No COPY protocol for bulk data insertion
27//!
28//! For write operations, use the standard TCP connection.
29//!
30//! # Message Size Limits
31//!
32//! By default, the client uses a 64 MB message size limit ([`DEFAULT_MAX_MESSAGE_SIZE`]).
33//! This is important when using [`TransferMode::Sync`], which returns all results in
34//! a single gRPC response. For [`TransferMode::Adaptive`] (default) or [`TransferMode::Async`],
35//! results are streamed in smaller chunks, making large message sizes less critical.
36//!
37//! ```
38//! use hyperdb_api_core::client::grpc::{GrpcConfig, TransferMode};
39//!
40//! // For SYNC mode with large results, increase the limit
41//! let config = GrpcConfig::new("http://localhost:7484")
42//!     .database("large_data.hyper")
43//!     .transfer_mode(TransferMode::Sync)
44//!     .max_message_size(256 * 1024 * 1024); // 256 MB
45//! ```
46//!
47//! # Parameterized Queries
48//!
49//! gRPC supports parameterized queries using [`QueryParameters`] and [`ParameterStyle`]:
50//!
51//! ```no_run
52//! use hyperdb_api_core::client::grpc::{GrpcClient, GrpcConfig, QueryParameters, ParameterStyle};
53//!
54//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
55//! # let config = GrpcConfig::new("http://localhost:7484");
56//! let mut client = GrpcClient::connect(config).await?;
57//!
58//! // Dollar-numbered parameters ($1, $2, ...) - use from_json_value for mixed types
59//! let params = QueryParameters::from_json_value(&serde_json::json!([42, "Alice"]))?;
60//! let result = client.execute_query_with_params(
61//!     "SELECT * FROM users WHERE id = $1 AND name = $2",
62//!     params,
63//!     ParameterStyle::DollarNumbered,
64//! ).await?;
65//!
66//! // Named parameters (:id, :name, ...)
67//! let params = QueryParameters::json_named()
68//!     .add("id", &42i64)?
69//!     .add("name", &"Alice")?
70//!     .build();
71//! let result = client.execute_query_with_params(
72//!     "SELECT * FROM users WHERE id = :id AND name = :name",
73//!     params,
74//!     ParameterStyle::Named,
75//! ).await?;
76//! # Ok(())
77//! # }
78//! ```
79//!
80//! # Example
81//!
82//! ```no_run
83//! use hyperdb_api_core::client::grpc::{GrpcClient, GrpcConfig};
84//!
85//! #[tokio::main]
86//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
87//!     let config = GrpcConfig::new("http://localhost:7484")
88//!         .database("my_database.hyper");
89//!
90//!     let mut client = GrpcClient::connect(config).await?;
91//!
92//!     // Execute a query and get Arrow IPC bytes
93//!     let arrow_data = client.execute_query_to_arrow("SELECT * FROM users").await?;
94//!
95//!     // Or get parsed results
96//!     let result = client.execute_query("SELECT id, name FROM users").await?;
97//!     // Process Arrow data...
98//!
99//!     Ok(())
100//! }
101//! ```
102
103mod client;
104mod config;
105mod error;
106mod executor;
107mod params;
108mod proto;
109mod result;
110
111#[cfg(feature = "salesforce-auth")]
112mod authenticated_client;
113
114pub use client::{GrpcChunkStreamSync, GrpcClient, GrpcClientSync};
115pub use config::{GrpcConfig, DEFAULT_MAX_MESSAGE_SIZE};
116pub use error::GrpcError;
117pub use executor::GrpcChunkStream;
118pub use params::{JsonNamedParamsBuilder, ParameterStyle, QueryParameters};
119pub use result::{GrpcColumnInfo, GrpcQueryResult, GrpcResultChunk};
120
121#[cfg(feature = "salesforce-auth")]
122pub use authenticated_client::{AuthenticatedGrpcClient, AuthenticatedGrpcClientSync, TableInfo};
123
124// Re-export transfer mode for users who want to specify it
125pub use proto::hyper_service::query_param::TransferMode;
126
127// Re-export output format for advanced users
128pub use proto::hyper_service::OutputFormat;
hyperdb_api_core/client/grpc/mod.rs

hyperdb_api_core/client/grpc/
mod.rs
