Skip to content

COMPATIBILITY.md

Latest commit

 

History

History
97 lines (77 loc) · 4.68 KB

COMPATIBILITY.md

File metadata and controls

97 lines (77 loc) · 4.68 KB
Raw

Compatibility & Release Policy

This document describes which IoTDB server versions this client targets, the exact protocol toolchain each crate release is built from, and the versioning rules the crate follows.

IoTDB server compatibility matrix

The client speaks IoTDB service protocol V3 over Apache Thrift RPC and targets the IoTDB 2.0.x line. There is no version-specific branching in the client code.

IoTDB version Status Notes
2.0.1 Expected to work Untested
2.0.2 Expected to work Untested
2.0.3 Expected to work Untested
2.0.4 Expected to work Untested
2.0.5 Expected to work Untested
2.0.6 Tested CI runs the full live test suite + 3 examples against apache/iotdb:2.0.6-standalone on every push; TLS verified end-to-end (enable_thrift_ssl, TLSv1.3, full certificate verification)
2.0.7 Expected to work Untested
2.0.8 Expected to work Untested
2.0.10 Tested Full benchmark + data-correctness verification (all 10 data types, tree & table models, nulls) against a standalone deployment; RPC compression verified (dn_rpc_thrift_compression_enable=true)
master Expected to work The Thrift IDL is synced from apache/iotdb master (iotdb-protocol/); untested beyond IDL lockstep
1.x Not supported The table model and the TIMESTAMP / DATE / BLOB / STRING data types assume 2.x; no plan to support 1.x

"Expected to work" means the version speaks protocol V3 and the same IDL surface, but the client has not been exercised against it. Reports of success or failure on untested versions are welcome as issues.

Protocol toolchain (per release)

Each crate release records the exact IDL source and Thrift toolchain used to generate src/protocol/:

Crate version IoTDB IDL source Thrift compiler thrift crate
0.1.0 (unreleased) apache/iotdb master, iotdb-protocol/ @ 2fedd8a395 (2026-06-30, last change to client.thrift/common.thrift) 0.23.0 (as pinned by the IoTDB pom's thrift.version) 0.23

The generation pipeline is documented in tools/generate-thrift.sh: the IDL files (thrift/client.thrift, thrift/common.thrift) are synced from apache/iotdb's iotdb-protocol/ module, and the Thrift compiler binary is taken from the IoTDB Maven build output, which guarantees the compiler version matches the one the server project pins. The generated stubs are committed and must never be hand-edited.

This table is updated as part of every release.

Versioning policy (SemVer)

The crate follows Cargo's SemVer rules:

  • Pre-1.0 (0.x.y): a bump of x may contain breaking API changes; a bump of y is additive or a bug fix. Cargo treats 0.x as the compatibility boundary, so ^0.1 will never auto-upgrade to 0.2.
  • Post-1.0: breaking changes bump the major version, new functionality bumps the minor version, bug fixes bump the patch version.
  • A regeneration of the Thrift stubs against a newer IDL is treated as breaking only if it changes the public Rust API surface; pure wire-level additions ship as minor/patch releases.

Deprecation policy

  • APIs slated for removal are first marked #[deprecated] (with a message pointing at the replacement) and remain functional for at least one minor release before removal.
  • Removals happen only in releases that SemVer already marks as breaking (major bumps, or 0.x bumps pre-1.0).
  • Deprecations and removals are listed in the release notes.

Release process

  • Every release documents, in its release notes: the IoTDB IDL commit, the Thrift compiler version, and the tested IoTDB server versions (the table above is updated in the same change).
  • CI continuously tests against both the oldest tested and the latest stable IoTDB versions (currently 2.0.6 and 2.0.10; see .github/workflows/ci.yml).