ZH Configuration

Home · GitHub

English | 简体中文

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

2.1.2 的 HTTP 批次字节预算

配置项	默认值与范围
tsdb.influxdb.max-batch-bytes	67108864（64 MiB），一个 InfluxDB 3 应用批次预生成 UTF-8 payload 的合计字节
tsdb.influxdb1.max-batch-bytes	67108864（64 MiB），InfluxDB 1.x 的相同范围
tsdb.opengemini.max-batch-bytes	67108864（64 MiB），OpenGemini 的相同范围

配置必须为正数，并进入适配器构造时的配置快照。超过应用批次预算时返回 ARGUMENT_ERROR、NOT_COMMITTED，请求数为零。应与物理请求边界、记录数上限、解压后的查询响应字节预算分别理解；IoTDB 没有新增此字节预算配置。详见写入与错误。

统一 HTTP 适配路径不自动跟随重定向。URL 应指向最终服务或由部署方管理的入口；没有新增 YAML 开关恢复自动重定向，应在适配器外配置路由，不依赖自动请求重放。

本页涉及的输入校验、配置快照和初始化失败策略修复纳入 2.1.0；详见 2.1.0 变更记录。

在 YAML 中配置业务数据库

可以。业务侧在 application.yml 或 application.yaml 中配置当前后端的数据库名即可，无需修改适配层代码。

后端	YAML 配置项	未配置时的值
IoTDB 表模型	tsdb.iotdb.database	tsdb
InfluxDB 3 Core	tsdb.influxdb.database	tsdb
InfluxDB OSS 1.x	tsdb.influxdb1.database	tsdb
openGemini 默认引擎	tsdb.opengemini.database	tsdb

下面仅演示 IoTDB 的数据库选择片段，连接参数请结合后面的完整示例填写。未配置的后端即使引入了对应 starter 也不会启用，仅需为所选后端填写 enable: true。

tsdb:
  iotdb:
    enable: true
    database: business_metrics

数据库选择优先级为：非空的单次调用参数，例如 write("another_database", record) 或链式 .database("another_database")，其次是后端配置的默认库，最后是配置项省略时的 tsdb。单次调用参数为 null 或空白时回退到配置的默认库；YAML 配置项显式为空时，启用的后端会在启动校验阶段报错。禁用后端的配置不会被校验。这几种情况应区分使用。

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

starter 只选择显式配置 enable: true 的后端。未引入的后端不参与启用判断或冲突检查；同一 Spring 上下文最多启用一个后端。默认库设置只负责选择数据库，不负责建库或迁移数据：IoTDB / InfluxDB 1.x / openGemini 的目标数据库需要提前创建。原生 executeQuery(...) 没有单次调用的数据库参数，具体规则见本页的“默认数据库规则”。

配置方式

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

后端启用规则

开关	行为
省略 enable	不启用，即使存在连接参数
enable: false	不启用，不绑定或校验其连接参数
enable: true	启用，并校验必填连接参数
显式空值或非法 enable	配置错误

同一 Spring 上下文最多启用一个后端。多个开关同时为 true 时，在客户端初始化前返回 CONFIGURATION_ERROR。没有启用的后端时，不创建 adapter、TGTemplate 或原生客户端 Bean。未引入的 adapter 不参与启用判断。这些开关控制 starter 自动装配；业务直接构造 adapter 时仍自行调用 init()。

YAML、properties、环境变量、命令行和自定义属性源仍遵循 Spring 配置优先级，例如 TSDB_INFLUXDB1_ENABLE=true 也可以提供显式开关。自定义属性源无需枚举全部连接参数。Spring profile 可按需选择应用配置文件，但不能替代后端的 enable 开关。

下面保留了未启用的 InfluxDB 3 配置，同时显式启用 InfluxDB 1.x：

tsdb:
  influxdb1:
    enable: true
    url: http://127.0.0.1:8086
    database: business_metrics
  influxdb:
    enable: false
    url: http://127.0.0.1:8181

这里的 false 可以省略，省略后 InfluxDB 3 仍保持关闭。只校验已启用后端的必填连接参数。

完整示例

IoTDB、InfluxDB 3、InfluxDB 1.x 和 openGemini 默认引擎的 database 在未配置时均默认使用 tsdb；显式配置为空仍会校验失败。已有数据库名称可通过对应的 tsdb.iotdb.database、tsdb.influxdb.database 或 tsdb.influxdb1.database / tsdb.opengemini.database 保留，显式配置的其他库名不会被覆盖。

