ZH Upgrades and Migration

Home · GitHub

English | 简体中文

TsGate 2.1.0： 本页使用 com.alandevise.tsgate.*。从 2.0.0 升级时须更新 import、反射类名和包扫描配置，并重新编译。Central 2.0.0 保留 com.alandevise.tsdb.*。详见迁移步骤与发布状态。

2.1.0 Java 包名迁移

TsGate 2.1.0 将全部 Java 包由 com.alandevise.tsdb.* 迁移为 com.alandevise.tsgate.*，源码与测试目录前缀由 com/alandevise/tsdb/ 改为 com/alandevise/tsgate/。已发布的 2.0.0 制品保留旧包名。本次按维护者选择使用 2.1.0；包名变更实际不兼容旧二进制，次版本号不免除迁移要求。

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/

业务应用及依赖库须更新 import 与全限定类名，包括注解、模板、适配器接口、模型、配置和异常类型。同时更新反射类名、@ComponentScan / 包扫描设置、显式 Spring 配置导入，以及业务资源文件中引用旧类名的条目。查询 SQL 日志的分类改为 com.alandevise.tsgate.adapter.impl，显式配置过旧日志分类时也须同步调整。使用完整的 2.1.0 制品集合重新编译应用和依赖库。

这次包名变更不兼容旧包的二进制：不保留旧包类或转发别名。按 com.alandevise.tsdb.* 编译的应用或依赖库，必须更新引用并重新编译后才能链接迁移后的 JAR。应用与依赖库应统一使用同一命名空间的 TsGate 制品。 纯包名迁移提交 2cecd41 与功能变更分开记录；91 个既有 Java 文件均被识别为改名，并通过 Git 历史跟踪检查，旧历史可继续查询。

使用 git log --follow -- path/to/File.java 可沿改名继续查询旧路径的提交。根目录 .git-blame-ignore-revs 只列出本次机械迁移提交，GitHub blame 可跳过它并保留此前的行归属。本地查看时可显式执行 git blame --ignore-revs-file .git-blame-ignore-revs -- path/to/File.java，无需修改用户 Git 配置。详见 GitHub blame 官方说明。

Maven groupId 仍为 io.github.alandevise；artifactId、tsdb.* YAML 配置键、tgTemplate Bean 名、TG* / TSDB* 类型名，以及 Template → adapter SPI → 后端主干设计均保持不变。不要把 YAML 配置改为 tsgate.*。父 POM、BOM 与模块依赖统一为 2.1.0，不替换或重新发布 Central 2.0.0。2.1.0 同时纳入下文所列行为修复与 OpenGemini 支持。

既有 JSON/XML 报告、日志、源码清单及不可变源码链接保留实际测试快照。迁包后的回归单独记录于 .local-test/package-migration-20261003/，验证新命名空间而不改写历史证据。最终 2.1.0 发行构建验证与发布结果另见测试与发布。

显式启用后端

四个后端默认关闭。业务直接在 application.yml 中填写连接参数，并将所需后端的 enable 显式设为 true；无需配置 spring.profiles.active，也无需为其他后端填写 enable: false。省略 enable 或设置为 false 均不启用，即使保留了连接参数。Spring profile 是业务可选的配置组织方式，不是 TsGate 的要求。

数据库与组件升级

数据库服务端、官方 Java 客户端与 TsGate 是三套独立版本。不要随数据库官方发布自动更新依赖，也不要将服务端版本号直接作为组件版本号。

1. 阅读官方 release notes / migration guide，确认协议、认证、SQL 方言、类型、批量写入错误语义和 Java 基线的变化。
2. 在升级分支锁定新的客户端和 Docker 镜像版本；重新构建 TsGate 时 IoTDB 修改 iotdb.version；业务应用应采用下文的实际依赖坐标覆盖方式。InfluxDB 3 修改 influxdb3-java.version 并核对 Arrow / Netty / gRPC / OkHttp / Jackson；InfluxDB 1.x 更新其 influxdb-java 依赖并核对 OkHttp / Jackson。检查最终 dependency tree。
3. 同时验证当前最低支持服务端和计划升级服务端：写入/查询、原生客户端、分页计数、空值和精度、批次部分失败、连接断开恢复、关闭并发、DST 窗口及数量/字节限制。再执行兼容性与验证所列 JDK / Boot 消费者矩阵。
4. SQL 或协议变更优先在后端模块适配；保留旧版本分支或能力检测必须有双版本测试。若无法维持旧版支持，应明确提高最低版本，并在中英文 Wiki 中给出迁移步骤。
5. 按下表选组件版本，全部当前源码 JAR 模块及独立 BOM 的版本保持一致；同步更新中英文 Wiki 的兼容矩阵、依赖示例、配置与变更记录，以及两份仓库概览 README 后发布。保留旧制品，升级应用前在独立环境验证并准备回退。

