Repository navigation
EN Compatibility and Validation
TsGate 2.1.0: This guide uses
com.alandevise.tsgate.*. Upgrading from 2.0.0 requires updating imports, reflection names and package scanning, then recompiling. Central 2.0.0 retainscom.alandevise.tsdb.*. See migration steps and release status.
Release source 8cf119e includes the shared SPI count(null) argument error and bounded validation of extreme OpenGemini integer-valued decimal predicates. The mechanical namespace migration is isolated in 2cecd41; all 91 original Java files are recognized as renames and retain traceable history. Final reports are under .local-test/release-2.1.0-20261003/.
| Runtime / scope | Result | Report |
|---|---|---|
| JDK 17 / Spring Boot 2.7.18 unit suite | 889 passed; zero failures, errors or skips | docker-existing/summary.json |
| JDK 21 / Spring Boot 3.5.14 unit suite | 889 passed; zero failures, errors or skips | unit-jdk21-final/summary.json |
| JDK 25 / Spring Boot 4.1.0 unit suite | 889 passed; zero failures, errors or skips | unit-jdk25/summary.json |
| Existing-backend Docker suite | 114 passed; owned containers removed | docker-existing/summary.json |
| OpenGemini 1.4.1 single node / three-node, three-replica cluster | 44 passed in each deployment | opengemini-matrix/summary.json |
| OpenGemini 1.5.2 single node / three-node, three-replica cluster | 44 passed in each deployment | opengemini-matrix/summary.json |
| Final Temurin 17.0.14+7 signed build | 889 unit tests passed; 27 JAR attachments audited; 38 PGP signatures and all four checksum types verified |
build-status.json, release-artifacts.json, bundle-verification.json
|
The 290 Docker integration tests all have zero failures, errors or skips. All owned matrix containers/networks were removed. Build-input hashes match across the runtime and Docker runs; signed artifacts correspond to the release source commit. The 11 Maven modules comprise the parent POM, standalone BOM and nine JAR modules. Signing-key fingerprint: D7FB5E1158537706FB2023D62DCFFB6B26BE7EB5. Bundle SHA-256: b6cbc4927587223bfbad9b613c63cf0894e1f014571368db8de4d4ce580c1193.
The final source also passed JDK 17/21/25 GitHub CI, including the Java 17 unsigned artifact audit. Its remote Docker job was not requested; the Docker evidence above comes from the local environment.
The earlier 888-unit / 290-Docker snapshots below remain historical evidence. Central publication is tracked separately in Testing and publishing.
The recorded migration snapshot uses com.alandevise.tsgate.*; 103 Java files and 18 main/test package directories were migrated. SHA-256 checks confirm that the namespace migration itself preserved the existing Java implementation. Spring auto-configuration resources, reflection names, portable runner FQCNs, Javadoc audit paths and examples were updated. The later 2.1.0 review fixes and versioned release build are tracked separately in the release verification section above.
The migrated source passed 888 unit tests on each JDK/Boot combination (17/2.7.18, 21/3.5.14, 25/4.1.0), 114 existing-backend Docker tests, and 44 OpenGemini adapter/starter tests in each of four deployments (1.4.1 single node, 1.4.1 three-node/three-replica cluster, 1.5.2 single node and 1.5.2 three-node/three-replica cluster). All failures, errors and skipped counts are zero. Owned Docker resources were removed. Nine JAR modules passed 27 unsigned binary/source/Javadoc archive checks; 34 Python runner regression tests also passed. All Java runs used identical build-input hashes. Reports are under .local-test/package-migration-20261003/; earlier reports retain their original namespace and snapshots.
Earlier records below, including the pre-migration OpenGemini 888-unit / 44-case-per-environment results, retain their original source snapshots, manifests, JSON/XML reports, logs and immutable source links. The new namespace is verified by the separate migration regression above. Neither snapshot substitutes for verification of the final 2.1.0 release build.
TsGate 2.1.0 adds tsgate-opengemini and tsgate-opengemini-spring-boot-starter, bringing the build to four backends and nine JAR modules. The 2.1.0 BOM manages both new modules. Central 2.0.0 contains neither module. See OpenGemini integration for the exact verified default-engine versions and topologies. Historical records retain their original source snapshots, runtimes, test counts and seven-module artifact audit. The pre-package-migration OpenGemini source validation is recorded separately below.
The expanded source passed 888 unit tests on each of the three documented JDK/Boot combinations. The representative existing-backend Docker suite passed 114 integration tests; those three backend implementations were not changed by the subsequent OpenGemini-specific fixes. Nine JAR modules passed 27 unsigned binary/source/Javadoc artifact checks. Each environment below passed both the adapter and starter suites, with zero failures, errors or skipped tests and no owned containers/networks left behind. This local result does not represent a GitHub CI run or a Maven publication.
| Server | Topology | Replicas | Java integration results |
|---|---|---|---|
| 1.4.1 | Single node | 1 | 44 passed; 0 failed/errors/skipped |
| 1.4.1 | Three-node cluster | 3 | 44 passed; 0 failed/errors/skipped |
| 1.5.2 | Single node | 1 | 44 passed; 0 failed/errors/skipped |
| 1.5.2 | Three-node cluster | 3 | 44 passed; 0 failed/errors/skipped |
Exact default-engine settings, asynchronous new-series visibility, HTTP integer precision boundaries and reproduction commands are documented in OpenGemini integration. Reports are retained in .local-test/opengemini-20261003/.
The four fixes preserve raw strict cursor input until validation, honor fail-fast=false for unavailable optional native resources, capture complete configuration at adapter construction, and share basic direct-query argument checks. The Template → adapter SPI → backend structure and Java 17 baseline remain unchanged. This historical validation covered source updates after the published 2.0.0 artifact, before preparing the 2.1.0 release; that source-only step did not publish a new Maven version. These fixes are now included in 2.1.0.
| Runtime | Actual validation scope | Result |
|---|---|---|
| JDK 17.0.14 / Boot 2.7.18 | Complete unit suite | 723 passed |
| JDK 21.0.11 / Boot 3.5.14 | Complete unit suite | 723 passed |
| JDK 25.0.2 / Boot 4.1.0 | Complete unit suite | 723 passed |
| JDK 17.0.14 / Boot 2.7.18 | Complete Docker regression: IoTDB 2.0.10 / SDK 2.0.11, InfluxDB OSS 1.13.1, InfluxDB 3 Core 3.11.5 | 114 passed: 106 backend + 8 starter cases |
| Java 17 unsigned artifact audit | Seven binary, seven sources and seven Javadoc JARs | Passed |
All final cases passed with zero failures, errors or skips. The 85 additional unit cases cover malformed cursor entries and normalized collisions, valid whitespace and case-distinct keys in both InfluxDB 3 strategies, optional native-client injection and startup cleanup, configuration consistency through initialization retries and IoTDB recovery, and invalid direct queries/count time ranges before I/O. Count continues to ignore pagination and cursors. The final source manifests match all production, test and build inputs. Validated source snapshot.
Each backend adds one Docker regression that changes the original Properties before and after initialization, then verifies adapter/native-client reads still use the captured database and invalid queries leave the connection usable. The InfluxDB cases also exercise native writes, and the InfluxDB 3 case verifies a valid whitespace-padded strict cursor. Existing cursor, write, limit, lifecycle and starter scenarios were rerun. Only cached images were used; all test containers were removed.
Local reports remain ignored under .local-test/design-fixes-20261003/: docker-final/, unit-jdk21/, unit-jdk25/ and validation-summary.json. The earlier compile failure and intermediate successful run are retained separately; the counts above describe the final source. Other database/SDK versions below were not rerun for this change and retain their historical evidence. See source change history for configuration migration and optional native-client access.
All three backends now default to false and require explicit enable: true. Connection settings alone leave the backend inactive. Plain application.yml works without an active Spring profile; other backends need no false flags.
| Runtime | Validation | Result |
|---|---|---|
| JDK 17.0.14 / Boot 2.7.18 | Complete unit suite | 638 passed |
| JDK 21.0.11 / Boot 3.5.14 | Complete unit suite | 638 passed |
| JDK 25.0.2 / Boot 4.1.0 | Complete unit suite | 638 passed |
| JDK 17.0.14 / Boot 2.7.18 | Complete Docker regression: IoTDB 2.0.10 with SDK 2.0.11, InfluxDB OSS 1.13.1, InfluxDB 3 Core 3.11.5 | 111 passed |
| Java 17 unsigned release audit | Binary, sources and Javadoc archives | Passed |
All cases passed with zero failures, errors or skips. Tests cover explicit activation, missing/false flags, plain YAML, environment variables and custom property sources, invalid flags, conflict detection before construction, and no connection binding or client creation for inactive backends. Docker starter cases verify real writes, reads and native clients while retained settings for inactive backends contain unresolved placeholders.
The Docker run also repeated all 638 unit cases. Cached images were reused and all test containers were removed. Source manifests for every run match the validated production, test and build inputs. The corresponding source snapshot and CI results are available on GitHub. These results do not extend the database-version support list; earlier version combinations below retain their historical evidence.
The correctness fixes and Maven coordinates were validated against the production sources and POMs. That validated snapshot used Java packages com.alandevise.tsdb.* and Maven artifacts under io.github.alandevise.
| Run | Actual scope | Result |
|---|---|---|
| JDK 17.0.14 / Boot 2.7.18 | Complete unit suite | 634 passed |
| JDK 21.0.11 / Boot 3.5.14 | Complete unit suite | 634 passed |
| JDK 25.0.2 / Boot 4.1.0 | Complete unit suite | 634 passed |
| Representative Docker regression | IoTDB 2.0.10 / SDK 2.0.11, InfluxDB OSS 1.13.1, Core 3.11.5 | 103 backend tests + 8 starter tests passed |
| Older Core 3.0.3 | UNION-only fluent case-distinct column and physical _time / TIME regression |
5 passed |
| Independent consumers | Five projects using the published coordinates, single-BOM imports, Boot parent and IoTDB SDK 2.0.10 override | Dependency resolution and compilation passed; 5 Docker scenarios / 7 Spring contexts passed |
| Unsigned release artifacts | Seven binary, seven sources and seven Javadoc JARs | Coordinates, licenses/notices, source contents, generated API docs and Java 17 bytecode passed; tests excluded |
This earlier validation combines 103 successful backend cases and eight starter cases from separate phases. All final successful results had zero failures, errors or skips. The current 638-unit / 111-integration run above subsequently exercised the complete suite with explicit backend activation.
The independent consumer Docker scenarios additionally used IoTDB 2.0.11 from the locally prepared official-binary image, testing SDK 2.0.11 / 2.0.10 with compression true / false and 12-row writes. They also exercised InfluxDB 1.13.1 and Core 3.11.5, including native Arrow Flight. These smoke scenarios are separate from the representative 111-case suite. All runs reused local images and cleaned up their own containers. Evidence remains under .local-test/2026-09-29-approved-fixes/, including the consumer subdirectory and source manifests. Historical server combinations below retain their original evidence and are not represented as full reruns of every version.
On JDK 17.0.14 / Boot 2.7.18, five independent consumers passed model resolution, dependency-tree inspection and compilation using the single tsgate-bom. Five Docker scenarios / seven Spring contexts also passed: IoTDB 2.0.11 with SDK 2.0.11 and explicit SDK 2.0.10, each with both Tablet settings; InfluxDB OSS 1.13.1; InfluxDB 3 Core 3.11.5 with both a Boot BOM import and the Boot starter parent. Both InfluxDB 3 consumers executed native Arrow Flight queries.
The verified runtime versions remained OkHttp 4.12.0, Netty 4.2.15.Final, gRPC 1.81.0, Arrow 19.0.0 and Jackson 2.21.4. IoTDB SDK overrides followed the selected official SDK dependency family. Cached images were used and all containers were removed. Evidence: .local-test/consumer-bom-20260929/model-summary.json and docker-summary.json. These non-web consumers do not certify arbitrary WebFlux/gRPC coexistence or new database versions.
The default Java SDK is now iotdb-session:2.0.11. Its resolved IoTDB SDK family is 2.0.11, with TSFile / common 2.4.0 and libthrift 0.23.0. The earlier 2.0.10 SDK uses TSFile / common 2.3.1; server and dependency version numbers must not be substituted for each other. See upgrades and SDK overrides for consumer dependencyManagement and dependency-tree checks.
tsdb.iotdb.table.rpc-compression-enabled defaults to true and can be omitted. For older incompatible table-model servers such as 2.0.2, the application explicitly sets it to false. This controls Tablet RPC compact encoding/compression, independently of Thrift transport or disk compression. Passing writes below 10 rows per actual Tablet does not prove that the larger-Tablet encoding is compatible: validate at least 10 rows in one Tablet, then read them back, for the selected SDK/server/setting combination.
With SDK 2.0.11, the complete module unit suite passed 513 tests, with zero failures, errors or skipped cases, on each of JDK 17.0.14 / Spring Boot 2.7.18, JDK 21.0.11 / Spring Boot 3.5.14 and JDK 25.0.2 / Spring Boot 4.1.0. The separate Java 17 unit report is .local-test/2026-09-29-iotdb-sdk-upgrade/java17-all-unit/summary.json; the combined unit/integration reports are in the matrix archive below. These unit tests include the new setting and request encoding checks; they do not replace real-server validation.
The following SDK 2.0.11 update checks have completed. All listed assertions passed with zero failures, errors or skipped cases; an expected rejection is not a successful write.
| JDK / Spring Boot | Actual IoTDB server | Unit / IoTDB Docker integration | Tablet RPC result | Independent application |
|---|---|---|---|---|
| 17.0.14 / 2.7.18 | 2.0.2 | Unit suite recorded separately above; 38 IT | Existing 28 IT with false; false writes/readbacks at 9, 10, 12, 1024 and 1025 rows passed. true at 9 rows passed; four true cases at 10/12/1024/1025 rows correctly asserted rejection |
Default SDK 2.0.11, false, 12 rows in one Tablet, Spring binding and close passed |
| 17.0.14 / 2.7.18 | 2.0.10 | 513 / 38 | Existing 28 IT with default true; both true and false writes/readbacks at 9, 10, 12, 1024 and 1025 rows passed |
Default SDK 2.0.11 and explicit SDK 2.0.10 override each passed both settings at 12 rows, Spring binding and close |
| 21.0.11 / 3.5.14 | 2.0.11 | 513 / 38 | Existing 28 IT with default true; both settings passed all five row-count boundaries |
Default SDK 2.0.11 passed both settings at 12 rows, Spring binding and close |
| 25.0.2 / 4.1.0 | 2.0.11 | 513 / 38 | Existing 28 IT with default true; both settings passed all five row-count boundaries |
Default SDK 2.0.11 passed both settings at 12 rows, Spring binding and close |
The 1025-row case crosses the default 1024-row Tablet split. On server 2.0.2, the four expected rejection cases confirmed status 301, the adapter's UNKNOWN commit state and zero visible rows after the failed write. They do not authorize retrying arbitrary failed writes or using default true for production batches on that server. The four combinations completed 152 integration assertions in total, including those four expected rejections, and five independent consumer runs. These counts do not mean 152 successful write cases or certify other combinations.
The independent applications do not inherit TsGate's parent POM. The SDK 2.0.10 override used the same TsGate JAR already compiled against SDK 2.0.11; its actual dependency graph contained IoTDB SDK family 2.0.10, TSFile / common 2.3.1 and libthrift 0.14.1, with no mixed SDK-family versions. This verifies the stated 12-row consumer scenarios, not a full SDK 2.0.10 regression matrix. Reports and dependency trees are archived under .local-test/2026-09-29-iotdb-sdk2011/java17-boot2718-iotdb202/ and the sibling java17-boot2718-iotdb2010/, java21-boot3514-iotdb2011/ and java25-boot410-iotdb2011/ directories.
These SDK/encoding tests predate the later API, lifecycle and activation fixes. They retain their original source snapshot and counts; the current representative regression is listed above. No all-version or future-version compatibility guarantee follows from this switch or dependency upgrade.
After implementing the selector, the complete module unit suite passed 564/564 tests on JDK 17.0.14 / Spring Boot 2.7.18, with zero failures, errors or skipped cases. This includes 44 new SQL-strategy tests and seven new Spring binding tests in addition to the previous 513 tests. All 77 compiled project production classes retain class major 61 (Java 17). The command was mvn -o -B clean test; the summary and log are .local-test/2026-09-29-influx3-union/java17-unit-summary.json and java17-all-unit.log. These are adapter-unit results, not proof that any untested server release is compatible.
The final Docker matrix used the same 57 production/POM files as the working tree, with official client influxdb3-java:1.10.0. All 212 integration test executions passed with zero failures, errors or skipped cases:
| Actual Core server | JDK / Spring Boot | Existing backend + starter tests | New strict-cursor cases | Total IT |
|---|---|---|---|---|
| 3.0.0 | 17.0.14 / 2.7.18 |
union-all: 28 |
11, including an expected legacy OR failure | 39 |
| 3.0.3 | 17.0.14 / 2.7.18 |
union-all: 28 |
11, including an expected legacy OR failure | 39 |
| 3.10.0 | 21.0.11 / 3.5.14 |
or: 28, union-all: 28 |
11 | 67 |
| 3.11.5 | 25.0.2 / 4.1.0 |
or: 28, union-all: 28 |
11 | 67 |
The existing 28 comprise 25 backend tests, two starter tests and one all-starters coexistence test. The 11 new cases cover complete traversal with four sort shapes, mixed directions and FIELD-first ordering, equal timestamps and multiple tags, explicit projections and hidden sort keys, case-sensitive value / Value columns, outer OFFSET, inclusive time-boundary pruning, all-empty branches and row-limit protection. On each old server, one of those cases asserts HTTP 500 / CONNECTION_ERROR for four legacy OR shapes. An expected rejection is a passing test of the error contract, not proof that OR works on that server. Native SQL remains unchanged.
Seven configuration-binding tests also passed on JDK 21.0.11 / Boot 3.5.14 and JDK 25.0.2 / Boot 4.1.0: 14 additional unit executions, separate from the 212 IT and the full Java 17 suite above. Together with the Java 17 binding checks, they verify that omitted/blank values retain or, both documented values bind, and nonblank invalid values fail. This is not a claim that all 564 unit tests were rerun on the two newer runtimes for this SQL change.
The exact verified older-server baseline is Core 3.0.0 with explicit tsdb.influxdb.strict-cursor-sql=union-all; Core 3.0.3 uses the same requirement for strict cursors. Core 3.10.0 / 3.11.5 passed both strategies and may retain the default or. No intermediate, future, Enterprise or Cloud release is certified by these results. The archive .local-test/2026-09-29-influx3-union/ contains summary.json, REPORT.zh-CN.md, per-version XML/logs, actual process versions, image digests and source hashes. Only cached images were used; the test containers were removed after validation. Earlier attempts remain separate from the final matrix.
Separate native SQL probes on Core 3.0.3 and 3.11.5 checked four sort shapes across four pages, hidden projections and OFFSET. They also reproduced planner HTTP 500 for contradictory time bounds on both versions; omitting proven-empty branches and using an explicit false predicate for an all-empty cursor result returned HTTP 200. These probes are not included in the 212 IT count and do not establish general compatibility for arbitrary native SQL.
The observed strict composite-cursor second-page HTTP 500 belongs to InfluxDB 3 Core 3.0.0 / 3.0.3, not InfluxDB 1.x. In the earlier server audit, each old Core version passed 27 of 28 checks and failed that cursor case; Core 3.11.5 passed all 28. Direct native HTTP SQL reproduced the 3.0.3 planner failure. InfluxDB 1.x has a different InfluxQL adapter and explicitly rejects strict composite cursors with UNSUPPORTED_OPERATION.
The earlier audit used the OR SQL form and remains historical evidence under .local-test/compat-audit-20260929/influxdb3/. TsGate now implements explicit tsdb.influxdb.strict-cursor-sql: union-all for structured strict-cursor continuation; the default remains or. There is no automatic version detection or HTTP 500 retry. Configuration-specific validation must be recorded separately from the original failures, and a passing exact version does not certify intervening releases. See configuration and pagination boundaries.
Test sources under each module's src/test/ are committed. The shared runner and pinned Docker settings are also under tsgate-core/src/test/. Local reports, downloaded fixtures and credentials remain ignored. From a checkout with Java 17+, Maven 3.9+, Python 3 and Docker for integration tests:
python3 tsgate-core/src/test/scripts/run-tests.py unit --spring-boot 2.7.18
python3 tsgate-core/src/test/scripts/run-tests.py unit --spring-boot 2.7.18 --release-artifacts
python3 tsgate-core/src/test/scripts/run-tests.py docker --spring-boot 2.7.18Choose JAVA_HOME for the selected JDK. Pass --offline --maven-repo /path/to/cache when using a prepared dependency cache; --pull never reuses available Docker images. Reports go to a fresh .local-test/ci/ directory unless --output selects another new directory. The shared representative Docker configuration uses official IoTDB 2.0.10, InfluxDB OSS 1.13.1 and InfluxDB 3 Core 3.11.5; it does not depend on the local custom IoTDB 2.0.11 image used by historical runs.
GitHub CI runs the three documented JDK / Boot unit combinations; Java 17 also builds unsigned release attachments. Docker runs only when a maintainer manually selects run_docker=true. See testing and publishing. The historical .local-test/ scripts and reports above preserve earlier experiment evidence and are not prerequisites for the shared runner. The verified GitHub Actions run passed all three unit combinations and the Java 17 unsigned artifact audit; its Docker job was not requested.
Server-version compatibility and database feature coverage are separate goals. TsGate aims to provide consistent contracts for its documented common capabilities while preserving explicit backend differences. It does not promise to unify every database feature or make SQL and InfluxQL equivalent.
The support policy uses an explicit version list. The earlier full matrix verified IoTDB table model 2.0.10 / 2.0.11 with SDK 2.0.10, InfluxDB 3 Core 3.10.0, and InfluxDB OSS 1.13.1; the separate Core audit additionally verified 3.11.5. The new IoTDB SDK/compression combinations and the InfluxDB 3 cursor-strategy matrix are tracked above rather than inferred from that older matrix. The latter additionally verifies Core 3.0.0 / 3.0.3 with explicit union-all, and both strategies on 3.10.0 / 3.11.5. None of these observations is an unrestricted >= promise. A claim such as “supported from X” must also identify the highest verified version, product edition, and supported capabilities. Continue listing individual versions when intermediate releases have not been tested. Future releases enter the support list only after regression testing.
IoTDB table model 2.0.2 is now an exact verified older target with SDK 2.0.11 and explicit Tablet RPC compression false. This does not certify untested intermediate or earlier versions. Older InfluxDB 1.x releases and other IoTDB SDK/server/settings combinations still require separate targets and actual testing.
Use the component within the explicitly verified version and capability set. Public source availability does not extend that compatibility scope or establish a production service-level guarantee.
Existing foundations include independent starters, annotated POJOs and a unified query entry point, centralized configuration, explicit error codes, batch commit states, query resource limits, and real-database regression tests. Routine business reads and writes need relatively little code, but setup costs differ by backend: IoTDB comes closest to adding a starter and configuring a connection; InfluxDB 1.x also requires OkHttp / Jackson alignment; InfluxDB 3 additionally requires Arrow / Netty / gRPC coordination and Arrow JVM options. All three backends are disabled by default. Configure the chosen backend directly in application.yml and explicitly set its enable flag to true. No spring.profiles.active option or enable: false entries for other backends are required. Missing or false flags keep a backend inactive even when connection settings are present. Only one backend is currently allowed in a Spring context.
The approved strict-cursor, IoTDB numeric/lifecycle and result-type fixes now have dedicated regression tests. Historical matrices above retain their original snapshots and counts; they do not automatically certify the updated implementation. Public stability also requires authentication/TLS, recovery, application-dependency coexistence and dependency-security validation appropriate to the supported deployment scope.
← Mapping and backend limits · Upgrades, APIs and licensing →
TsGate 2.1.0 includes the independent OpenGemini adapter and starter. See OpenGemini integration for configuration, default-engine limits and exact-version testing, and 2.1.0 release notes for migration requirements.
TsGate · Wiki home · 文档首页 · Apache-2.0 · NOTICE
Compatibility claims apply only to documented capabilities and verified versions. 兼容性承诺仅适用于已列明的能力和已验证的版本。