ZH Upgrades and Migration - AlanDevise/TsGate GitHub Wiki

Home · GitHub

English | 简体中文

2.1.3 已通过 GitHub 源码／标签和 Maven Central 发布，同 SHA CI 与公开制品核验通过。 当前坐标为 2.1.3；详见 2.1.3 发布说明.

升级前检查动态拼接的过滤条件：比较运算必须恰好一个操作数，BETWEEN 两个，IN 至少一个。直接模型中的 null 操作数、Float／Double 非有限值现在会在 I/O 前返回 ARGUMENT_ERROR。链式 builder 的可选输入清理保持；文字字符串 "null" 仍是普通字符串。count 在私有副本中忽略分页／游标，SPI 默认 count(null) 返回 ARGUMENT_ERROR。

IoTDB 在整批列角色／类型检查前，按 Locale.ROOT 小写物理表身份归并表名。冲突的大小写变体在借用 session 前以 METADATA_ERROR／NOT_COMMITTED 拒绝；兼容变体保留同表行序及既有 Tablet 拆分。原生查询应使用唯一输出 alias：SDK 输出列名或 InfluxDB 3 JSON 对象键精确重复时，整次 query／count／executeQuery 返回 QUERY_ERROR。大小写不同结果键及既有宽松 DTO 映射保持。

直接 adapter 的 batchWriteDetailed／batchWrite 在复制或遍历记录前拒绝报告大小明显超限的集合，复制后再次复核。生命周期检查仍优先，ready 状态的 null／空批次仍成功。超限返回 ARGUMENT_ERROR／NOT_COMMITTED，数据库 I/O 为零。业务应主动拆批，或评估后调整既有正数 max-batch-records；本次不新增资源预算配置，也不承诺任意自定义集合的内存硬上限。

从 Central 2.1.0 升级的用户也会获得此前仅通过 GitHub 发布的 2.1.1／2.1.2 修复：数值游标边界、IoTDB 列身份、HTTP 重定向写入确认、InfluxDB 3 缺失 JSON 报错、聚合输出名检查、可配置的 64 MiB HTTP 整批预算，以及 POJO 读计划缓存。这些是继承的修改，不是 2.1.3 首次新增。请同时阅读 2.1.1 说明 与 2.1.2 说明，包括最终 HTTP 入口配置及显式拆批要求。

2.1.3 发布说明

2.1.2 保持公开 API、Java 17 基线、客户端版本及 TGTemplate → TSDBAdapter → 后端的主干设计。修复 HTTP 自动重定向、InfluxDB 3 缺失 JSON 响应及聚合结果名冲突，并增加 HTTP 应用批次合计字节预算、按类生命周期复用的 POJO 读计划。

• 配置最终 HTTP 入口。此前依赖 3xx 的部署，应在升级前把路由指向最终服务或 ingress。
• HTTP 应用批次默认允许 64 MiB 合计预生成 UTF-8 payload。超过时拆分应用批次，或评估内存后显式调大正数 max-batch-bytes；完成整个批次预检前不会提交请求。
• 聚合 alias 与分组 tag 按后端规范化后必须不同。window_start 仅在生成时间窗口输出时保留；IoTDB 大小写变体冲突，Influx 的大小写不同名称可以保留。InfluxDB 1.x／OpenGemini 还保留聚合响应的隐式 time，但 Time 仍不同；两个 SQL 适配器不因此保留 time alias。
• InfluxDB 3 缺失或空白 HTTP 响应改为 QUERY_ERROR；有效 [] 仍为空成功。POJO 映射优先级及转换语义保持。

2.1.2 仅通过 GitHub 分发，发行包与报告见 v2.1.2；该历史版本发布时 Maven Central 为 2.1.0。从已验证的 v2.1.2 源码安装版本一致的模块／BOM，再声明对应坐标。该历史版本的验证与分发见 2.1.2 发布说明；2.1.0／2.1.1 历史证据分别保留。

四个后端默认关闭。业务直接在 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，也可能影响 SQL、内存或运行时依赖；组件版本按实际兼容性决定，不机械照搬上游版本。

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 模块，继续保留原制品。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 保留大小写，有列名折叠规则的后端可以覆盖。准确的已验证组合见兼容性与验证。

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

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。

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.3</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 依赖管理规则。

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

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。

默认 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.1 保持公共 API 与主干设计，增加精确结果时间转换、不可用续页时间拒绝，以及 IoTDB 完整批次物理列预检／取值映射。小数、非有限和溢出的结果时间不能静默成为游标；有歧义的 IoTDB 大小写列不能进入数据库写入。既有有效输入、生命周期／配置快照及各后端提交错误差异保持不变。

扩展新后端前先使用可复用契约和能力断言。自动 CI 选择受影响 Docker 后端，发行标签／完整手动运行覆盖 OpenGemini 1.4.1／1.5.2 各自单节点与三节点三副本。选择器及门禁见测试与发布。

分发方式： 2.1.1 仅在 GitHub 发布。声明一致的 2.1.1 模块／BOM 前，先将 v2.1.1 源码安装到本地仓库；2.1.1 未上传 Central，该版本无法直接从 Central 解析。准确变更与最终证据见 2.1.1 发布说明。

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 接入指南。

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

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 行为、配置、限制、错误语义、兼容性、升级、示例及变更记录必须保持同步。测试和发行命令见测试与发布。

← 兼容性、验证与成熟度

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