Installation

Add Yoda to your project in minutes — as a Rust library, a CLI tool, or a Python package.

System Requirements

• Rust: stable toolchain. CI tests on the latest stable (currently 1.95). The workspace uses edition 2021 and depends on async fn in traits (stable since 1.75).
• C++ toolchain (for duckdb-backend only): a working cc/c++ is needed because DuckDB bundles its C++ sources. No extra system library is required — duckdb-sys compiles everything.
• Docker (optional): only needed for the Postgres end-to-end tests (docker compose up).

Rust — Library

Add the crate to your Cargo.toml:

[dependencies]
# DataFusion backend (default — pure Rust, natively async)
yoda = "1"

# DuckDB backend instead of, or in addition to, DataFusion
# yoda = { version = "1", features = ["duckdb-backend"] }

# Both backends
# yoda = { version = "1", features = ["full"] }

Feature Flags

Feature	Default	Description
datafusion-backend	yes	Apache DataFusion OLAP engine (pure Rust, no C deps)
duckdb-backend	no	DuckDB OLAP engine — bundles the C++ library via duckdb-sys
full	no	Both OLAP backends simultaneously
sidecar	no	Timestamp-based CDC from external SQLite or PostgreSQL sources
rocksdb-cdc	no	RocksDB-backed durable CDC event buffer (5–7× faster write path than SQLite triggers)
flight-sql	no	Arrow Flight SQL gRPC server for OLAP queries (yoda-flight crate)
metrics	no	Emit counters/gauges via the metrics crate facade
metrics-exporter	no	Prometheus HTTP endpoint on yoda-tui (requires metrics_port in TOML config)
cloud-storage	no	S3 and GCS object-store backends for DataFusion Parquet storage

Picking a backend

Use datafusion-backend (the default) for most projects — it has zero C dependencies and compiles fast. Switch to duckdb-backend when you need ACID transactions on your OLAP mirror or want DuckDB's SQL dialect.

CLI — yd

Build and install the yd command from source:

# Install from the workspace (recommended during development)
cargo install --path crates/yoda-tui

# Or build a release binary without installing
cargo build -p yoda-tui --release
# Binary is at ./target/release/yd

The CLI supports all major operations:

yd exec  --db myapp.db "INSERT INTO events VALUES (1, 'hello')"
yd query --db myapp.db "SELECT COUNT(*) FROM events"
yd repl  --db myapp.db          # interactive REPL with persistent engine
yd serve --config config/htap.toml  # long-running service with TUI dashboard

See CLI Reference for the full command list.

Python

Install the published package:

pip install yoda
# or, with uv:
uv pip install yoda

Build from source (editable install):

# Requires maturin and a Rust toolchain
uv run maturin develop           # debug build
uv run maturin develop --release # optimised build

The Python package exposes HtapEngine, HtapConfig, TableSchema, and TimestampTableConfig. See Python Quickstart for a working example and Python API Reference for the full surface.

anyio / asyncio compatibility

The Python bindings bridge Rust's Tokio runtime into Python's async event loop via pyo3-async-runtimes. Every I/O method returns a native Python awaitable and works with both asyncio and anyio.