IoTDB 表模型示例：

tsdb:
  query-log-enabled: true
  iotdb:
    enable: true
    fail-fast: true
    discovery-mode: AUTO
    username: root
    password: root
    database: tsdb
    max-batch-records: 10000
    max-query-rows: 10000
    pool:
      enabled: true
      node-urls:
        - 127.0.0.1:16669
      max-size: 8
      wait-to-get-session-timeout-in-ms: 3000
      connection-timeout-in-ms: 3000
      query-timeout-in-ms: 60000
      max-retry-count: 3
      retry-interval-in-ms: 1000
      fetch-size: 10000
    table:
      tablet-max-row-size: 1024

InfluxDB 3 Core 示例：

tsdb:
  query-log-enabled: true
  influxdb:
    enable: true
    fail-fast: true
    url: http://127.0.0.1:8181
    token: ""
    database: tsdb
    strict-cursor-sql: or
    max-batch-records: 10000
    max-batch-bytes: 67108864
    max-query-rows: 10000
    max-query-response-bytes: 16777216
    http-client:
      max-idle-connections: 8
      keep-alive-duration-ms: 300000
      connect-timeout-ms: 3000
      read-timeout-ms: 60000
      write-timeout-ms: 60000
      call-timeout-ms: 0
      retry-on-connection-failure: true

InfluxDB OSS 1.x 示例（HTTP 8086、用户名密码，与 3.x 的 token 配置独立）：

tsdb:
  query-log-enabled: true
  influxdb1:
    enable: true
    fail-fast: true
    url: http://127.0.0.1:8086
    username: ""
    password: ""
    database: tsdb
    retention-policy: ""
    max-batch-records: 10000
    max-batch-bytes: 67108864
    max-query-rows: 10000
    max-query-response-bytes: 16777216
    http-client:
      max-idle-connections: 8
      keep-alive-duration-ms: 300000
      connect-timeout-ms: 3000
      read-timeout-ms: 60000
      write-timeout-ms: 60000
      call-timeout-ms: 0
      retry-on-connection-failure: true

openGemini 默认引擎适配；url 为一个 ts-sql 入口或外部负载均衡入口：

tsdb:
  query-log-enabled: true
  opengemini:
    enable: true
    fail-fast: true
    url: http://127.0.0.1:8086
    username: ""
    password: ""
    database: tsdb
    retention-policy: ""
    max-batch-records: 10000
    max-batch-bytes: 67108864
    max-query-rows: 10000
    max-query-response-bytes: 16777216
    http-client:
      max-idle-connections: 8
      keep-alive-duration-ms: 300000
      connect-timeout-ms: 3000
      read-timeout-ms: 60000
      write-timeout-ms: 60000
      call-timeout-ms: 0
      retry-on-connection-failure: false

必须使用独立的 tsdb.opengemini.enable 开关；复用 InfluxDB1 实现不会启用后者，同时启用两者仍报配置错误。OpenGemini 的 HTTP 连接恢复默认 false；显式设置 true 可能允许 OkHttp 对符合条件的请求进行恢复，不能保证写入幂等或确定提交边界。adapter 不发现节点，也不跨入口重放失败写入。

1.x 空凭据用于无鉴权环境；启用服务端鉴权时填写用户名/密码，适配层使用 HTTP Basic Auth。retention-policy 为空时使用数据库默认策略；此配置只选择已有策略，不负责创建或修改策略。 IoTDB 和 InfluxDB 1.x 的 database 需预先创建；1.x 可先执行 CREATE DATABASE tsdb。 适配层不发送建库请求；InfluxDB 3 Core 可在首次 line protocol 写入时由服务端原生创建 database，是否允许创建取决于服务端权限。

关键配置说明：

