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 bash cargo run --example <name>
• Detailed documentation: See docs/examples.md for comprehensive examples and explanations
• Test examples: See tests/ directory for additional usage examples

Contributing

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

Getting Started

1. Fork the repository and clone your fork bash git clone https://github.com/YOUR_USERNAME/chdb-rust.git cd chdb-rust

2. Create a branch for your changes bash git checkout -b feature/your-feature-name # or git checkout -b fix/your-bug-fix

3. Make your changes and ensure they work

4. Run tests: cargo test
5. Check formatting: cargo fmt --check

6. Run clippy: cargo clippy

7. Commit your changes with clear, descriptive commit messages bash git commit -m "Add feature: description of what you did"

8. Push to your fork and open a Pull Request bash 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!