Expand description
§chdb-rust
Rust FFI bindings for chDB, an embedded ClickHouse database.
§Overview
This crate provides a safe Rust interface to chDB, allowing you to execute ClickHouse SQL queries either statelessly (in-memory) or with persistent storage using sessions.
§Quick Start
use chdb_rust::execute;
use chdb_rust::arg::Arg;
use chdb_rust::format::OutputFormat;
// Execute a simple query
let result = execute("SELECT 1 + 1 AS sum", None)?;
println!("Result: {}", result.data_utf8_lossy());§Features
- Stateless queries: Execute one-off queries without persistent storage
- Stateful sessions: Create databases and tables with persistent storage
- Parameterized queries: Bind ClickHouse
{name:Type}placeholders withexecute_with_paramsandQueryParam, across buffered, streaming, Arrow-streaming and insert statements. Values are bound in the chDB library and never spliced into the SQL text - Multiple output formats: JSON, CSV, TabSeparated, and more
- Query result streaming: Read large result sets in chunks with constant memory
- Streaming INSERT (
insert_stream): push rows in chunks in any input format, with engine backpressure; the stream also implementsstd::io::Write - Arrow input and bulk insert (feature
arrow, on by default):connection::Connection::register_arrow_readercreates a scoped SQL source;insert_record_batch_directandinsert_record_batch_readerwrite Arrow data. Usechdb_rust::arrowtypes so your Arrow version matches the crate. - Arrow batch streaming (with the
arrowfeature): Stream query results asRecordBatchvalues via the Arrow C Data Interface - One-shot Arrow export (with the
arrowfeature): take a whole result as one Arrow stream viaconnection::Connection::query_arrow, witharrow_options::ArrowOptionscontrolling the type mapping on both the one-shot and streaming paths - Thread-safe: Connections and results can be safely sent between threads
- Version accessors (
version): which chdb-core release is linked, where it came from, and which ClickHouse it carries - Backup, restore and statement analysis (admin module): the chdb-core management ABI, on any engine that exports it
- Durable objects (feature
durable): a database whose authoritative state is a checkpoint plus a statement WAL in storage you own - Runtime control (
runtime): decline chDB’s process-wide signal handlers, and shut the engine down cleanly so no engine thread outlives your teardown
§Examples
See the examples directory for more detailed examples.
§Safety
This crate uses unsafe code to interface with the C library, but provides a safe Rust API.
All public functions are safe to call, and the crate ensures proper resource cleanup.
Re-exports§
pub use arrow_insert::insert_record_batch;pub use arrow_insert::insert_record_batch_direct;pub use arrow_insert::insert_record_batch_reader;pub use arrow_insert::insert_record_batches;pub use arrow_options::ArrowOptions;pub use arrow_options::InsertOptions;pub use arrow_query_stream::ArrowQueryStream;pub use arrow_query_stream::ArrowReader;pub use arrow_stream::arrow_stream_table_sql;pub use arrow_stream::ArrowRegistration;pub use insert_stream::InsertStream;pub use insert_stream::WriteStats;pub use insert_stream::DEFAULT_WRITE_BUFFER;pub use query_param::QueryParam;pub use query_param::QueryParams;pub use query_result::QueryResult;pub use arrow;
Modules§
- arg
- Query argument definitions for chDB.
- arrow_
insert - High-throughput inserts via Arrow C Data Interface registration.
- arrow_
options - Options for chDB’s Arrow paths: the insert-side
InsertOptions(tuning knobs forINSERT … SELECTand direct FFI insert) and the read-sideArrowOptions(type-mapping knobs for Arrow export). - arrow_
query_ stream - Arrow C Data Interface batch streaming for chDB query results.
- arrow_
stream - Arrow streaming support for chDB.
- connection
- Connection management for chDB.
- error
- Error types for chdb-rust.
- format
- Input and output format definitions for chDB queries.
- insert_
stream - Write-side streaming INSERT.
- log_
level - Log level definitions for chDB.
- query_
param - ClickHouse query parameter values for
{name:Type}placeholders. - query_
result - Query result handling for chDB.
- query_
stream - Streaming query result handling for chDB.
- runtime
- Process-wide engine lifecycle.
- session
- Session management for persistent chDB databases.
- version
- Which engine this build carries.
Functions§
- active_
engine_ path - The data path the embedded engine is bound to, or
Nonewhen no connection is open.:memory:for an in-memory engine, a directory otherwise. - active_
engine_ refs - How many open connections are holding the embedded engine. Zero means the next connection may bind any path.
- execute
- Execute a one-off query using an in-memory connection.
- execute_
stream - Execute a one-off streaming query using an in-memory connection.
- execute_
stream_ arrow - Execute a one-off Arrow streaming query using an in-memory connection.
- execute_
stream_ arrow_ with_ params - Execute a one-off query with ClickHouse
{name:Type}parameter binding and stream Arrow batches. - execute_
stream_ with_ params - Execute a one-off query with ClickHouse
{name:Type}parameter binding and stream text chunks. - execute_
with_ params - Execute a one-off query with ClickHouse
{name:Type}parameter binding.