EN Upgrades and Migration

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.

Java package migration in 2.1.0

TsGate 2.1.0 moves all Java packages from com.alandevise.tsdb.* to com.alandevise.tsgate.*. Matching source and test directories move from com/alandevise/tsdb/ to com/alandevise/tsgate/. The published 2.0.0 artifacts retain the old packages. This release uses the maintainer-selected version 2.1.0, although the package rename is binary incompatible; the minor version number does not remove the migration requirement.

2.0.0	2.1.0
com.alandevise.tsdb.annotation.TGMeasurement	com.alandevise.tsgate.annotation.TGMeasurement
com.alandevise.tsdb.core.TGTemplate	com.alandevise.tsgate.core.TGTemplate
com.alandevise.tsdb.adapter.TSDBAdapter	com.alandevise.tsgate.adapter.TSDBAdapter
src/main/java/com/alandevise/tsdb/	src/main/java/com/alandevise/tsgate/
src/test/java/com/alandevise/tsdb/	src/test/java/com/alandevise/tsgate/

Update imports and fully qualified references in consuming applications and libraries, including annotations, templates, adapter interfaces, models, configuration and exception types. Update reflection class names, @ComponentScan / package-scan settings, explicit Spring configuration imports and any application-owned resource entries that refer to old classes. SQL logging now uses com.alandevise.tsgate.adapter.impl; update an explicitly configured old logger category. Recompile applications and dependent libraries against the complete 2.1.0 artifact set.

This is a binary-incompatible package change: old-package classes and forwarding aliases are not retained. An application or library compiled against com.alandevise.tsdb.* cannot link to the migrated JARs without updating its references and recompiling. Align the TsGate dependency set so applications and their dependent libraries use the same namespace. The namespace-only rename commit 2cecd41 is separate from feature changes. All 91 existing Java files were detected as renames and passed Git history-follow checks; their prior history remains traceable.

Use git log --follow -- path/to/File.java to follow a renamed file into its previous path. The root .git-blame-ignore-revs lists only this mechanical migration commit so GitHub blame can skip it and retain earlier line attribution. For a local file, run git blame --ignore-revs-file .git-blame-ignore-revs -- path/to/File.java; no user Git configuration change is required. See GitHub blame documentation.

The Maven groupId remains io.github.alandevise; artifactIds, YAML keys under tsdb.*, the tgTemplate bean name, TG* / TSDB* type names and the Template → adapter SPI → backend design remain unchanged. Do not rename YAML configuration to tsgate.*. Align parent/BOM/module dependencies at 2.1.0; do not replace or republish Central 2.0.0. Version 2.1.0 also includes the documented behavioral fixes and OpenGemini support below.

Existing JSON/XML reports, logs, source manifests and immutable source links retain the snapshots actually tested. The post-migration regression is recorded separately under .local-test/package-migration-20261003/; it verifies the new namespace without rewriting historical evidence. Final 2.1.0 release-build verification and publication are tracked separately in Testing and publishing.

Explicit backend activation

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. Spring profiles are optional application configuration tools, not a TsGate requirement.

Database and component upgrades

Database servers, official Java clients and TsGate have independent versions. Do not automatically update client dependencies whenever a database release appears, or copy the server version number into the component version.

1. Read the official release notes and migration guide. Check changes to protocols, authentication, SQL dialects, data types, batch-write error semantics and the Java baseline.
2. Pin the new client and Docker image versions on an upgrade branch. When rebuilding TsGate, update iotdb.version for IoTDB; consuming applications instead use the artifact-level dependency override described below. For InfluxDB 3, update influxdb3-java.version and review Arrow / Netty / gRPC / OkHttp / Jackson. For InfluxDB 1.x, update its influxdb-java dependency and review OkHttp / Jackson. Inspect the final dependency tree.
3. Test both the current minimum supported server and the target server: writes/queries, native clients, pagination counts, nulls and precision, partial batch failures, recovery after disconnect, concurrent closure, DST windows and row/byte limits. Then run the documented JDK / Boot consumer matrix.
4. Adapt SQL or protocol changes in the backend module first. Retaining an old-version branch or adding capability detection requires tests against both versions. If old-version support cannot be maintained, explicitly raise the baseline and document migration steps in both Wiki languages.
5. Choose the component version using the table below, keeping all current source JAR modules and the standalone BOM aligned. Update compatibility, dependency examples, configuration and change history in both Wiki languages, together with both repository overview READMEs, before release. Retain older artifacts, validate application upgrades in an independent environment and prepare a rollback.