配置项	说明
tsdb.iotdb.enable / tsdb.influxdb.enable / tsdb.influxdb1.enable / tsdb.opengemini.enable	默认 false；只有显式 true 才启用。省略/false 不校验连接参数；空值/非法值属于配置错误，同一上下文最多启用一个后端
tsdb.query-log-enabled	是否以 DEBUG 级别输出适配器实际执行的查询 SQL，默认 true；设置为 false 时不输出
tsdb.iotdb.fail-fast	客户端资源初始化失败时是否终止启动，默认 true；初始化阶段不访问默认数据库
tsdb.iotdb.discovery-mode	节点自动发现和重定向策略，支持 AUTO、ENABLED、DISABLED，默认 AUTO
tsdb.iotdb.username	IoTDB 登录用户名，必填且无默认值
tsdb.iotdb.password	IoTDB 登录密码，必填且无默认值
tsdb.iotdb.database	IoTDB 连接池默认 database，未配置时为 tsdb；必须预先创建且运行期间不可删除，普通读写直接使用，显式访问其他库时才执行 USE
tsdb.iotdb.pool.enabled	必须为 true；单 ITableSession 模式已禁用，为 false 时启动失败
tsdb.iotdb.pool.node-urls	IoTDB 节点地址，IoTDB 配置下必填
tsdb.iotdb.table.tablet-max-row-size	IoTDB 单个 Tablet 最大行数，默认 1024
tsdb.iotdb.table.rpc-compression-enabled	是否允许 Tablet RPC 紧凑编码/压缩，默认 true；不兼容的旧服务端显式设为 false，与 Thrift 传输及磁盘压缩无关
tsdb.iotdb.max-batch-records	单次业务批量写入最大记录数，默认 10000；超限时写入前直接失败
tsdb.influxdb.fail-fast	客户端资源初始化失败时是否终止启动，默认 true；初始化阶段不访问默认数据库
tsdb.influxdb.url	InfluxDB 3 Core 地址
tsdb.influxdb.token	InfluxDB token；无鉴权环境可为空
tsdb.influxdb.database	InfluxDB 写入和查询 API 使用的 database，默认 tsdb
tsdb.influxdb.strict-cursor-sql	结构化严格复合游标续页的 SQL 策略：or（省略或空白时的默认值）或 union-all；不改写原生 SQL，也不影响 InfluxDB 1.x
tsdb.influxdb.max-batch-records	单次业务批量写入最大记录数，默认 10000；超限时发出 HTTP 请求前直接失败
tsdb.iotdb.max-query-rows / tsdb.influxdb.max-query-rows / tsdb.influxdb1.max-query-rows / tsdb.opengemini.max-query-rows	普通链式与原生查询结果上限，默认 10000；范围 1..2147483646；时间游标 / 复合游标分页最多允许额外读取一条探测记录
tsdb.influxdb.max-query-response-bytes	解压后的查询响应体字节上限，默认 16777216（16 MiB），必须为正数
tsdb.influxdb1.username / password	1.x HTTP Basic Auth 凭据，空值用于无鉴权环境
tsdb.influxdb1.fail-fast	1.x 客户端资源初始化失败时是否终止启动，默认 true；不探测数据库可用性
tsdb.influxdb1.database	1.x 写入和查询使用的 database，未配置时默认为 tsdb；必须预先创建
tsdb.influxdb1.retention-policy	已有 retention policy 名称，空值使用库默认策略
tsdb.influxdb1.max-batch-records / max-query-rows / max-query-response-bytes	默认 10000 / 10000 / 16 MiB，含义同 3.x；count 扫描也受响应字节上限约束
tsdb.influxdb1.http-client.*	1.x 独立 HTTP 连接池与超时，默认值同 3.x
tsdb.opengemini.url	一个 ts-sql 入口或外部负载均衡入口，默认 http://localhost:8086
tsdb.opengemini.username / password	HTTP Basic Auth 凭据，无鉴权环境使用空值
tsdb.opengemini.fail-fast / database / retention-policy	默认 true / tsdb / 空值；数据库与所选保留策略必须预先存在
tsdb.opengemini.max-batch-records / max-query-rows / max-query-response-bytes	默认 10000 / 10000 / 16 MiB；count 扫描仍受响应字节上限约束
tsdb.opengemini.http-client.*	独立 HTTP 配置；连接池/超时默认值同 InfluxDB1，但 retry-on-connection-failure 默认 false
tsdb.influxdb.http-client.*	InfluxDB HTTP 客户端连接池和超时参数

tsdb.query-log-enabled=true 仅表示允许记录查询 SQL；还需要把 com.alandevise.tsgate.adapter.impl 的日志级别设置为 DEBUG 才能看到该日志。

部署模式说明：

