EN Overview

Home · GitHub

English | 简体中文

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 retains com.alandevise.tsdb.*. See migration steps and release status.

TsGate

TsGate provides time-series database adapters for Spring Boot applications. It separates shared functionality into a core module, backend-specific adapters and four independent starters in 2.1.0. Add the relevant starter to obtain an auto-configured TGTemplate, then use annotated Java POJOs for writes, fluent queries and native queries. Applications that need custom configuration can depend on an adapter directly and configure their own beans.

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.

The historical verified backend versions include the exact combinations documented in the validation guide:

• IoTDB table model, default SDK iotdb-session:2.0.11. Verified servers: 2.0.2 with explicit tsdb.iotdb.table.rpc-compression-enabled=false, and 2.0.10 / 2.0.11 with both settings. Exact JDK / Boot / SDK combinations and historical results are recorded in the validation guide; untested intermediate releases are not certified.
• InfluxDB 3 Core 3.0.0 / 3.0.3 with explicit tsdb.influxdb.strict-cursor-sql=union-all, and 3.10.0 / 3.11.5 with default or or explicit union-all (influxdb3-java:1.10.0). The setting affects structured strict-cursor continuation; exact runtime/strategy checks are recorded in the validation guide.
• InfluxDB OSS 1.13.1, using InfluxQL (influxdb-java:2.25).
• openGemini 1.4.1 / 1.5.2 default engine, using compatible HTTP/InfluxQL (influxdb-java:2.25), tested as single nodes and three-node/three-replica clusters.

These are specific verified releases, not a promise of compatibility with every release in the corresponding version family. Other IoTDB table-model releases, InfluxDB 3.x releases InfluxDB 1.x releases and other openGemini versions/engines remain unverified. InfluxDB 3 Core 3.0.0 / 3.0.3 still reject the original OR strict-cursor shape; their verified support requires the explicit UNION strategy. Native SQL is not rewritten and there is no automatic strategy fallback. InfluxDB Enterprise, Cloud and 2.x are not certified by this matrix.

All four 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. At most one backend may be active in a Spring context; multiple true flags fail before initialization. With no enabled backend, no adapter, template or native client bean is created. See the configuration guide.

Module structure

Module	Responsibility
tsgate-core	Shared annotations, models, metadata parsing, TGQueryBuilder, TGTemplate and TSDBException
tsgate-iotdb	IoTDB table-model adapter, also usable with application-managed configuration
tsgate-influxdb3	InfluxDB 3 Core adapter, also usable with application-managed configuration
tsgate-iotdb-spring-boot-starter	IoTDB adapter auto-configuration
tsgate-influxdb3-spring-boot-starter	InfluxDB 3 Core auto-configuration
tsgate-influxdb1	InfluxDB OSS 1.x / InfluxQL adapter
tsgate-influxdb1-spring-boot-starter	InfluxDB OSS 1.x auto-configuration
tsgate-opengemini	openGemini default-engine InfluxQL adapter; added in 2.1.0
tsgate-opengemini-spring-boot-starter	Independent openGemini auto-configuration; added in 2.1.0

The application API is TGTemplate; fluent queries use TGQueryBuilder<T>. The four TG* annotations describe measurement, time, tag and field mapping. Shared metadata converts them into the existing TSDBRecord / TSDBQuery models, and the existing TSDBAdapter SPI dispatches work to the active backend. The current source uses com.alandevise.tsgate.annotation and com.alandevise.tsgate.core.

Features

• Single-record and batch writes from annotated POJOs.
• Conversion to a shared internal record using @TGMeasurement, @TGTime, @TGTag and @TGField.
• IoTDB table-model writes assembled into Tablets by measurement.
• InfluxDB and openGemini writes encoded as batched line protocol.
• Complete batch validation before I/O, with BatchWriteResult distinguishing successful, uncommitted, partially committed and unknown outcomes.
• Fluent queries with time ranges, tag/field predicates, projections, aggregates, time windows, sorting, limits, offsets and pagination.
• Result mapping to application objects without exposing the internal QueryResult.
• Native queries through executeQuery(...).
• A native client bean for the active adapter, available through @Autowired; openGemini uses the compatible org.influxdb.InfluxDB client rather than the openGemini-specific SDK.
• Unified TSDBException errors with six-digit application error codes for arguments, configuration, metadata, connections and database execution. Underlying client, HTTP or database exceptions are retained as the original cause.
• A startup banner displaying TsGate, the build version and the initialized backend.

The banner uses the MINI font style, with its version loaded from the build resource:

___  __
 | _/__ _._|_ _
 |_>\_|(_| |_(/_
TsGate 2.1.0 · InfluxDB1 initialized

---

Getting started →