组件版本	使用情形	例子
PATCH 2.0.x	不改变受支持契约的修复，或经回归且完全兼容的依赖安全补丁	修复结果句柄泄漏
MINOR 2.x.0	向后兼容的新功能、可选配置、增加服务端支持，或降低 Java 基线	新增可配置查询保护
MAJOR 3.0.0	不兼容公共 API/行为变化，移除后端，或提高最低 Java / Boot / 服务端要求	要求 Java 21，移除 IoTDB 2.0.10 支持

本次发行明确使用 2.1.0，但命名空间变更仍不兼容旧二进制，须完成上面的迁移。对于后续发行，上游客户端即使只升 PATCH，也可能影响 SQL、内存或运行时依赖；组件版本按实际兼容性决定，不机械照搬上游版本。

Maven 坐标

TsGate 制品使用 Maven groupId io.github.alandevise，对应维护者 AlanDevise 的 GitHub 身份。2.1.0 对齐父 POM、独立 tsgate-bom 及九个 JAR 模块，其中包含新增的 OpenGemini adapter/starter；Java 包为 com.alandevise.tsgate.*。历史 2.0.0 发行包含七个 JAR 模块并使用 com.alandevise.tsdb.*，继续保留原制品。Maven 坐标与 Java 包名分别承担不同用途。

查询与生命周期契约

• 严格游标统一使用后端物理列身份。InfluxDB 3 保留大小写，IoTDB 非引号列名规范为小写；将 nextCursor 原样传回。结果缺少游标列报 QUERY_ERROR，输入游标键/排序不合法报 ARGUMENT_ERROR。
• IoTDB 在发送 SQL 前拒绝有小数部分、非有限或超界的时间数值；1.0 等精确整数值可以使用。
• IoTDB 采用 NEW -> READY -> CLOSED：重复 init 保留原生池代理，初始化失败可重试，close 为终态且等待适配层操作结束。关闭后须创建新的 adapter/上下文；原生 session 的直接调用由业务协调关闭。
• 默认聚合别名使用 Locale.ROOT，显式别名按原值使用；Map 结果类型限定为 Map、LinkedHashMap、HashMap、TreeMap，其他 Map 类型在查询前即拒绝，空结果也校验。TreeMap 提供键排序，不承诺原结果列顺序。

SPI 默认方法 normalizeColumnIdentifier 保留大小写，有列名折叠规则的后端可以覆盖。准确的已验证组合见兼容性与验证。

TG API 与模板配置

面向业务的注解和查询入口采用 TsGate 的 TG 前缀：

公共类型	用途	包路径
TGMeasurement	将 POJO 映射到 measurement/表	com.alandevise.tsgate.annotation
TGTime	标识时间戳字段	com.alandevise.tsgate.annotation
TGTag	映射 tag 字段	com.alandevise.tsgate.annotation
TGField	映射数值或其他业务字段	com.alandevise.tsgate.annotation
TGTemplate	提供写入与查询操作	com.alandevise.tsgate.core
TGQueryBuilder<T>	为实体类型构建查询	com.alandevise.tsgate.core

TGTemplate.query(...) 为每次查询创建 TGQueryBuilder<T>。实体使用 @TGMeasurement("telemetry")，并按字段用途配置 TGTime、TGTag、TGField；完整 POJO 与注入示例见写入说明。

启用的 starter 默认模板 Bean 名为 tgTemplate。优先按类型注入 TGTemplate；按名称注入时使用 @Qualifier("tgTemplate") 或 @Resource(name = "tgTemplate")。未指定名称的 @Resource 可能按字段/属性名选择 Bean。根据业务所用 Spring 版本选择 javax.annotation.Resource 或 jakarta.annotation.Resource。

业务提供自己的 TGTemplate 后，starter 按类型退让，不再创建模板。自定义模板的 Bean 名应与注入点一致。例如，可在业务配置类中声明以下 Bean 工厂方法：

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 配置使用 tsdb.* 前缀。公共模型与适配器 SPI 包括 TSDBAdapter、TSDBRecord、TSDBQuery、TSDBException。

选择 IoTDB Java SDK 版本

TsGate 默认使用官方 org.apache.iotdb:iotdb-session SDK 2.0.11。客户端版本、数据库服务端版本和 TsGate 组件版本分别管理。准确的已完成验证见兼容性与验证；仅升级 SDK 不代表覆盖所有旧服务端或未来版本。

