Repository navigation
EN Getting Started
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.
Use the 2.1.0 dependency set below with com.alandevise.tsgate.* examples. Choose the starter for the required backend, or use its adapter directly. Consumers upgrading from 2.0.0 must migrate imports and recompile; Central 2.0.0 has the old namespace and no OpenGemini modules. Confirm release status before resolving the new version.
IoTDB starter:
<dependency>
<groupId>io.github.alandevise</groupId>
<artifactId>tsgate-iotdb-spring-boot-starter</artifactId>
<version>2.1.0</version>
</dependency>InfluxDB 3 Core starter, which may appear alongside the dependency above in the same POM:
<dependency>
<groupId>io.github.alandevise</groupId>
<artifactId>tsgate-influxdb3-spring-boot-starter</artifactId>
<version>2.1.0</version>
</dependency>InfluxDB OSS 1.x starter:
<dependency>
<groupId>io.github.alandevise</groupId>
<artifactId>tsgate-influxdb1-spring-boot-starter</artifactId>
<version>2.1.0</version>
</dependency>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.
OpenGemini starter dependency:
<dependency>
<groupId>io.github.alandevise</groupId>
<artifactId>tsgate-opengemini-spring-boot-starter</artifactId>
<version>2.1.0</version>
</dependency>Enable it with tsdb.opengemini.enable=true; set url and database under tsdb.opengemini. The implementation dependency on InfluxDB1 does not activate that backend. Only one of the four backend enable flags may be true. The borrowed native client is the compatible org.influxdb.InfluxDB. See the dedicated guide for complete settings.
The business-facing API uses TGTemplate and TGQueryBuilder<T> in com.alandevise.tsgate.core, plus TGMeasurement, TGTime, TGTag and TGField in com.alandevise.tsgate.annotation. The active starter's default template bean is tgTemplate. See the complete POJO and injection example and template configuration.
For the OpenGemini adapter, a successful write acknowledges the request; a new measurement or new tag series may become query-visible later, after the server merges its index. When following the write/read examples, establish visibility of the expected timestamp, tags and field values with an explicit read-side poll and a deadline if the application needs to observe its write. Each adapter query sends one request; TsGate adds no transparent visibility retry. See OpenGemini integration.
| Layer | Baseline / pinned client | Notes |
|---|---|---|
| Java | JDK 17 | Compiled with --release 17, without preview features; the exact tested JDK combinations are listed in Compatibility and validation
|
| Spring Boot starter | 2.7.18 | Uses auto-configuration imports introduced in 2.7; 3.x / 4.x require the client dependency alignment described below |
| Build tooling | Maven 3.9+ | 2.1.0 has nine JAR modules, plus the parent and standalone BOM |
| IoTDB server | 2.0.2 table model with RPC compression disabled | Default iotdb-session:2.0.11; 2.0.2 requires tsdb.iotdb.table.rpc-compression-enabled=false. See the exact SDK/server/configuration matrix; tree model is unsupported |
| InfluxDB 3 server | Core 3.0.0 with union-all |
Pinned influxdb3-java:1.10.0; Core 3.0.0 / 3.0.3 require explicit tsdb.influxdb.strict-cursor-sql=union-all for strict cursors. Core 3.10.0 / 3.11.5 support default or; see the exact validation matrix |
| InfluxDB 1 server | 1.13.1 OSS | Pinned org.influxdb:influxdb-java:2.25; uses the 1.x HTTP API and InfluxQL; no compatibility claim for other 1.x releases |
| openGemini default engine | 1.4.1 / 1.5.2, single node and three-node/three-replica cluster | Compatible org.influxdb:influxdb-java:2.25; exact topology/configuration results are recorded in OpenGemini integration
|
The IoTDB RPC setting defaults to true and normally needs no YAML entry. It controls Tablet payload encoding, independently of Thrift transport and disk compression. For 2.0.2 use explicit false, and verify at least 10 rows in one actual Tablet. To override the default SDK in a consuming application, use the artifact-level dependencyManagement example; setting only an application iotdb.version property does not override the starter's transitive SDK.
Records were finalized in Java 16, but this project and the InfluxDB Java client establish a Java 17 baseline. Java 8 and 11 are unsupported. Public models use records, and source code stays within the Java 17 language and API baseline.
A baseline is the lowest release covered by the current regression-backed support commitment, not a claim about the earliest database release that might theoretically work. Newer database versions also require upgrade validation. InfluxDB 3 support is configuration-specific: Core 3.0.0 / 3.0.3 passed the updated Docker suite with explicit union-all, while their default OR strict-cursor query remains incompatible. This does not establish support for every intervening 3.x release. Spring Boot 2.7.18 is a compatibility target, not a claim that it remains under upstream open-source maintenance. Applications do not have to inherit this project's parent POM.
TsGate does not currently promise compatibility with every IoTDB table-model, InfluxDB 3.x, InfluxDB 1.x or openGemini release. Individual testing of every release has not been performed.
| Product | Full regression passed | Known incompatibilities | Unverified scope |
|---|---|---|---|
| Apache IoTDB table model | SDK 2.0.11 with server 2.0.2 (false required), 2.0.10 and 2.0.11 (both settings); exact runtime combinations are recorded in the validation guide |
2.0.2 rejects the tested newer Tablet encoding when compression is true and a Tablet has at least 10 rows |
Other SDK/server/configuration combinations; the tree model is outside the adapter's scope |
| InfluxDB 3 Core | 3.0.0 / 3.0.3 with explicit union-all; 3.10.0 / 3.11.5 with either strategy (default or); exact runtime/strategy combinations are listed in the validation guide |
The original or strict-cursor shape on 3.0.0 / 3.0.3 still returns HTTP 500, exposed as CONNECTION_ERROR; native SQL is not rewritten |
Other 3.x releases, and Enterprise / Cloud products |
| InfluxDB OSS 1.x | 1.13.1 | No blocking issues found in this tested release | Other 1.x releases, and the Enterprise product |
| openGemini default engine | 1.4.1 / 1.5.2, single node and three-node/three-replica cluster | The HTTP integer path requires precision preflight; new-series query visibility is asynchronous | Other versions/engines, COLUMNSTORE/Arrow, TLS/authentication and node/ingress failover |
Unverified does not mean known to be incompatible, but it is not a compatibility commitment. Sharing a major version or having a newer patch number cannot replace regression testing. These compatibility conclusions apply only to the adapter capabilities documented in this Wiki, not every feature of each database. Unit tests validate Java logic and simulated scenarios; real Docker database integration tests validate server compatibility. The validation matrix covers only the explicitly listed JDK / Spring Boot / database combinations, not every release or their full Cartesian product.
As of 2026-09-25, InfluxDB 1.x version 1.13.1 was verified as the latest stable release against the official Docker image and source tag. IoTDB 2.0.11 is available as an official distribution.
Import io.github.alandevise:tsgate-bom:2.1.0 once instead of copying five separate runtime BOMs. It manages all nine TsGate JAR modules, including OpenGemini, and aligns the selected IoTDB and InfluxDB 3 SDKs and verified OkHttp / Netty / gRPC / Arrow / Jackson versions. It has no project parent and does not import Spring Boot, JUnit or Mockito. Dependency management does not add unused database clients to the application classpath.
The following example is for an application without the Spring Boot parent. Keep the TsGate import before the Boot BOM. Select the application's Boot version explicitly; the BOM does not raise the Java 17 baseline.
<properties>
<spring-boot.version>2.7.18</spring-boot.version>
<maven.compiler.release>17</maven.compiler.release>
</properties>
<dependencyManagement>
<dependencies>
<dependency>
<groupId>io.github.alandevise</groupId>
<artifactId>tsgate-bom</artifactId>
<version>2.1.0</version>
<type>pom</type>
<scope>import</scope>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-dependencies</artifactId>
<version>${spring-boot.version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>After importing this BOM, the selected starter dependency can omit its version. A starter's transitive POM cannot automatically override application dependency management; the explicit import remains necessary when alignment is required. Application-level explicit versions still take precedence, so inspect mvn dependency:tree before deployment. With the Spring Boot starter parent, import only the TsGate BOM in the application dependencyManagement and omit the Boot BOM shown above. The Boot parent 2.7.18 variant passed dependency-tree, write/read and native Arrow Flight checks; other business dependency combinations still need their own validation.
Applications using only IoTDB may keep their starter's default dependency graph without importing the BOM. InfluxDB 1.x and the openGemini compatibility adapter need OkHttp / Jackson alignment but no Arrow JVM options. A single combined BOM also manages Netty / gRPC / Arrow versions used elsewhere in an application, even when those libraries are introduced by other components; validate WebFlux and other gRPC integrations in that application.
To select an IoTDB SDK version, declare org.apache.iotdb:iotdb-session directly in the application's dependencyManagement, as in the upgrade guide. Setting an application property named tsgate.iotdb.version does not rewrite an already imported BOM. The selected official SDK POM supplies its matching RPC / TSFile / Thrift family; inspect conflicts rather than assigning the SDK version to every artifact.
Do not import the TsGate root build POM as a consumer BOM: it also manages build and test dependencies. The runtime BOM does not set Java launcher options. See Maven dependency management.
For local development or testing source changes, run the command below from the TsGate repository root to install the aligned 2.1.0 modules and BOM into the local Maven repository. A local installation is not a Central publication; do not build the migrated source with 2.0.0 coordinates or replace an existing Central release.
mvn clean install -DskipTestsWindows PowerShell:
mvn clean install "-DskipTests"The official InfluxDB 3 client uses Apache Arrow and requires this JVM option:
--add-opens=java.base/java.nio=ALL-UNNAMED
Applications using only IoTDB, InfluxDB 1.x or the openGemini compatibility adapter do not need this Arrow option. On Java 25, the official Arrow client may additionally use --sun-misc-unsafe-memory-access=allow as described upstream. Pass JVM options to the Java process that actually runs the application.
This is a JVM module-access option, not a YAML setting or a system property that an ordinary library can add after the JVM starts. TsGate does not use self-attaching agents or reflective module-opening workarounds. For the tested classpath / Spring Boot executable-JAR setup:
java --add-opens=java.base/java.nio=ALL-UNNAMED -jar application.jarIn an IDE, place it in VM options, not program arguments. In a container, append it to the application's Java command or the existing JDK_JAVA_OPTIONS value without discarding other options. For Maven-run tests, configure the consuming application's Surefire/Failsafe argLine; TsGate's own test configuration is not inherited through the starter.
This does not certify JPMS/module-path execution, which may require named-module opens/reads described in the Arrow installation guide. Replacing the native Arrow client or making it optional is a separate API/design change, not part of BOM consolidation.
← Overview · Configuration and database selection →
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. 兼容性承诺仅适用于已列明的能力和已验证的版本。