Version notes

Yoda is currently v1.4.0. Releases are tracked on GitHub Releases.

Versioning policy

Yoda follows Semantic Versioning for the public API:

• MAJOR — breaking changes to HtapEngine, HtapConfig, CdcSource, SidecarConfig, the trait surface in yoda-core, or the on-disk SQLite schema (_yoda_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 yd 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.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
1.4.0	S3 / GCS object-store backends for DataFusion Parquet; 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.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.
• The _yoda_cdc_log SQLite schema is unchanged; existing databases work unmodified.

General upgrade procedure

# Update Cargo.toml dependency:
yoda = "1.4"

# 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 Yoda versions.

Stability tiers

Not all crates carry the same stability promise:

Crate	Stability	Notes
yoda	Stable	Public-facing facade; semver-tracked.
yoda-core	Stable	Shared traits and types.
yoda-sync	Stable	CdcSyncEngine, SqlParserRouter.
yoda-olap, yoda-duckdb, yoda-datafusion	Stable	Implementation backends.
yoda-oltp-rusqlite	Stable	Default OLTP backend.
yoda-tokio-rusqlite	Stable	Standalone (no Yoda-specific dependencies).
yoda-sidecar	Stable	Sidecar mode.
yoda-cdc-rocksdb	Experimental	Feature rocksdb-cdc; API may change in a 1.x release.
yoda-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.