EN Getting Started

Home · GitHub

English | 简体中文

Maven dependencies

Version 2.0.0 has been uploaded to Central Portal and passed validation; it is awaiting publication and is not yet downloadable from Maven Central. To use this checkout now, run mvn install at the repository root before adding the dependencies below.

IoTDB starter:

<dependency>
  <groupId>io.github.alandevise</groupId>
    <artifactId>tsgate-iotdb-spring-boot-starter</artifactId>
    <version>2.0.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.0.0</version>
</dependency>

InfluxDB OSS 1.x starter:

<dependency>
    <groupId>io.github.alandevise</groupId>
    <artifactId>tsgate-influxdb1-spring-boot-starter</artifactId>
    <version>2.0.0</version>
</dependency>

The business-facing API uses TGTemplate and TGQueryBuilder<T> in com.alandevise.tsdb.core, plus TGMeasurement, TGTime, TGTag and TGField in com.alandevise.tsdb.annotation. The active starter's default template bean is tgTemplate. See the complete POJO and injection example and template configuration.

Minimum requirements and compatibility scope

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+	The seven JAR modules and standalone BOM use version 2.0.0
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

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.

Server-version verification status

TsGate does not currently promise compatibility with every IoTDB table-model, InfluxDB 3.x or InfluxDB 1.x 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

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.

Aligning client dependencies with the TsGate BOM

Import io.github.alandevise:tsgate-bom:2.0.0 once instead of copying five separate runtime BOMs. It manages the seven TsGate JAR modules, the selected IoTDB and InfluxDB 3 SDKs, and the 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 your application's 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.0.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 needs 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.

All modules use Maven groupId io.github.alandevise. Install them into the local Maven repository:

mvn clean install -DskipTests

Windows PowerShell:

mvn clean install "-DskipTests"

Runtime requirements

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 or InfluxDB 1.x 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.

Supplying the Arrow JVM option

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.jar

In 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 →