IoTDB 官方 Java 原生接口指南 建议客户端与服务端版本匹配，并提醒高版本客户端连接低版本服务端存在兼容风险。这里连接旧服务端的实测是 TsGate 的特定组合验证，不是 Apache IoTDB 对该类组合的全面兼容背书。

重新构建 TsGate 本身时，其父 POM 的 iotdb.version 控制 SDK。对于只引入 starter 的业务应用，单独在业务 POM 中声明同名 <iotdb.version> 属性，不会替换 TsGate 依赖 POM 已解析的版本。应在业务应用的 dependencyManagement 中管理实际依赖坐标。下面示例锁定 2.0.11；应用自有版本属性可以改为其他精确 SDK 版本，但必须先完成兼容测试：

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

在业务项目内检查最终依赖图，而不只是检查本仓库：

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

确认 iotdb-session 实际解析为指定版本，并检查其 isession、RPC、Thrift 与 TSFile 依赖，以及被省略或冲突覆盖的条目。依赖组合应以所选 SDK 的官方 POM 为起点；业务 BOM 或路径更近的依赖仍可能覆盖这些版本。如果冲突要求显式管理其他制品，应采用所选 SDK 对该制品要求的版本。不要把所有 IoTDB family 或 TSFile 制品都硬套成 SDK 的版本号：TSFile 等依赖有独立的发布版本。独立的 tsgate-bom 管理默认 iotdb-session 版本，并刻意让所选 SDK 带入配套依赖，因此覆盖 SDK 后仍需核对依赖图。业务侧覆盖依据见 Maven 依赖管理规则。

本次核对的依赖组合说明这些版本不能混为一个数字：

官方 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

2.0.11 的实际依赖图还包含 org.apache.thrift:libthrift:0.23.0；归档见 .local-test/2026-09-29-iotdb-sdk-upgrade/dependency-tree.log。这些是本次已核对的组合，不代表未来 SDK 的传递依赖也应固定使用这些版本。

本次额外验证过的消费者 SDK 覆盖版本只有 2.0.10，使用同一份按 2.0.11 编译的 TsGate JAR；连接服务端 2.0.10 时，两种设置分别通过单 Tablet 12 行、Spring 属性绑定与关闭。这是限定范围的消费者验证，不是该 SDK 的全量回归认证。不要直接把服务端版本填入 SDK 属性：例如更早的 SDK 2.0.5 不具备本适配器现已调用的 enableIoTDBRpcCompression builder 方法，不能直接替换，须另行调整实现并验证。

保持 Java 17 和已声明的 Spring Boot 基线，确认表模型 API 与运行期链接，再回归写查、原生连接池、分页、错误语义和生命周期。相关 RPC 压缩开关验证必须包含一个实际 Tablet 至少 10 行的用例，小批量不足以覆盖兼容边界。2.0.2 等不兼容旧服务端应按配置说明显式设置 tsdb.iotdb.table.rpc-compression-enabled: false；关闭 Tablet RPC 编码并不等于旧服务端实现了适配层使用的全部 API 或 SQL。

选择 InfluxDB 3 严格游标 SQL 策略

默认 tsdb.influxdb.strict-cursor-sql: or 保留既有 SQL。在 Core 3.0.0 / 3.0.3 上使用严格游标续页时，显式配置 union-all；配置示例见配置说明，准确组合见服务端/策略矩阵。省略或空白配置仍使用 or，非空白的非法值会导致 Spring 绑定失败。adapter 在构造时确定策略，不探测服务端版本，不自动降级或在 HTTP 500 后重试，该开关也不改写原生 SQL。

切换策略或升级服务端前，应回归第一页及后续页，覆盖相同时间戳、多 tag、FIELD 优先、混合方向、显式选列、业务过滤及游标/时间范围边界。核对逐页内容和终止条件，不能只检查 HTTP 成功。保留行数、响应字节和无效游标测试。union-all 模式拒绝严格游标与聚合组合，普通聚合行为不变。

UNION 各分支携带相同业务条件，使用互斥的字典序比较，再统一做外层排序和分页。能够由游标时间与显式 timeRange / startTime / endTime 边界证明为空的分支会被省略，但不分析任意过滤表达式或改写原生 SQL。补齐后的每个游标键最多产生一个分支，可能增加扫描和排序；在已经支持 or 的新版服务端上启用前，应评估真实数据量与时间范围。切换 SQL 策略不要求升级客户端依赖。某个服务端/策略组合通过，不代表其他版本、Enterprise 等其他产品或所有原生 SQL 都得到认证。

2.1.0 修复与新增能力

2.1.0 纳入 2.0.0 之后的以下修复，并新增 OpenGemini 支持。Java 17、已说明的 Spring Boot/客户端基线及 Template → adapter SPI → 后端主干设计保持不变。包名迁移、准确后端范围和验证状态见 2.1.0 发布说明。