• discovery-mode=AUTO 时，一个 endpoint 会关闭自动发现和重定向，适用于单机或 VIP；多个 endpoint 会开启两者，适用于直接连接多个 DataNode 的集群。
• discovery-mode=ENABLED 强制开启自动发现和重定向，适用于只配置一个种子节点但仍需发现其他 DataNode 的集群。
• discovery-mode=DISABLED 强制关闭自动发现和重定向，始终使用配置的固定入口。
• openGemini 通过 tsdb.opengemini.url 连接单个 ts-sql 入口或集群外部入口，不提供客户端节点发现或自动切换入口。
• InfluxDB 客户端没有 IoTDB 风格的节点自动发现。3.x 的 REST 和 Arrow Flight 客户端从 tsdb.influxdb.url 建立连接；1.x 的 HTTP 客户端使用 tsdb.influxdb1.url。

不再支持 required-adapters、default-type、default-database、table.enabled、自动创建 retention 的配置、IoTDB 树模型配置和点位模型配置。

InfluxDB 3 严格游标 SQL 策略

tsdb.influxdb.strict-cursor-sql 省略或空白时默认 or，保持现有的字典序 OR 条件。对于已验证但无法执行该查询形态的旧服务端 Core 3.0.0 / 3.0.3，在已有连接配置中显式选择 union-all：

tsdb:
  influxdb:
    enable: true
    strict-cursor-sql: union-all

此片段补充上面的地址、token 和数据库配置。该开关仅作用于具有非空后续游标的结构化严格复合游标查询，例如 strictCursorPage() 的第二页及后续页。普通严格游标的第一页、普通 list、仅时间游标、offset 分页、计数、普通聚合、原生 SQL 和其他后端仍使用原来的查询生成方式。union-all 模式不支持严格游标与聚合组合，即使第一页也会报 UNSUPPORTED_OPERATION。

策略在构造 adapter 时确定，之后修改配置对象不会改变现有 adapter。YAML 中非空白的未知值（如 auto 或 unsupported-mode）会导致 Spring 属性绑定失败；省略或空白值按 Spring 绑定行为保留字段默认值 or；以编程方式传入 null 策略会在构造 adapter 时报 CONFIGURATION_ERROR。

union-all 为最终游标中的每个键最多生成一个互斥分支，再对合并结果执行完整排序和分页限制。它只发送一次 SQL 请求，但可能增加服务端扫描和排序开销。响应行数与解压后字节上限继续生效。混合排序示例见分页，准确的服务端/策略实测组合见兼容性与验证。TsGate 不探测服务端版本，不自动切换策略，也不在 HTTP 500 后换 SQL 重试。

IoTDB Tablet RPC 编码

tsdb.iotdb.table.rpc-compression-enabled 默认 true，业务侧无需填写。它允许官方 SDK 对 Tablet RPC 载荷采用紧凑编码/压缩，具体 Tablet 是否采用该格式仍由 SDK 判断。它与 Thrift 传输压缩、磁盘 TsFile 压缩是不同设置。

对于 IoTDB 2.0.2 等无法解码新版 Tablet 表示的旧表模型服务端，在已有 IoTDB 连接配置中显式关闭：

tsdb:
  iotdb:
    enable: true
    table:
      rpc-compression-enabled: false

这个片段需要与前面的地址、账号和密码配置合并。参数在物理 SessionPool 构建时生效，故障恢复时创建的替换池也使用同一设置；适配器不会自动猜测服务端版本，也不会在写入失败后换一种编码自动重试。

兼容验证必须让一个实际 Tablet 至少包含 10 行，并写入后回查。业务 batch 总量达到 10 条，但按 measurement 分组或按 tablet-max-row-size 拆分后各 Tablet 都不足 10 行，仍不能覆盖 SDK 的编码阈值；小批量通过可能掩盖兼容问题。设为 false 只改变传输表示，不改变 TsGate 的前置校验、行数限制或批次提交状态契约。已完成的证据见兼容性与验证；这个开关和 SDK 升级都不构成旧版全覆盖或未来版本必然兼容的承诺。

自动装配和启动语义

启用的 starter 会自动注册 com.alandevise.tsgate.core.TGTemplate，默认 Bean 名为 tgTemplate；业务已提供自己的 TGTemplate 时不重复注册。优先按类型注入，需要按名称注入时使用 @Qualifier("tgTemplate") 或 @Resource(name = "tgTemplate")；自定义 Bean 名应与业务注入点一致。TGQueryBuilder<T> 由 tgTemplate.query(...) 为每次查询创建，不是 starter 共享的 Bean。公共类型及自定义 Bean 示例见TG API 与模板配置。