Component version	When to use it	Example
PATCH 2.0.x	Fix preserving supported contracts, or a fully compatible dependency security patch verified by regression tests	Fixing a leaked result handle
MINOR 2.x.0	Backward-compatible features, optional settings, additional supported servers or a lower Java baseline	Adding configurable query protection
MAJOR 3.0.0	Incompatible public API/behavior changes, backend removal or a higher minimum Java / Boot / server version	Requiring Java 21 or dropping IoTDB 2.0.10

The current release is explicitly numbered 2.1.0; its namespace change remains binary incompatible and requires the migration above. For future releases, even an upstream client PATCH release can affect SQL, memory or runtime dependencies. Select the TsGate version according to actual compatibility rather than mechanically copying upstream versioning.

Maven coordinates

TsGate artifacts use Maven groupId io.github.alandevise, associated with the maintainer’s AlanDevise GitHub identity. Version 2.1.0 aligns the parent, standalone tsgate-bom and nine JAR modules, including the new OpenGemini adapter/starter. Java packages are com.alandevise.tsgate.*. The historical 2.0.0 release contains seven JAR modules and uses com.alandevise.tsdb.*; it remains available unchanged. Maven coordinates and Java package names serve different purposes.

Query and lifecycle contracts

• Strict cursors use backend physical-column identity consistently. InfluxDB 3 preserves case; IoTDB unquoted columns normalize to lowercase. Pass nextCursor unchanged. Missing result cursor columns fail with QUERY_ERROR; invalid input cursor keys/order fail with ARGUMENT_ERROR.
• IoTDB cursor time conversion rejects fractional, non-finite and out-of-range numbers before SQL execution. Exact integral values such as 1.0 are accepted.
• IoTDB follows NEW -> READY -> CLOSED: repeated init preserves the exposed pool proxy; failed init can be retried; close is terminal and waits for adapter operations. Create a new adapter/context after closure. Native session callers coordinate their own operations with shutdown.
• Default aggregate aliases use Locale.ROOT; explicit aliases are preserved. Map result classes are limited to Map, LinkedHashMap, HashMap and TreeMap; unsupported Map types fail before querying, including empty results. TreeMap provides key ordering rather than result-column ordering.

The default SPI method normalizeColumnIdentifier preserves case; backend implementations with folding rules can override it. See compatibility and validation for the exact tested combinations.

TG API and template configuration

Application-facing annotations and query entry points use the TsGate TG prefix:

Public type	Purpose	Package
TGMeasurement	Maps a POJO to a measurement/table	com.alandevise.tsgate.annotation
TGTime	Identifies the timestamp field	com.alandevise.tsgate.annotation
TGTag	Maps a tag field	com.alandevise.tsgate.annotation
TGField	Maps a value field	com.alandevise.tsgate.annotation
TGTemplate	Provides write and query operations	com.alandevise.tsgate.core
TGQueryBuilder<T>	Builds a query for an entity type	com.alandevise.tsgate.core

TGTemplate.query(...) creates a TGQueryBuilder<T> for each query. Annotate entities with @TGMeasurement("telemetry") and the appropriate TGTime, TGTag and TGField annotations; see the complete POJO and injection example.

The active starter's default template bean is tgTemplate. Prefer type-based injection of TGTemplate; for name-based injection, use @Qualifier("tgTemplate") or @Resource(name = "tgTemplate"). A bare @Resource may select by field/property name. Select javax.annotation.Resource or jakarta.annotation.Resource according to the application's Spring generation.

An application-provided TGTemplate makes the starter back off by type. For an application-owned template, keep the chosen bean name and injection points consistent. For example, place this bean factory in an application configuration class:

import com.alandevise.tsgate.core.TGTemplate;
import com.alandevise.tsgate.adapter.TSDBAdapter;
import com.alandevise.tsgate.metadata.TSDBMetadataResolver;
import org.springframework.context.annotation.Bean;

@Bean
TGTemplate tgTemplate(TSDBAdapter adapter, TSDBMetadataResolver metadataResolver) {
    return new TGTemplate(adapter, metadataResolver);
}

YAML configuration uses the tsdb.* prefix. Public models and the adapter SPI include TSDBAdapter, TSDBRecord, TSDBQuery and TSDBException.

Selecting the IoTDB Java SDK version

TsGate's default official org.apache.iotdb:iotdb-session SDK is 2.0.11. This client version is independent of the server version and TsGate's component version. See the exact completed checks on Compatibility and validation; upgrading the SDK alone does not certify every older or future server.

IoTDB's official Java Native API guide recommends matching client and server versions and warns that a newer client can fail against an older server. The older-server checks here are TsGate's specific tested combinations, not a general compatibility endorsement from Apache IoTDB.

