Skip to main content

chdb_rust/
lib.rs

1//! # chdb-rust
2//!
3//! Rust FFI bindings for [chDB](https://github.com/chdb-io/chdb), an embedded ClickHouse database.
4//!
5//! ## Overview
6//!
7//! This crate provides a safe Rust interface to chDB, allowing you to execute ClickHouse SQL queries
8//! either statelessly (in-memory) or with persistent storage using sessions.
9//!
10//! ## Quick Start
11//!
12//! ```no_run
13//! use chdb_rust::execute;
14//! use chdb_rust::arg::Arg;
15//! use chdb_rust::format::OutputFormat;
16//!
17//! // Execute a simple query
18//! let result = execute("SELECT 1 + 1 AS sum", None)?;
19//! println!("Result: {}", result.data_utf8_lossy());
20//! # Ok::<(), chdb_rust::error::Error>(())
21//! ```
22//!
23//! ## Features
24//!
25//! - **Stateless queries**: Execute one-off queries without persistent storage
26//! - **Stateful sessions**: Create databases and tables with persistent storage
27//! - **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
28//! - **Multiple output formats**: JSON, CSV, TabSeparated, and more
29//! - **Query result streaming**: Read large result sets in chunks with constant memory
30//! - **Streaming INSERT** ([`insert_stream`]): push rows in chunks in any input format, with engine backpressure; the stream also implements [`std::io::Write`]
31//! - **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`](arrow) types so your Arrow version matches the crate.
32//! - **Arrow batch streaming** (with the `arrow` feature): Stream query results as `RecordBatch` values via the Arrow C Data Interface
33//! - **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
34//! - **Thread-safe**: Connections and results can be safely sent between threads
35//! - **Version accessors** ([`version`]): which chdb-core release is linked, where it came from, and which ClickHouse it carries
36//! - **Backup, restore and statement analysis** (admin module): the chdb-core management ABI, on any engine that exports it
37//! - **Durable objects** (feature `durable`): a database whose authoritative state is a checkpoint plus a statement WAL in storage you own
38//! - **Runtime control** ([`runtime`]): decline chDB's process-wide signal handlers, and shut the engine down cleanly so no engine thread outlives your teardown
39//!
40//! ## Examples
41//!
42//! See the [`examples`](https://github.com/chdb-io/chdb-rust/tree/main/examples) directory for more detailed examples.
43//!
44//! ## Safety
45//!
46//! This crate uses `unsafe` code to interface with the C library, but provides a safe Rust API.
47//! All public functions are safe to call, and the crate ensures proper resource cleanup.
48
49#[cfg(has_durable_abi)]
50pub mod admin;
51pub mod arg;
52#[cfg(feature = "arrow")]
53pub mod arrow_insert;
54#[cfg(feature = "arrow")]
55pub mod arrow_options;
56#[cfg(feature = "arrow")]
57pub mod arrow_query_stream;
58#[cfg(feature = "arrow")]
59pub mod arrow_stream;
60#[cfg(feature = "arrow")]
61pub use arrow;
62#[cfg(feature = "arrow")]
63pub use arrow_insert::{
64    insert_record_batch, insert_record_batch_direct, insert_record_batch_reader,
65    insert_record_batches,
66};
67#[cfg(feature = "arrow")]
68pub use arrow_options::{ArrowOptions, InsertOptions};
69#[cfg(feature = "arrow")]
70pub use arrow_query_stream::{ArrowQueryStream, ArrowReader};
71#[cfg(feature = "arrow")]
72pub use arrow_stream::arrow_stream_table_sql;
73#[cfg(feature = "arrow")]
74pub use arrow_stream::ArrowRegistration;
75#[allow(
76    dead_code,
77    unused,
78    non_snake_case,
79    non_camel_case_types,
80    non_upper_case_globals
81)]
82mod bindings {
83    include!(concat!(env!("OUT_DIR"), "/bindings.rs"));
84}
85pub mod connection;
86// The `durable` feature needs the chdb-core management ABI, and a library that
87// does not export it cannot serve a durable object at all. Saying so at compile
88// time beats a link error naming three symbols.
89#[cfg(all(feature = "durable", not(has_durable_abi)))]
90compile_error!(
91    "the `durable` feature needs a libchdb with the Durable V1 ABI (chdb_backup_database_n, \
92     chdb_restore_database_n, chdb_classify_query_n), which is chdb-core v26.7.2-rc.2 or newer. \
93     Update the engine with ./update_libchdb.sh, or point CHDB_LIB_DIR at a newer one."
94);
95#[cfg(all(feature = "durable", has_durable_abi))]
96pub mod durable;
97pub mod error;
98pub mod format;
99pub mod insert_stream;
100pub use insert_stream::{InsertStream, WriteStats, DEFAULT_WRITE_BUFFER};
101pub mod log_level;
102pub mod query_param;
103pub mod query_result;
104pub mod query_stream;
105pub(crate) mod registry;
106pub mod runtime;
107pub mod session;
108pub mod version;
109
110pub use query_param::{QueryParam, QueryParams};
111pub use query_result::QueryResult;
112
113#[cfg(test)]
114mod test_utils;
115
116use crate::arg::{extract_output_format, Arg};
117use crate::connection::Connection;
118use crate::error::Result;
119use crate::format::OutputFormat;
120use crate::query_stream::QueryStream;
121
122pub(crate) const CHDB_PROGRAM_NAME: &str = "clickhouse";
123
124/// Execute a one-off query using an in-memory connection.
125///
126/// This function creates a temporary in-memory database connection, executes the query,
127/// and returns the result. It's suitable for queries that don't require persistent storage.
128///
129/// # Arguments
130///
131/// * `query` - The SQL query string to execute
132/// * `query_args` - Optional array of query arguments (e.g., output format)
133///
134/// # Returns
135///
136/// Returns a [`QueryResult`] containing the query output, or an [`Error`](error::Error) if
137/// the query fails.
138///
139/// # Examples
140///
141/// ```no_run
142/// use chdb_rust::execute;
143/// use chdb_rust::arg::Arg;
144/// use chdb_rust::format::OutputFormat;
145///
146/// // Simple query with default format
147/// let result = execute("SELECT 1 + 1 AS sum", None)?;
148/// println!("{}", result.data_utf8_lossy());
149///
150/// // Query with JSON output format
151/// let result = execute(
152///     "SELECT 'Hello' AS greeting, 42 AS answer",
153///     Some(&[Arg::OutputFormat(OutputFormat::JSONEachRow)])
154/// )?;
155/// println!("{}", result.data_utf8_lossy());
156/// # Ok::<(), chdb_rust::error::Error>(())
157/// ```
158///
159/// # Errors
160///
161/// This function will return an error if:
162/// - The query syntax is invalid
163/// - The connection cannot be established
164/// - The query execution fails
165/// - A connection is already open on a data path, since the in-memory
166///   connection this opens would be a second one. See
167///   [`Error::PathConflict`](error::Error::PathConflict).
168pub fn execute(query: &str, query_args: Option<&[Arg]>) -> Result<QueryResult> {
169    let conn = Connection::open_in_memory()?;
170    let fmt = extract_output_format(query_args, OutputFormat::TabSeparated);
171    conn.query(query, fmt)
172}
173
174/// The data path the embedded engine is bound to, or `None` when no connection
175/// is open. `:memory:` for an in-memory engine, a directory otherwise.
176pub fn active_engine_path() -> Option<String> {
177    registry::active_path()
178}
179
180/// How many open connections are holding the embedded engine. Zero means the
181/// next connection may bind any path.
182pub fn active_engine_refs() -> usize {
183    registry::refs()
184}
185
186/// Execute a one-off query with ClickHouse `{name:Type}` parameter binding.
187///
188/// Counterpart to [`execute`]. Parameter values are bound in the chDB library
189/// and never interpolated into the SQL text. Names in `params` need not match placeholder
190/// order. An empty `params` list is a plain query: placeholders then fail with a
191/// substitution error.
192///
193/// # Examples
194///
195/// ```no_run
196/// use chdb_rust::arg::Arg;
197/// use chdb_rust::execute_with_params;
198/// use chdb_rust::format::OutputFormat;
199///
200/// let result = execute_with_params(
201///     "SELECT {x:UInt64} AS v",
202///     Some(&[Arg::OutputFormat(OutputFormat::CSV)]),
203///     [("x", 7_u64)],
204/// )?;
205/// # Ok::<(), chdb_rust::error::Error>(())
206/// ```
207///
208/// # Errors
209///
210/// This function will return an error if:
211/// - The query syntax is invalid
212/// - A `{name:Type}` placeholder has no matching param
213/// - A value cannot be parsed as the type declared in the placeholder
214/// - The connection cannot be established
215/// - The query execution fails
216/// - A connection is already open on a data path, since the in-memory
217///   connection this opens would be a second one. See
218///   [`Error::PathConflict`](error::Error::PathConflict).
219pub fn execute_with_params(
220    query: &str,
221    query_args: Option<&[Arg]>,
222    params: impl Into<QueryParams>,
223) -> Result<QueryResult> {
224    let conn = Connection::open_in_memory()?;
225    let fmt = extract_output_format(query_args, OutputFormat::TabSeparated);
226    conn.query_with_params(query, fmt, params)
227}
228
229/// Execute a one-off streaming query using an in-memory connection.
230///
231/// This function creates a temporary in-memory database connection, starts a
232/// streaming query, and returns a [`QueryStream`] that owns the connection.
233/// The connection is kept alive until the stream is dropped.
234///
235/// Primarily useful for reading external data: CSV files, S3, Parquet, etc.
236///
237/// # Arguments
238///
239/// * `query` - The SQL query string to execute
240/// * `query_args` - Optional array of query arguments (e.g., output format)
241///
242/// # Returns
243///
244/// Returns a [`QueryStream`] that owns the temporary connection, or an
245/// [`Error`](error::Error) if the query cannot be started.
246///
247/// # Examples
248///
249/// ```no_run
250/// use chdb_rust::execute_stream;
251/// use chdb_rust::arg::Arg;
252/// use chdb_rust::format::OutputFormat;
253///
254/// let mut stream = execute_stream(
255///     "SELECT number FROM numbers(100_000)",
256///     Some(&[Arg::OutputFormat(OutputFormat::JSONEachRow)]),
257/// )?;
258///
259/// while let Some(chunk) = stream.next_chunk()? {
260///     print!("{}", chunk.data_utf8_lossy());
261/// }
262/// # Ok::<(), chdb_rust::error::Error>(())
263/// ```
264///
265/// # Errors
266///
267/// This function will return an error if:
268/// - The query syntax is invalid
269/// - The connection cannot be established
270/// - The query execution fails
271pub fn execute_stream(query: &str, query_args: Option<&[Arg]>) -> Result<QueryStream<'static>> {
272    let conn = Connection::open_in_memory()?;
273    let fmt = extract_output_format(query_args, OutputFormat::TabSeparated);
274    QueryStream::start_owned(conn, query, fmt)
275}
276
277/// Execute a one-off query with ClickHouse `{name:Type}` parameter binding and stream text chunks.
278///
279/// Counterpart to [`execute_stream`]. Syntax errors fail when the stream is
280/// created. A missing placeholder binding is reported on the first
281/// [`QueryStream::next_chunk`], not at start.
282///
283/// # Examples
284///
285/// ```no_run
286/// use chdb_rust::arg::Arg;
287/// use chdb_rust::execute_stream_with_params;
288/// use chdb_rust::format::OutputFormat;
289///
290/// let mut stream = execute_stream_with_params(
291///     "SELECT {x:UInt64} AS v",
292///     Some(&[Arg::OutputFormat(OutputFormat::CSV)]),
293///     [("x", 11_u64)],
294/// )?;
295/// while let Some(chunk) = stream.next_chunk()? {
296///     print!("{}", chunk.data_utf8_lossy());
297/// }
298/// # Ok::<(), chdb_rust::error::Error>(())
299/// ```
300///
301/// # Errors
302///
303/// This function will return an error if:
304/// - The query syntax is invalid
305/// - The connection cannot be established
306/// - The query cannot be started
307/// - A connection is already open on a data path. See
308///   [`Error::PathConflict`](error::Error::PathConflict).
309pub fn execute_stream_with_params(
310    query: &str,
311    query_args: Option<&[Arg]>,
312    params: impl Into<QueryParams>,
313) -> Result<QueryStream<'static>> {
314    let conn = Connection::open_in_memory()?;
315    let fmt = extract_output_format(query_args, OutputFormat::TabSeparated);
316    QueryStream::start_owned_with_params(conn, query, fmt, params)
317}
318
319/// Execute a one-off Arrow streaming query using an in-memory connection.
320///
321/// Returns an [`ArrowQueryStream`] that owns the temporary connection and yields
322/// [`arrow::record_batch::RecordBatch`] values via the Arrow C Data Interface.
323///
324/// Available when the crate is built with the `arrow` feature.
325///
326/// # Examples
327///
328/// ```no_run
329/// use chdb_rust::execute_stream_arrow;
330///
331/// let mut stream = execute_stream_arrow("SELECT number FROM numbers(100_000)")?;
332/// while let Some(batch) = stream.next_batch()? {
333///     println!("rows: {}", batch.num_rows());
334/// }
335/// # Ok::<(), chdb_rust::error::Error>(())
336/// ```
337#[cfg(feature = "arrow")]
338pub fn execute_stream_arrow(query: &str) -> Result<ArrowQueryStream<'static>> {
339    let conn = Connection::open_in_memory()?;
340    ArrowQueryStream::start_owned(conn, query, None)
341}
342
343/// Execute a one-off query with ClickHouse `{name:Type}` parameter binding and stream Arrow batches.
344///
345/// Counterpart to [`execute_stream_arrow`]. Syntax errors fail when the stream is
346/// created. A missing placeholder binding is reported on the first
347/// [`ArrowQueryStream::next_batch`], not at start.
348///
349/// # Examples
350///
351/// ```no_run
352/// use chdb_rust::execute_stream_arrow_with_params;
353///
354/// let mut stream =
355///     execute_stream_arrow_with_params("SELECT {x:UInt64} AS v", [("x", 11_u64)])?;
356/// while let Some(batch) = stream.next_batch()? {
357///     println!("rows: {}", batch.num_rows());
358/// }
359/// # Ok::<(), chdb_rust::error::Error>(())
360/// ```
361///
362/// # Errors
363///
364/// This function will return an error if:
365/// - The query syntax is invalid
366/// - The connection cannot be established
367/// - The query cannot be started
368/// - A connection is already open on a data path. See
369///   [`Error::PathConflict`](error::Error::PathConflict).
370#[cfg(feature = "arrow")]
371pub fn execute_stream_arrow_with_params(
372    query: &str,
373    params: impl Into<QueryParams>,
374) -> Result<ArrowQueryStream<'static>> {
375    let conn = Connection::open_in_memory()?;
376    ArrowQueryStream::start_owned_with_params(conn, query, params, None)
377}