• 各 starter 默认关闭，必须显式配置 enable: true。省略或 false 均保持关闭；空值或非法值属于配置错误，不再依据连接配置自动启用。
• 多种依赖可以同时存在，但最多启用一种；冲突检查基于当前 Spring 上下文配置，不使用静态全局状态，并在客户端初始化前执行。
• 未配置或显式关闭的 adapter 不校验连接配置、不创建客户端；显式启用但只填写部分配置的后端会执行完整配置校验，不会因缺少必填项而忽略。没有启用的后端时不自动装配 adapter 或 TGTemplate。
• 未启用的原生客户端 Bean 不存在。业务代码同时引用多个客户端时，应使用 ObjectProvider 或可选注入； 也可用 @Conditional(TSDBAdapterEnabledCondition.IoTDB.class) / InfluxDB.class / InfluxDB1.class / OpenGemini.class 控制对应业务组件。 没有启用的后端时，依赖 TGTemplate 的业务组件也应禁用（可用 @Conditional(TSDBAdapterEnabledCondition.class)）。
• 必填配置缺失、批量上限非法或 IoTDB pool 被关闭属于配置错误，无论 fail-fast 取值如何都会终止启动。
• adapter 初始化只创建客户端资源并把默认 database 绑定到 IoTDB 连接池，不建立物理 Session；默认库在首次借出 Session 时由 IoTDB 校验。 部署流程必须预先创建默认库并保证运行期间不被删除，否则首次借出 Session 会失败。
• fail-fast=true 在客户端资源初始化失败时关闭 adapter 并抛出异常；false 则允许四个源码 starter 保留 adapter/template，此时原生客户端在按类型可选注入时不可用。业务若强制注入原生客户端，仍可能无法启动，应使用 ObjectProvider 或可选注入。此策略不探测数据库/表是否存在，也不改变运行时写查异常语义。
• starter 不提供 HealthIndicator，不会探测 TSDB 宕机或恢复，也不会因为运行期 TSDB 不可用而主动停止应用。运行状态应使用 TSDB 自身指标或业务系统统一的监控体系。

配置生命周期

四个源码 adapter 都在构造时防御性复制连接与操作配置，包括嵌套 HTTP/table/pool 配置和 IoTDB 节点 URL 列表。在 init() 前后修改调用方的 Properties 对象，都不会改变该 adapter、其原生客户端或恢复时新建的 IoTDB 物理池。配置绑定必须在构造之前完成。

需要更改地址、凭据、数据库、超时、发现策略或限额时，应使用新配置创建新的 adapter/上下文，并与业务操作协调替换。临时资源初始化失败可以使用原快照重试；修正非法配置则需要新实例。此规则保证配置一致性，不增加动态重配置功能；每次操作显式指定 database 的能力保持可用。

默认数据库规则

• 四个后端的 database 未配置时均使用 tsdb，显式空值无效；显式指定的其他库名仍按原值使用。更改默认值不会自动创建、重命名或迁移已有数据库。
• write(record)、batchWrite(records)、链式查询未调用 database(...) 时，adapter 使用 YAML 中配置的默认 database。
• IoTDB 连接池绑定配置的默认 database；未指定 database 或显式指定默认库时直接执行，只有显式访问其他库时才执行 USE。
• 跨库操作关闭 Session 时，IoTDB 客户端会先恢复连接池默认 database，再把物理 Session 放回池中。
• InfluxDB 3 写入会把目标 database 放入 /api/v3/write_lp 请求的 db 参数；InfluxDB 1.x 与 openGemini 使用 /write 的 db 参数。
• 原生查询 executeQuery(...) 不提供 database 参数，也不改写 SQL。IoTDB 不主动执行 USE，但借出的 Session 已具有默认库上下文；InfluxDB 3 / 1.x / openGemini 的查询 API 需要请求库，分别使用配置中的 tsdb.influxdb.database / tsdb.influxdb1.database / tsdb.opengemini.database，查询文本不被改写。
• IoTDB 原生 SQL 可直接访问默认库中的表；跨库 SQL 建议显式使用 database.table。

官方与兼容 client 注入

