Home

Project repository · English overview · 中文项目介绍

TsGate documentation · 使用文档

TsGate is a Java 17 time-series database adapter for Spring Boot, with TGTemplate / TGQueryBuilder, four TG* POJO annotations and independent IoTDB, InfluxDB 3, InfluxDB 1.x and openGemini starters in 2.1.0. The repository READMEs introduce the project and its architecture; this Wiki contains the complete bilingual usage guide.

TsGate 是面向 Spring Boot 的 Java 17 时序数据库适配组件，提供 TGTemplate / TGQueryBuilder、四个 TG* POJO 注解及2.1.0 中独立的 IoTDB、InfluxDB 3、InfluxDB 1.x、openGemini starter。仓库 README 保留项目介绍与架构设计，Wiki 提供完整的中英文使用说明。

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.

TsGate 2.1.0 新增 tsgate-opengemini 与 tsgate-opengemini-spring-boot-starter，构建包含四个后端、九个 JAR 模块，2.1.0 BOM 管理这两个新模块。Central 2.0.0 不包含它们。准确的默认引擎版本与拓扑验证范围见 OpenGemini 接入指南。

Java package migration · Java 包名迁移

TsGate 2.1.0 moves Java packages from com.alandevise.tsdb.* to com.alandevise.tsgate.*; Central 2.0.0 retains the old namespace. Consumers must update imports, reflection/scanning references and recompile applications and dependent libraries. Maven coordinates, tsdb.* YAML keys and type names stay the same. See migration steps and 2.1.0 release notes.

TsGate 2.1.0 将 Java 包由 com.alandevise.tsdb.* 迁移为 com.alandevise.tsgate.*，Central 2.0.0 保留旧包名。消费者须更新 import、反射/扫描引用并重新编译应用与依赖库。Maven 坐标、tsdb.* YAML 配置及类型名保持不变。详见迁移步骤与 2.1.0 发布说明。

Documentation map · 文档目录

English	简体中文
Overview	项目概览
Getting started	开始使用
Configuration and database selection	配置与数据库选择
Writes, models and errors	写入、模型与错误处理
Fluent queries and aggregation	链式查询与聚合
Pagination and native queries	分页与原生查询
Mapping and backend limits	结果映射与后端边界
Compatibility, validation and readiness	兼容性、验证与成熟度
Upgrades, APIs and licensing	升级、API 与许可证
Testing and publishing	测试与发布
OpenGemini integration	OpenGemini 接入
2.1.0 release notes	2.1.0 发布说明

Choose a database · 配置业务数据库

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. The default database is tsdb. Business applications can override it in YAML through tsdb.iotdb.database, tsdb.influxdb.database or tsdb.influxdb1.database / tsdb.opengemini.database, according to the active backend. See configuration in English for override priority, blank-value behavior and complete examples.

四个后端默认关闭。业务直接在 application.yml 中填写连接参数，并将所需后端的 enable 显式设为 true；无需配置 spring.profiles.active，也无需为其他后端填写 enable: false。省略 enable 或设置为 false 均不启用，即使保留了连接参数。默认数据库为 tsdb；业务侧可根据当前后端，在 YAML 中通过 tsdb.iotdb.database、tsdb.influxdb.database 或 tsdb.influxdb1.database / tsdb.opengemini.database 修改。配置优先级、空值规则和完整示例见中文配置说明。

Compatibility scope · 兼容范围

The verified combinations include IoTDB table model 2.0.2 with explicit tsdb.iotdb.table.rpc-compression-enabled=false, and 2.0.10 / 2.0.11 with either setting; the default SDK is 2.0.11. InfluxDB 3 Core 3.0.0 / 3.0.3 requires explicit tsdb.influxdb.strict-cursor-sql=union-all for strict cursors; 3.10.0 / 3.11.5 has been tested with both strategies and retains default or. InfluxDB OSS 1.13.1 is also verified. OpenGemini 1.4.1 / 1.5.2 default engine passed single-node and three-node/three-replica cluster validation. These results do not certify untested releases, and the old Core OR failure remains documented. The English validation page separates exact runtime/configuration checks from historical results.

已验证组合包括 IoTDB 表模型 2.0.2（须显式 tsdb.iotdb.table.rpc-compression-enabled=false）及 2.0.10 / 2.0.11（两种设置均通过），默认 SDK 为 2.0.11。InfluxDB 3 Core 3.0.0 / 3.0.3 的严格游标须显式 tsdb.influxdb.strict-cursor-sql=union-all；3.10.0 / 3.11.5 两种策略均经过验证，默认仍为 or。另已验证 InfluxDB OSS 1.13.1，以及 openGemini 1.4.1 / 1.5.2 默认引擎的单节点和三节点三副本集群。上述结果不认证未测版本，旧 Core OR 失败证据仍保留。准确运行时/配置组合及历史结果分别见中文验证说明。

Reading conventions · 阅读约定

Each topic has English/Chinese counterpart links, a shared sidebar and previous/next links. GitHub supplies each page's top-level title; the content uses level-two sections and level-three subsections.

每个主题提供中英文对应页面跳转、公共侧边目录和上一页 / 下一页。页面一级标题由 GitHub 提供，正文使用二级主标题和三级子标题。