Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

安装适用于 Rust 的 chDB

View as MarkdownEdit this pageReport an issueSet up docs MCP

chDB-rust 提供适用于 chDB 的 Experimental FFI (外部函数接口) 绑定，让您能够在 Rust 应用程序中直接运行 ClickHouse 查询，且无需任何外部依赖。

安装

安装 libchdb

安装 chDB 库：

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

用法

chDB Rust 提供无状态和有状态两种查询执行模式。

无状态用法

对于不需要持久状态的简单查询：

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

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 执行简单查询
    let result = execute(
        "SELECT version()",
        Some(&[Arg::OutputFormat(OutputFormat::JSONEachRow)])
    )?;
    println!("ClickHouse version: {}", result.data_utf8()?);
    
    // 使用 CSV 文件进行查询
    let result = execute(
        "SELECT * FROM file('data.csv', 'CSV')",
        Some(&[Arg::OutputFormat(OutputFormat::JSONEachRow)])
    )?;
    println!("CSV data: {}", result.data_utf8()?);
    
    Ok(())
}

有状态用法 (会话)

对于需要持久状态 (如数据库和表) 的查询：

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

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 为数据库存储创建临时目录
    let tmp = TempDir::new("chdb-rust")?;
    
    // 构建带配置的会话
    let session = SessionBuilder::new()
        .with_data_path(tmp.path())
        .with_arg(Arg::LogLevel(LogLevel::Debug))
        .with_auto_cleanup(true)  // 释放时清理
        .build()?;

    // 创建数据库和表
    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,
    )?;

    // 插入数据
    session.execute(
        "INSERT INTO logs (id, msg) VALUES (1, 'Hello'), (2, 'World')",
        None,
    )?;

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

    println!("Query results:\n{}", result.data_utf8()?);
    
    // 获取查询统计信息
    println!("Rows read: {}", result.rows_read());
    println!("Bytes read: {}", result.bytes_read());
    println!("Query time: {:?}", result.elapsed());

    Ok(())
}

构建与测试

构建项目

cargo build

运行测试

cargo test

开发依赖项

该项目包含以下开发依赖：

  • bindgen (v0.70.1) - 从 C 头文件生成 FFI 绑定
  • tempdir (v0.3.7) - 在测试中处理临时目录
  • thiserror (v1) - 错误处理工具

错误处理

chDB Rust 通过 Error 枚举提供了完善的错误处理机制：

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 仓库

你可以在 chdb-io/chdb-rust 找到该项目的 GitHub 仓库。

Navigation