chdb-rust

Experimental chDB FFI bindings for Rust.

Documentation

Full API Documentation - Complete Rust API reference on docs.rs

Status

Experimental - This library is currently experimental, unstable, and subject to changes.

The library automatically downloads and manages libchdb dependencies during the build process.

Quick Start

Add chdb-rust to your Cargo.toml:

[dependencies]
chdb-rust = "1.1.0"

The library will automatically download the required libchdb binary during the build process.

Supported Platforms

• Linux: x86_64, aarch64
• macOS: x86_64, arm64 (Apple Silicon)

Building

Standard Build

cargo build

Verbose Build (for debugging)

RUST_BACKTRACE=full cargo build --verbose

Manual Installation (Optional)

If you prefer to install libchdb manually instead of automatic download:

System-wide installation:

./update_libchdb.sh --global

Local directory installation:

./update_libchdb.sh --local

Testing

Run the test suite:

cargo test -- --test-threads=1

Examples

• Runnable examples: See the examples/ directory

  cargo run --example <name>

• Detailed documentation: See docs/examples.md for comprehensive examples and explanations
• Test examples: See tests/ directory for additional usage examples

Arrow Bulk Insert

Apache Arrow bulk insert is enabled by default via the arrow feature (Arrow 59). Import Arrow types through chdb_rust::arrow so your RecordBatch types match the crate:

use chdb_rust::arrow::array::{Int64Array, RecordBatch};
use chdb_rust::arrow::datatypes::{DataType, Field, Schema};

SQL-only users can disable it to avoid building Arrow:

chdb-rust = { version = "1.4", default-features = false }

See docs/examples.md for usage, or run:

cargo run --example 08_arrow_insert

Contributing

We welcome contributions! Here's how you can help:

Getting Started

1. Fork the repository and clone your fork

   git clone https://github.com/YOUR_USERNAME/chdb-rust.git
   cd chdb-rust

2. Create a branch for your changes

   git checkout -b feature/your-feature-name
   # or
   git checkout -b fix/your-bug-fix

3. Make your changes and ensure they work

   • Run tests: cargo test
   • Check formatting: cargo fmt --check
   • Run clippy: cargo clippy

4. Commit your changes with clear, descriptive commit messages

   git commit -m "Add feature: description of what you did"

5. Push to your fork and open a Pull Request

   git push origin feature/your-feature-name

Development Guidelines

• Code Style: Follow Rust conventions and run cargo fmt before committing
• Testing: Add tests for new features and ensure all existing tests pass
• Documentation: Update relevant documentation for user-facing changes
• Commit Messages: Write clear, descriptive commit messages
• Pull Requests:
  • Provide a clear description of your changes
  • Reference any related issues
  • Ensure CI checks pass

Reporting Issues

Found a bug or have a feature request? Please open an issue on GitHub with:

• A clear description of the problem or feature
• Steps to reproduce (for bugs)
• Expected vs actual behavior
• Your environment (OS, Rust version, etc.)

Questions?

Feel free to open a discussion or issue if you have questions about contributing!