• 严格游标原始输入保留到校验阶段，null 值、空白键、多余键及规范化重名键会报 ARGUMENT_ERROR，不再被丢弃；null/空 map 仍表示第一页。
• InfluxDB 3、IoTDB starter 在资源初始化失败时正确遵守 fail-fast=false，原生客户端可选注入不可用，与 InfluxDB 1.x 一致；手动重试初始化不会自动重建此前不可用的 Spring 原生客户端 Bean。
• 四个 adapter 都在构造时捕获完整配置快照。Properties 修改应放在构造之前；修改或修正配置需要新实例。临时初始化失败重试与 IoTDB 恢复继续使用原快照。
• 直接结构化查询统一在 I/O 前拒绝 null query、非正 limit、负 offset 和逆序时间范围；count 仍忽略分页/游标，公共默认 count 实现也将 null query 归类为 ARGUMENT_ERROR。
• 新增 OpenGemini adapter/starter 与 BOM 集成，目标为 1.4.1/1.5.2 默认引擎的单节点及三节点三副本集群。整批 measurement/整数校验、准确的缺失 measurement 处理、兼容原生客户端健康/版本、生命周期和有界查询见 OpenGemini 接入指南。
• 全部 Java 包、Spring 自动装配元数据、反射类名、可移植运行器全限定类名及生成文档检查迁移为 com.alandevise.tsgate.*。

可选注入、迁移细节与准确测试组合见配置、分页及验证证据。

2.0.0 首次公开发布

2.0.0 是 TsGate 的首次公开发布版本，提供以下能力：

• 独立 tsgate-bom、IoTDB / InfluxDB 3 / InfluxDB 1.x 适配器与 Spring Boot starter，以及上文所述的 TG* API。
• 不使用预览特性的 Java 17 编译/运行基线，以及 Spring Boot 2.7.18 构建基线。准确运行时与数据库组合见兼容性与验证。
• 默认 IoTDB Java SDK 2.0.11，以及默认 true 的 tsdb.iotdb.table.rpc-compression-enabled。2.0.2 等不兼容旧服务端须显式设为 false。该参数控制 Tablet RPC 载荷编码，不是 Thrift 传输或磁盘压缩，适用于初始池和替换池。
• InfluxDB 3 tsdb.influxdb.strict-cursor-sql: or|union-all，默认 or。显式 union-all 支持已验证 Core 3.0.0 / 3.0.3 组合的结构化严格游标续页，保留键补齐、排序、单行探测与查询限额，拒绝严格游标与聚合组合，不改写原生 SQL 或自动重试查询。
• 对非法数字文本、整数越界和非法 boolean 文本明确报转换错误；原生查询行数保护和 InfluxDB 流式响应字节保护。大结果应分页查询或配置合适限额。
• InfluxDB 初始化幂等、失败可重试、关闭为终态并等待适配层在途操作；关闭后须创建新实例。
• IoTDB / InfluxDB 3 地区时区日窗口遵循实际本地日历。地区时区要求时间范围，跨偏移变化的小时等窗口明确拒绝。InfluxDB 1.x 不支持地区自然日窗口，且所有窗口查询都要求显式起止时间。
• 三个后端的默认数据库均为 tsdb，可通过所选后端的 database 属性修改。IoTDB / InfluxDB 1.x 要求目标数据库已存在，显式空值会校验失败；配置不会创建或迁移数据库。
• 显式 enable: true 启用后端。省略开关或只配置连接信息均保持关闭；其他后端无需填写 false。多个启用后端或非法开关会报配置错误。
• 英文 Javadoc 与源码注释、中英文 Wiki 使用说明、简明的中英文 README 概览、可移植测试源码和 CI 配置。源码/Javadoc 制品包含许可证材料，发行命令见测试与发布。
• 项目自有代码采用 Apache License 2.0，版权归属保留在 NOTICE；第三方组件保留各自的许可证。

许可证

项目自有代码采用 Apache License 2.0，版权归属见 NOTICE。使用、修改和分发须遵守许可证条款；第三方依赖仍遵循各自许可证。标准文本来自 Apache Software Foundation。

文档维护同时覆盖两份仓库概览 README 和中英文 Wiki。适配层代码变化时，API 行为、配置、限制、错误语义、兼容性、升级、示例及变更记录必须保持同步。测试和发行命令见测试与发布。

---

← 兼容性、验证与成熟度

2.1.0 中的 OpenGemini

TsGate 2.1.0 包含独立的 OpenGemini adapter 与 starter。配置、默认引擎边界及准确版本测试见 OpenGemini 接入指南，迁移要求见 2.1.0 发布说明。