title_wip

[Edit this page](https://github.com/ClickHouse/clickhouse-docs/blob/main/docs/chdb/install/rust.md)

chDB-rust provides experimental FFI (Foreign Function Interface) bindings for chDB, enabling you to run ClickHouse queries directly in your Rust applications with zero external dependencies.

## Installation[​](#installation "Direct link to Installation")

### Install libchdb[​](#install-libchdb "Direct link to Install libchdb")

Install the chDB library:

```
curl -sL https://lib.chdb.io | bash
```

## Usage[​](#usage "Direct link to Usage")

chDB Rust provides both stateless and stateful query execution modes.

### Stateless usage[​](#stateless-usage "Direct link to Stateless usage")

For simple queries without persistent state:

```
use chdb_rust::{execute, arg::Arg, format::OutputFormat};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Execute a simple query
    let result = execute(
        "SELECT version()",
        Some(&[Arg::OutputFormat(OutputFormat::JSONEachRow)])
    )?;
    println!("ClickHouse version: {}", result.data_utf8()?);
    
    // Query with CSV file
    let result = execute(
        "SELECT * FROM file('data.csv', 'CSV')",
        Some(&[Arg::OutputFormat(OutputFormat::JSONEachRow)])
    )?;
    println!("CSV data: {}", result.data_utf8()?);
    
    Ok(())
}
```

### Stateful usage (Sessions)[​](#stateful-usage-sessions "Direct link to Stateful usage (Sessions)")

For queries requiring persistent state like databases and tables:

```
use chdb_rust::{
    session::SessionBuilder,
    arg::Arg,
    format::OutputFormat,
    log_level::LogLevel
};
use tempdir::TempDir;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create a temporary directory for database storage
    let tmp = TempDir::new("chdb-rust")?;
    
    // Build session with configuration
    let session = SessionBuilder::new()
        .with_data_path(tmp.path())
        .with_arg(Arg::LogLevel(LogLevel::Debug))
        .with_auto_cleanup(true)  // Cleanup on drop
        .build()?;

    // Create database and table
    session.execute(
        "CREATE DATABASE demo; USE demo", 
        Some(&[Arg::MultiQuery])
    )?;

    session.execute(
        "CREATE TABLE logs (id UInt64, msg String) ENGINE = MergeTree() ORDER BY id",
        None,
    )?;

    // Insert data
    session.execute(
        "INSERT INTO logs (id, msg) VALUES (1, 'Hello'), (2, 'World')",
        None,
    )?;

    // Query data
    let result = session.execute(
        "SELECT * FROM logs ORDER BY id",
        Some(&[Arg::OutputFormat(OutputFormat::JSONEachRow)]),
    )?;

    println!("Query results:\n{}", result.data_utf8()?);
    
    // Get query statistics
    println!("Rows read: {}", result.rows_read());
    println!("Bytes read: {}", result.bytes_read());
    println!("Query time: {:?}", result.elapsed());

    Ok(())
}
```

## Building and testing[​](#building-testing "Direct link to Building and testing")

### Build the project[​](#build-the-project "Direct link to Build the project")

```
cargo build
```

### Run tests[​](#run-tests "Direct link to Run tests")

```
cargo test
```

### Development dependencies[​](#development-dependencies "Direct link to Development dependencies")

The project includes these development dependencies:

- `bindgen` (v0.70.1) - Generate FFI bindings from C headers
- `tempdir` (v0.3.7) - Temporary directory handling in tests
- `thiserror` (v1) - Error handling utilities

## Error handling[​](#error-handling "Direct link to Error handling")

chDB Rust provides comprehensive error handling through the `Error` enum:

```
use chdb_rust::{execute, error::Error};

match execute("SELECT 1", None) {
    Ok(result) => {
        println!("Success: {}", result.data_utf8()?);
    },
    Err(Error::QueryError(msg)) => {
        eprintln!("Query failed: {}", msg);
    },
    Err(Error::NoResult) => {
        eprintln!("No result returned");
    },
    Err(Error::NonUtf8Sequence(e)) => {
        eprintln!("Invalid UTF-8: {}", e);
    },
    Err(e) => {
        eprintln!("Other error: {}", e);
    }
}
```

## GitHub repository[​](#github-repository "Direct link to GitHub repository")

You can find the GitHub repository for the project at [chdb-io/chdb-rust](https://github.com/chdb-io/chdb-rust).

- [Installation](#installation)
  - [Install libchdb](#install-libchdb)- [Usage](#usage)
    - [Stateless usage](#stateless-usage)- [Stateful usage (Sessions)](#stateful-usage-sessions)- [Building and testing](#building-testing)
      - [Build the project](#build-the-project)- [Run tests](#run-tests)- [Development dependencies](#development-dependencies)- [Error handling](#error-handling)- [GitHub repository](#github-repository)

Was this page helpful?