When rebuilding TsGate itself, its parent POM's iotdb.version controls the SDK. For a business application that only depends on the starter, declaring an unrelated <iotdb.version> property in the application's POM does not replace the version already resolved by TsGate's dependency POM. Manage the actual artifact in the consuming application's dependencyManagement instead. The following example pins 2.0.11; replace the application-owned property value with another exact SDK release only after testing it:

<properties>
    <app.iotdb-sdk.version>2.0.11</app.iotdb-sdk.version>
</properties>

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.apache.iotdb</groupId>
            <artifactId>iotdb-session</artifactId>
            <version>${app.iotdb-sdk.version}</version>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <dependency>
        <groupId>io.github.alandevise</groupId>
        <artifactId>tsgate-iotdb-spring-boot-starter</artifactId>
        <version>2.1.0</version>
    </dependency>
</dependencies>

Inspect the final graph in the business application, not only this repository:

mvn dependency:tree -Dverbose '-Dincludes=org.apache.iotdb:*,org.apache.tsfile:*,org.apache.thrift:*'
mvn help:effective-pom

Ensure iotdb-session resolves to the selected version and inspect its isession, RPC, Thrift and TSFile dependencies, including omitted/conflicting entries. Start from the dependency versions declared by that SDK's official POM; an application BOM or a nearer dependency can still override them. If such a conflict requires managing another artifact, use the version required for that artifact by the selected SDK. Do not assign the SDK number to every IoTDB-family or TSFile artifact: TSFile and other dependencies have their own release numbers. The standalone tsgate-bom manages the default iotdb-session version; it deliberately lets the selected SDK supply its matching family, so overriding the SDK still requires this check. Maven's dependency-management rules explain the consumer override.

The dependency graphs checked for this change illustrate why those versions must not be flattened:

Official Java SDK	IoTDB SDK family	org.apache.tsfile:tsfile / common	org.apache.thrift:libthrift
2.0.10	2.0.10	2.3.1	0.14.1
2.0.11	2.0.11	2.4.0	0.23.0

The resolved 2.0.11 graph also contains org.apache.thrift:libthrift:0.23.0. The archived graph is .local-test/2026-09-29-iotdb-sdk-upgrade/dependency-tree.log. These are the inspected combinations, not a rule that future SDKs must use these same transitive versions.

The only additional consumer SDK override validated in this change is 2.0.10, with the same TsGate JAR compiled against 2.0.11: on server 2.0.10, each setting passed 12 rows in one Tablet, Spring property binding and closure. This is a bounded consumer check, not full regression certification of that SDK. Do not copy the server version into the SDK property: older SDKs such as 2.0.5 lack the enableIoTDBRpcCompression builder method now required by this adapter and cannot be substituted directly without implementation changes and validation.

Keep Java 17 and the documented Spring Boot baseline, verify table-model API and runtime linkage, and rerun writes/queries, native pool usage, pagination, error semantics and lifecycle cases. Include a single actual Tablet with at least 10 rows for both relevant RPC-compression settings; tiny batches alone do not exercise the compatibility boundary. For an older incompatible server such as 2.0.2, explicitly set tsdb.iotdb.table.rpc-compression-enabled: false as shown in Configuration. Disabling Tablet RPC encoding is not a general guarantee that the server implements all APIs or SQL used by the adapter.

Selecting the InfluxDB 3 strict-cursor SQL strategy

The default tsdb.influxdb.strict-cursor-sql: or retains existing SQL. For Core 3.0.0 / 3.0.3, explicitly configure union-all to use strict-cursor continuation; see Configuration and the exact server/strategy matrix. Omitted or blank configuration retains or; nonblank invalid values fail Spring binding. The adapter captures this setting at construction. There is no server-version probe, automatic fallback or HTTP 500 retry, and native SQL is never rewritten by the switch.

Before changing strategies or upgrading a server, regress both first and subsequent pages with equal timestamps, multiple tags, FIELD-first ordering, mixed directions, explicit projections, business filters and cursor/time-range boundaries. Check page contents and termination, not merely HTTP success. Retain row-limit, response-byte and invalid-cursor checks. Strict cursors combined with aggregation are rejected in union-all mode; ordinary aggregation retains its existing behavior.

UNION branches use the same business filters and mutually exclusive lexicographic comparisons, followed by one outer sort and page limit. Branches proven empty by the cursor time and explicit timeRange / startTime / endTime bounds are omitted; this does not analyze arbitrary filter expressions or rewrite native SQL. Up to one branch per completed cursor key can increase scans and sorting; assess realistic data volumes and time ranges before selecting this mode for newer servers that already support or. A client dependency upgrade is not required to select the SQL strategy. Passing one server/strategy combination does not certify other releases, other products such as Enterprise, or all native SQL.

