Version notes

Rhei is currently v2.0.0. Releases are tracked on GitHub Releases.

Versioning policy

Rhei follows Semantic Versioning for the public API:

• MAJOR — breaking changes to HtapEngine, HtapConfig, CdcSource, SidecarConfig, the trait surface in rhei-core, or the on-disk SQLite schema (_rhei_cdc_log layout, reserved column names).
• MINOR — new features, new optional config fields with backwards-compatible defaults, new feature flags.
• PATCH — bug fixes, performance improvements, dependency bumps, doc additions.

The rh CLI follows the same versioning. The TOML config schema is forward-compatible within a MAJOR version — unknown keys are ignored, missing optional keys fall back to defaults.

Pinned dependencies

Some upstream versions are pinned to keep the Arrow ABI consistent across backends:

• Arrow — 58 (must match duckdb 1.10501, datafusion 53, and connector_arrow 0.11)
• Rust toolchain — stable, minimum 1.91 (effective MSRV from vortex 0.70; CI runs on the latest stable, currently 1.95)
• PyO3 — 0.28 for the Python bindings
• arrow-flight — 58 for the FlightSQL server

Bumping any of these requires updating all together — they share an internal Arrow type lattice.

Recent highlights

Version	Notes
2.0.0	Vortex storage migration. DataFusion StorageMode collapses from 5 variants (InMemory / ArrowIpc / Parquet / S3Parquet / GcsParquet) down to 2: InMemory and unified Vortex { url }. The Vortex URL auto-classifies as local or S3-compatible from its prefix (s3://... → S3 with cloud-storage feature, otherwise local — schemes gs://, arrow_ipc, etc. are rejected). DuckDB backend unchanged. Breaking: HtapConfig callers passing StorageMode::ArrowIpc { path }, Parquet { path }, S3Parquet { url }, or GcsParquet { url } must migrate to Vortex { url }. Existing .arrow / .parquet directories cannot be upgraded in place — drop the OLAP directory and re-sync from source. GCS support is dropped from the matrix; S3-compatible (MinIO/R2/Wasabi/Ceph) covers the same use case via AWS_ENDPOINT_URL. PyPI distribution adds vortex-data runtime dep.
1.5.1	Release-CI hotfix. crates.io publish is now idempotent on tag re-pushes; PyPI wheel builds for Linux x86_64 + aarch64 (native ubuntu-24.04-arm) and macOS aarch64 are restored — Linux now installs clang in the manylinux container so bindgen (libduckdb-sys, rust-librocksdb-sys, libsqlite3-sys) can find libclang. macOS x86_64 wheels dropped (Intel-mac runners are scarce / deprecated; users fall through to sdist). Two stale tests fixed (Postgres E2E nested-runtime panic; Python idempotent-registration assertion now matches the v1.5 contract). No API surface changes.
1.5.0	Project rename Yoda → Rhei across all crates, CLI binary (yd → rh), Python package, on-disk schema (_yoda_* → _rhei_*), and docs. New brand identity and palette. No API surface changes — drop-in once names are updated.
1.4.0	S3 / GCS object-store backends for DataFusion Parquet (superseded in v2.0 by unified Vortex storage); sidecar watermark hardening; typed Arrow-batch bulk INSERT (~5.8× throughput restoration); RocksDB-backed CDC log (rocksdb-cdc); Arrow Flight SQL server (flight-sql); Python async bindings; live TUI dashboard.
1.3.x	Observability — Prometheus metrics endpoint, structured JSON logs.
1.2.x	Pluggable storage modes for DataFusion (InMemory / ArrowIpc / Parquet).
1.1.x	Sidecar mode (timestamp-based CDC for SQLite + PostgreSQL sources).
1.0.x	Initial public release: HTAP facade, trigger-based CDC, OLAP routing, temporal SCD-2 mode.

For the full per-PR history, see the GitHub release page or git log --oneline main.

Upgrading

From 1.5.x to 2.0.0

The 2.0 release replaces all DataFusion file-format storage modes with a single Vortex backend. DuckDB backend is unchanged; OLTP, CDC, sync, sidecar, FlightSQL, and the TOML config schema are all unchanged.

Rust API:

• StorageMode::ArrowIpc { path } and StorageMode::Parquet { path } → StorageMode::Vortex { url: path }
• StorageMode::S3Parquet { url } and StorageMode::GcsParquet { url } → StorageMode::Vortex { url } (GCS users must switch to S3-compatible)
• The cloud-storage Cargo feature is unchanged in name; it now gates the S3-compatible codepath of the unified Vortex mode rather than the separate object-store modes

TOML config (rh serve):

# Old (v1.5.x):                        # New (v2.0):
[engine.datafusion_storage]            [engine.datafusion_storage]
mode = "parquet"                       mode = "vortex"
path = "/var/lib/rhei/data"            path = "/var/lib/rhei/data"

# S3 — old:                            # S3 — new (no separate mode name):
mode = "s3-parquet"                    mode = "vortex"
url = "s3://bucket/prefix"             url = "s3://bucket/prefix"

The legacy mode names (arrow_ipc, parquet, s3-parquet, gcs-parquet) are explicitly rejected at config parse time so misconfigurations surface immediately.

Python:

# Old (v1.5.x):                          # New (v2.0):
HtapConfig(storage_mode="parquet",       HtapConfig(storage_mode="vortex",
           storage_path="/data")                    storage_path="/data")
# or:
                                         HtapConfig(storage_mode="vortex",
                                                    storage_path="s3://bucket/prefix")

On-disk data: existing .arrow and .parquet files cannot be read by v2.0. Drop the OLAP directory and re-sync from source — Rhei's CDC pipeline will repopulate the table store from the underlying SQLite/PostgreSQL OLTP database. A rh convert migration tool may ship in v2.1 if there's demand. Sidecar mode in particular is unaffected since the OLAP store is always a derived mirror.

GCS: dropped from the storage matrix. Users on Google Cloud Storage have two options:

1. Run an S3-compatibility shim (e.g. gcsfuse mounted into a MinIO gateway) and set AWS_ENDPOINT_URL accordingly.
2. Stay on v1.5.x until first-class GCS support returns (no committed timeline).

Cargo dependency:

[dependencies]
rhei = "2.0"   # was "1.5"

From 1.4.x (Yoda) to 1.5.x (Rhei)

The 1.5 release renames the project from Yoda to Rhei. The API surface is unchanged, but every public name moves:

• Cargo dependency: yoda = "1.4" → rhei = "1.5". All sub-crates likewise: yoda-core → rhei-core, etc.
• Rust imports: use yoda::… → use rhei::…, use yoda_core::… → use rhei_core::….
• CLI binary: yd → rh (e.g. yd serve → rh serve). All subcommands and flags are unchanged.
• Python package: pip install yoda → pip install rhei-engine; import yoda → import rhei.
• Env vars: YODA_TEST_E2E, YODA_TEST_POSTGRES, YODA_FLIGHT_AUTH_TOKEN → RHEI_*.
• On-disk schema: the CDC log table _yoda_cdc_log and SCD-2 columns _yoda_valid_from / _yoda_valid_to / _yoda_operation are renamed to _rhei_*. Existing databases need a one-time ALTER TABLE … RENAME TO (or start fresh).

HtapEngine, HtapConfig, CdcSource, SidecarConfig, the trait surface, and TOML keys are unchanged.

From 1.3.x to 1.4.x

• No breaking changes to HtapConfig or the trait surface.
• New optional config fields (flight_port, flight_auth_token, metrics_port, rocksdb_cdc_path) are all behind feature flags or have safe defaults.

General upgrade procedure

# Update Cargo.toml dependency:
rhei = "1.5"

# Verify with cargo check:
cargo check --workspace --all-features

# Run the test suite:
cargo test --workspace --all-features

If you store schema-registry state (schema_registry_path) on disk, the JSON format is forward-compatible — older registries load cleanly under newer Rhei versions.

Stability tiers

Not all crates carry the same stability promise:

Crate	Stability	Notes
rhei	Stable	Public-facing facade; semver-tracked.
rhei-core	Stable	Shared traits and types.
rhei-sync	Stable	CdcSyncEngine, SqlParserRouter.
rhei-olap, rhei-duckdb, rhei-datafusion	Stable	Implementation backends.
rhei-oltp-rusqlite	Stable	Default OLTP backend.
rhei-tokio-rusqlite	Stable	Standalone (no Rhei-specific dependencies).
rhei-sidecar	Stable	Sidecar mode.
rhei-cdc-rocksdb	Experimental	Feature rocksdb-cdc; API may change in a 1.x release.
rhei-flight	Experimental	Feature flight-sql; the gRPC schema may evolve.

Experimental crates won't be removed without a deprecation cycle, but their public API may shift in a minor release if Arrow Flight SQL upstream changes or a better RocksDB schema emerges.