starter 会把当前 adapter 持有的原生 client 暴露为 Spring Bean：

@Autowired
private ITableSessionPool tableSessionPool;

@Autowired
private InfluxDBClient influxDBClient;

IoTDB 仅支持 pool 模式，业务侧可以直接注入 ITableSessionPool。应用中只存在当前启用后端的 client Bean；可同时引入四个源码 starter，显式将一个后端设为 enable: true；其他保留的配置块在未显式启用时仍保持关闭。

这些原生 client 来自 adapter 内部维护的连接资源，生命周期由 Spring 容器和 adapter 统一关闭。业务方法不要主动关闭注入的 InfluxDB client 或 IoTDB 连接池；从 ITableSessionPool 借出的 session 使用完应关闭以归还连接池。 原生 client 是借用引用：直接调用不受适配层的查询数量/字节上限和生命周期读锁保护，业务侧需协调应用关闭期间的原生操作。

OpenGemini 适配的 openGeminiClient 是兼容 org.influxdb.InfluxDB 的稳定代理。ping() / version() 使用快照中的入口、凭据和 HTTP 配置，并读取真实 X-Geminidb-Version 响应头。HTTP 成功且版本头非空才构成成功 ping；失败或缺少版本头时不会伪造版本。其他原生操作保留服务端响应，包括错误 DTO。database 和所选 retention policy 须已存在；写入确认不保证新 measurement/tag series 的索引立即对查询可见。详见 OpenGemini 接入指南。

四个后端 adapter 的生命周期统一为 NEW → READY → CLOSED：重复 init() 不创建或覆盖资源，初始化失败释放已创建资源并允许重试； close() 幂等、清除引用并永久关闭该实例，随后 init / 写入 / 查询 / 获取原生 client 会报 ADAPTER_STATE_ERROR。 关闭会等待已经进入适配层的读写操作和整个批次结束，再释放客户端。InfluxDB / openGemini 若需要限制停机等待，应配置 http-client.call-timeout-ms； 其默认值 0 表示无总调用时限，持续传输的慢响应可能使关闭等待较长。

IoTDB 重复初始化保留相同的对外 ITableSessionPool 代理，断线恢复仅替换内部物理池。手动 close() -> init() 不再支持，需创建新的 adapter/上下文。生命周期锁保护完整适配层操作与终态关闭，业务自行借用的原生 session 仍需协调使用与关闭。IoTDB 使用自身连接、借用和查询超时设置；InfluxDB 的 http-client 设置不适用于 IoTDB。

InfluxDB 1.x 官方客户端可直接注入；openGemini 使用同一兼容类型，Bean 名为 openGeminiClient，不是 openGemini 专用 SDK：

@Autowired
private org.influxdb.InfluxDB influxDB1Client;

fail-fast=false 容忍资源初始化失败时，四个后端的原生客户端都可能不可用，应使用 ObjectProvider 或可选注入。初始化成功前，adapter/template 操作报 ADAPTER_STATE_ERROR。临时资源问题解决后可手动重试 adapter.init()，再通过 getNativeClient()（InfluxDB 1.x / 3 / openGemini）或 getSessionPool()（IoTDB）获取借用客户端；Spring 不会自动重建此前不可用的原生客户端 Bean。必填配置缺失仍会导致启动失败，不受 fail-fast 控制。

库表和保留策略

starter 不主动发送创建 database、table、measurement 的请求，也不创建或修改 retention/TTL。库表不存在时，由后端按其原生写入规则创建或返回错误；查询不会代为建库建表。

• IoTDB：业务侧或运维流程提前创建 database 和 table。表没有 TTL/retention 时沿用数据库级策略。
• openGemini 默认引擎：database 和所选 retention policy 需提前创建；适配器复用 InfluxDB1 兼容实现，暴露 org.influxdb.InfluxDB，不是 openGemini 专用 SDK。
• InfluxDB 1.x：需提前创建 database；measurement 在首次 line protocol 写入时由服务端创建。
• InfluxDB 3 Core：首次 line protocol 写入可由服务端创建 database 和 table；需要预先管理权限、库名或保留策略时，仍应在部署流程中显式创建。

需要建库建表时，建议业务系统在初始化流程中直接使用官方 client 或运维脚本处理。

---

← 开始使用 · 写入、模型与错误处理 →

2.1.0 中的 OpenGemini

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