Skip to main content

Crate chdb_rust

Crate chdb_rust 

Source
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 with execute_with_params and QueryParam, 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 implements std::io::Write
  • Arrow input and bulk insert (feature arrow, on by default): connection::Connection::register_arrow_reader creates a scoped SQL source; insert_record_batch_direct and insert_record_batch_reader write Arrow data. Use chdb_rust::arrow types so your Arrow version matches the crate.
  • Arrow batch streaming (with the arrow feature): Stream query results as RecordBatch values via the Arrow C Data Interface
  • One-shot Arrow export (with the arrow feature): take a whole result as one Arrow stream via connection::Connection::query_arrow, with arrow_options::ArrowOptions controlling 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 for INSERT … SELECT and direct FFI insert) and the read-side ArrowOptions (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 None when 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.