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//! - **Multiple output formats**: JSON, CSV, TabSeparated, and more
28//! - **Thread-safe**: Connections and results can be safely sent between threads
29//!
30//! ## Examples
31//!
32//! See the [`examples`](https://github.com/chdb-io/chdb-rust/tree/main/examples) directory for more detailed examples.
33//!
34//! ## Safety
35//!
36//! This crate uses `unsafe` code to interface with the C library, but provides a safe Rust API.
37//! All public functions are safe to call, and the crate ensures proper resource cleanup.
38
39pub mod arg;
40#[allow(
41    dead_code,
42    unused,
43    non_snake_case,
44    non_camel_case_types,
45    non_upper_case_globals
46)]
47mod bindings;
48pub mod connection;
49pub mod error;
50pub mod format;
51pub mod log_level;
52pub mod query_result;
53pub mod session;
54
55use crate::arg::{extract_output_format, Arg};
56use crate::connection::Connection;
57use crate::error::Result;
58use crate::query_result::QueryResult;
59
60/// Execute a one-off query using an in-memory connection.
61///
62/// This function creates a temporary in-memory database connection, executes the query,
63/// and returns the result. It's suitable for queries that don't require persistent storage.
64///
65/// # Arguments
66///
67/// * `query` - The SQL query string to execute
68/// * `query_args` - Optional array of query arguments (e.g., output format)
69///
70/// # Returns
71///
72/// Returns a [`QueryResult`] containing the query output, or an [`Error`](error::Error) if
73/// the query fails.
74///
75/// # Examples
76///
77/// ```no_run
78/// use chdb_rust::execute;
79/// use chdb_rust::arg::Arg;
80/// use chdb_rust::format::OutputFormat;
81///
82/// // Simple query with default format
83/// let result = execute("SELECT 1 + 1 AS sum", None)?;
84/// println!("{}", result.data_utf8_lossy());
85///
86/// // Query with JSON output format
87/// let result = execute(
88///     "SELECT 'Hello' AS greeting, 42 AS answer",
89///     Some(&[Arg::OutputFormat(OutputFormat::JSONEachRow)])
90/// )?;
91/// println!("{}", result.data_utf8_lossy());
92/// # Ok::<(), chdb_rust::error::Error>(())
93/// ```
94///
95/// # Errors
96///
97/// This function will return an error if:
98/// - The query syntax is invalid
99/// - The connection cannot be established
100/// - The query execution fails
101pub fn execute(query: &str, query_args: Option<&[Arg]>) -> Result<QueryResult> {
102    let conn = Connection::open_in_memory()?;
103    let fmt = extract_output_format(query_args);
104    conn.query(query, fmt)
105}
chdb_rust/lib.rs

chdb_rust/
lib.rs