2.1.0 fixes and additions

Version 2.1.0 incorporates the following fixes after 2.0.0 and adds OpenGemini support. Java 17, the documented Spring Boot/client baselines, and the Template → adapter SPI → backend design are retained. See 2.1.0 release notes for the package migration, exact backend scope and validation status.

• Strict cursor input is preserved until validation, so null-valued, blank, additional or normalized-duplicate keys fail with ARGUMENT_ERROR instead of being discarded. Null/empty maps still mean the first page.
• InfluxDB 3 and IoTDB starters now honor fail-fast=false for resource initialization failures with unavailable optional native clients, matching InfluxDB 1.x. Manual initialization retry does not automatically recreate an unavailable Spring native-client bean.
• All adapters capture complete configuration snapshots at construction. Move any Properties mutation before construction; create a new instance for configuration changes or corrections. Transient initialization retry and IoTDB recovery keep the original snapshot.
• Direct structured query calls consistently reject null queries, nonpositive limits, negative offsets and reversed time ranges before I/O. Count still ignores pagination/cursors; the shared default count implementation also classifies a null query as ARGUMENT_ERROR.
• OpenGemini adapter/starter and BOM integration target 1.4.1/1.5.2 default-engine single nodes and three-node/three-replica clusters. Complete-batch measurement/integer checks, exact missing-measurement handling, compatible native health/version, lifecycle and bounded queries are documented in OpenGemini integration.
• All Java packages, Spring auto-configuration metadata, reflection names, portable runner class names and generated-documentation checks move to com.alandevise.tsgate.*.

See Configuration, Pagination and validation evidence for optional injection, migration details and the exact tested source combinations.

2.0.0 initial release

2.0.0 is TsGate's first public release. It provides:

• A standalone tsgate-bom, independent IoTDB / InfluxDB 3 / InfluxDB 1.x adapters and Spring Boot starters, and the TG* API described above.
• A Java 17 compile/runtime baseline without preview features and a Spring Boot 2.7.18 build baseline. Exact runtime and database combinations are listed in compatibility and validation.
• IoTDB Java SDK 2.0.11 and tsdb.iotdb.table.rpc-compression-enabled, defaulting to true. Older incompatible servers such as 2.0.2 require explicit false. The setting controls Tablet RPC payload encoding, not Thrift transport or disk compression, and applies to initial and replacement pools.
• InfluxDB 3 tsdb.influxdb.strict-cursor-sql: or|union-all, defaulting to or. Explicit union-all supports structured strict-cursor continuation on the verified Core 3.0.0 / 3.0.3 combinations. It preserves key completion, ordering, one-row probing and query limits, rejects strict cursors combined with aggregation, and does not rewrite native SQL or retry queries automatically.
• Explicit conversion errors for invalid numeric text, integer overflow and invalid boolean text; native-query row limits and streaming InfluxDB response-byte limits. Paginate large results or configure suitable limits.
• Idempotent InfluxDB initialization, retryable initialization failure and terminal closure that waits for adapter operations. Create a new instance after close.
• Local-calendar day windows for IoTDB / InfluxDB 3 regional time zones. Regional zones require a time range; sub-day windows crossing offset changes are rejected. InfluxDB 1.x does not support regional calendar-day windows, and all its window queries require explicit start and end times.
• A default database of tsdb for all three backends, configurable through the chosen backend's database property. IoTDB / InfluxDB 1.x require the target database to exist; explicitly blank values fail validation. Configuration does not create or migrate databases.
• Explicit backend activation with enable: true. Missing flags and connection-only configuration leave the backend inactive; other backends need no false flags. Multiple active backends or invalid flags fail configuration.
• English Javadoc and source comments, bilingual Wiki usage documentation, concise English and Chinese README overviews, portable test sources and CI configuration. Source/Javadoc artifacts include license materials; release commands are documented in testing and publishing.
• Apache License 2.0 for project-owned code, with copyright attribution in NOTICE. Third-party components retain their own licenses.

License

Project-owned code is licensed under the Apache License 2.0; copyright attribution is retained in NOTICE. Use, modification and distribution are subject to the license terms. Third-party dependencies retain their own licenses. The standard text comes from the Apache Software Foundation.

Documentation maintenance covers both repository overview READMEs and both Wiki languages. Keep API behavior, configuration, limits, error semantics, compatibility, upgrades, examples and change history synchronized with adapter changes. See testing and publishing for test and release commands.

---

← Compatibility, validation and readiness

OpenGemini in 2.1.0

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.