EN Configuration

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.

The validation, configuration-snapshot and startup-failure-policy fixes documented here are included in 2.1.0. See 2.1.0 change history.

Configure a business database in YAML

Yes. Configure the active backend's database in application.yml or application.yaml; business applications do not need to modify adapter code.

Backend	YAML property	Value when omitted
IoTDB table model	tsdb.iotdb.database	tsdb
InfluxDB 3 Core	tsdb.influxdb.database	tsdb
InfluxDB OSS 1.x	tsdb.influxdb1.database	tsdb
openGemini default engine	tsdb.opengemini.database	tsdb

This database-selection fragment uses IoTDB; add its connection settings from the complete example below. Unconfigured backends remain inactive even when their starters are present, so only the selected backend needs enable: true.

tsdb:
  iotdb:
    enable: true
    database: business_metrics

The effective database follows this order: a nonblank per-operation override such as write("another_database", record) or fluent .database("another_database"), then the configured backend default, then tsdb when the configuration property is omitted. A null or blank per-operation argument falls back to the configured default; an explicitly blank YAML configuration is invalid for an enabled backend and fails startup validation. Disabled backend settings are not validated. These are different cases.

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.

The starters select only a backend with explicit enable: true. Backend dependencies that are absent do not participate in activation or conflict detection. At most one backend may be active in a Spring context. The default is a database selection, not database creation or data migration: create the chosen IoTDB / InfluxDB 1.x / openGemini database in advance. Native executeQuery(...) has no per-operation database argument; see the default database rules on this page.

Configuration

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.

Backend activation

Flag	Behavior
Missing enable	Disabled, including when connection settings exist
enable: false	Disabled; connection settings are not bound or validated
enable: true	Enabled; all required connection settings are validated
Blank or invalid enable	Configuration error

A Spring context may enable at most one backend. Multiple true flags fail with CONFIGURATION_ERROR before client initialization. With no enabled backend, no adapter, TGTemplate or native client bean is created. Adapters absent from the classpath do not participate in selection. These flags control starter auto-configuration; directly constructed adapters still require an explicit init() call.

YAML, properties, environment variables, command-line arguments and custom property sources retain Spring's configuration precedence. For example, TSDB_INFLUXDB1_ENABLE=true can supply the explicit flag. A custom source need not enumerate all connection properties. An optional Spring profile can select an application configuration file, but never replaces the backend enable flag.

For example, these retained InfluxDB 3 settings remain inactive while InfluxDB 1.x is enabled:

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

The explicit false above is optional; omitting it also leaves InfluxDB 3 disabled. Required connection properties are checked only for the enabled backend.

Complete examples

When omitted, database defaults to tsdb for IoTDB, InfluxDB 3, InfluxDB 1.x and the openGemini default engine; an explicitly blank value still fails validation. To retain an existing database, set tsdb.iotdb.database, tsdb.influxdb.database or tsdb.influxdb1.database / tsdb.opengemini.database for the relevant backend. Explicitly configured database names are preserved.

IoTDB table model:

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-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, using HTTP port 8086 and username/password credentials independently of the 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-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 default-engine adapter; url is one ts-sql endpoint or an external load-balancer entry point:

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

The independent tsdb.opengemini.enable flag is required; reusing the InfluxDB1 implementation does not activate InfluxDB1. Enabling both is a configuration error. OpenGemini HTTP connection recovery defaults to false; setting it to true permits eligible OkHttp recovery and cannot guarantee write idempotency or a known commit boundary. The adapter does not discover nodes or replay failed writes across endpoints.

Empty 1.x credentials are suitable for servers without authentication. When server authentication is enabled, supply a username and password; the adapter uses HTTP Basic Auth. An empty retention-policy selects the database default policy. This option selects an existing policy and does not create or modify one.

Create IoTDB, InfluxDB 1.x and openGemini databases in advance; for 1.x, for example, run CREATE DATABASE tsdb. The adapter does not send database-creation requests. InfluxDB 3 Core may create a database through native server behavior on the first line-protocol write, subject to server permissions.

Key settings:

Setting	Description
tsdb.iotdb.enable / tsdb.influxdb.enable / tsdb.influxdb1.enable / tsdb.opengemini.enable	Defaults to false; only explicit true enables a backend. Missing/false skips connection validation. Blank/invalid flags are configuration errors. At most one backend is active
tsdb.query-log-enabled	Allow DEBUG logging of the query SQL actually executed by the adapter; defaults to true, and false disables it
tsdb.iotdb.fail-fast	Abort startup on client resource initialization failure; defaults to true; initialization does not access the default database
tsdb.iotdb.discovery-mode	Discovery and redirection policy: AUTO, ENABLED or DISABLED; defaults to AUTO
tsdb.iotdb.username	Required IoTDB username, with no default
tsdb.iotdb.password	Required IoTDB password, with no default
tsdb.iotdb.database	Pool default database; defaults to tsdb when omitted and must exist before use and remain available at runtime; ordinary reads/writes use it directly, and only explicit access to another database issues USE
tsdb.iotdb.pool.enabled	Must be true; single-ITableSession mode is disabled, and false fails startup
tsdb.iotdb.pool.node-urls	Required IoTDB node endpoints
tsdb.iotdb.table.tablet-max-row-size	Maximum rows in one IoTDB Tablet; defaults to 1024
tsdb.iotdb.table.rpc-compression-enabled	Allow Tablet RPC compact encoding/compression; defaults to true. Set false explicitly for an older incompatible server. Independent of Thrift transport and disk compression
tsdb.iotdb.max-batch-records	Maximum records in one application batch; defaults to 10000; exceeding it fails before any write
tsdb.influxdb.fail-fast	Abort startup on client resource initialization failure; defaults to true; initialization does not access the default database
tsdb.influxdb.url	InfluxDB 3 Core endpoint
tsdb.influxdb.token	InfluxDB token; may be empty without authentication
tsdb.influxdb.database	Database used by InfluxDB write and query APIs; defaults to tsdb
tsdb.influxdb.strict-cursor-sql	SQL strategy for structured strict composite-cursor continuation queries: or (default when omitted or blank) or union-all. It does not rewrite native SQL or affect InfluxDB 1.x
tsdb.influxdb.max-batch-records	Maximum records in one application batch; defaults to 10000; exceeding it fails before an HTTP request
tsdb.iotdb.max-query-rows / tsdb.influxdb.max-query-rows / tsdb.influxdb1.max-query-rows / tsdb.opengemini.max-query-rows	Row limit for ordinary fluent and native queries; defaults to 10000, valid range 1..2147483646; time-cursor / composite-cursor pagination may read one additional probe row
tsdb.influxdb.max-query-response-bytes	Positive limit on the decompressed query response body; defaults to 16777216 (16 MiB)
tsdb.influxdb1.username / password	1.x HTTP Basic Auth credentials; empty values for an unauthenticated server
tsdb.influxdb1.fail-fast	Abort startup on 1.x client resource initialization failure; defaults to true; does not probe database availability
tsdb.influxdb1.database	Database used by 1.x write and query APIs; defaults to tsdb when omitted and must exist before use
tsdb.influxdb1.retention-policy	Existing retention policy name; empty selects the database default
tsdb.influxdb1.max-batch-records / max-query-rows / max-query-response-bytes	Defaults to 10000 / 10000 / 16 MiB, with the same meanings as 3.x; count scans also obey the response byte limit
tsdb.influxdb1.http-client.*	Independent 1.x HTTP pool and timeouts, with the same defaults as 3.x
tsdb.opengemini.url	One ts-sql endpoint or external load balancer; defaults to http://localhost:8086
tsdb.opengemini.username / password	HTTP Basic Auth credentials; blank for an unauthenticated server
tsdb.opengemini.fail-fast / database / retention-policy	Defaults to true / tsdb / blank; database and selected retention policy must already exist
tsdb.opengemini.max-batch-records / max-query-rows / max-query-response-bytes	Defaults to 10000 / 10000 / 16 MiB; count scans retain the response-byte limit
tsdb.opengemini.http-client.*	Independent HTTP settings; timeout/pool defaults match InfluxDB1, but retry-on-connection-failure defaults to false
tsdb.influxdb.http-client.*	InfluxDB HTTP client pool and timeout settings

tsdb.query-log-enabled=true permits SQL logging, but the logger com.alandevise.tsgate.adapter.impl must also be set to DEBUG to display it.

Deployment modes:

• discovery-mode=AUTO: one endpoint disables discovery and redirection, suitable for standalone instances or a VIP; multiple endpoints enable both, suitable for direct connections to multiple cluster DataNodes.
• discovery-mode=ENABLED: force discovery and redirection, suitable for clusters configured with a single seed endpoint that must discover other DataNodes.
• discovery-mode=DISABLED: disable both features and always use the configured fixed endpoints.
• openGemini uses tsdb.opengemini.url for a standalone ts-sql endpoint or a cluster external entry point; it has no client-side node discovery or endpoint switching.
• InfluxDB clients do not provide IoTDB-style node discovery. The 3.x REST and Arrow Flight clients connect through tsdb.influxdb.url; the 1.x HTTP client uses tsdb.influxdb1.url.

required-adapters, default-type, default-database, table.enabled, automatic retention-creation settings, IoTDB tree-model settings and point-model settings are no longer supported.

InfluxDB 3 strict-cursor SQL strategy

tsdb.influxdb.strict-cursor-sql defaults to or when omitted or blank, preserving the existing lexicographic OR predicate. For the verified older servers Core 3.0.0 / 3.0.3, which reject this query shape, explicitly select union-all in its existing connection configuration:

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

This fragment supplements the endpoint, token and database settings above. The selector applies only to structured strict composite-cursor queries with a nonempty continuation cursor, such as the second and later calls to strictCursorPage(). An ordinary strict-cursor first page, ordinary lists, time-only cursors, offset pagination, counts, ordinary aggregation, native SQL and other backends retain their existing query generation. Combining strict cursors with aggregation is unsupported in union-all mode and fails with UNSUPPORTED_OPERATION, even on the first page.

The strategy is captured when the adapter is constructed; changing the configuration object afterwards does not reconfigure an existing adapter. A nonblank unknown YAML value, such as auto or unsupported-mode, fails Spring property binding; an omitted or blank value retains the field default or under Spring's binding behavior. A null strategy supplied programmatically fails adapter construction with CONFIGURATION_ERROR.

union-all emits at most one mutually exclusive branch per final cursor key and applies the complete ordering and page limit to the combined result. It sends one SQL request, but can cause more server scans and sorting work. The response row limit and decompressed-byte limit still apply. See pagination for mixed-direction examples and compatibility and validation for exact tested server/strategy combinations. TsGate does not detect the server version, change the strategy automatically, or retry HTTP 500 responses using another SQL form.

IoTDB Tablet RPC encoding

tsdb.iotdb.table.rpc-compression-enabled defaults to true, so applications can omit it. It permits the official SDK's compact encoding/compression of Tablet RPC payloads; the SDK still decides whether a particular Tablet qualifies. This is independent of Thrift transport compression and on-disk TsFile compression.

For an older table-model server such as IoTDB 2.0.2 that cannot decode the newer Tablet representation, explicitly disable it in the application's existing IoTDB configuration:

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

This fragment supplements the connection and credentials above. The setting is applied when the physical session pool is built, including a replacement pool created during recovery. There is no automatic server-version guess or automatic retry of writes with another encoding.

Compatibility checks must write and read back at least 10 rows in one actual Tablet. A business batch containing 10 or more records is insufficient if grouping by measurement or splitting by tablet-max-row-size leaves every Tablet below 10 rows; smaller batches can miss the SDK's encoding threshold. Setting false changes the wire representation, not TsGate's validation, row limits or batch commit-state contract. See compatibility and validation for completed evidence; neither this switch nor an SDK upgrade establishes compatibility with every old or future server version.

Auto-configuration and startup semantics

The active starter auto-configures a com.alandevise.tsgate.core.TGTemplate bean named tgTemplate, unless the application already provides its own TGTemplate. Prefer injection by type; if name-based injection is needed, use @Qualifier("tgTemplate") or @Resource(name = "tgTemplate"). A custom bean name must match the application's injection points. TGQueryBuilder<T> is created by tgTemplate.query(...) for each query and is not a shared starter bean. See TG API and template configuration for the public types and a custom bean example.

• Each starter is disabled by default and requires an explicit enable: true. Missing or false flags keep it inactive; blank or invalid flags are configuration errors. There is no automatic activation based on connection settings.
• Multiple dependencies may coexist, but at most one backend may be enabled. Conflict checks use the current Spring context configuration, without static global state, and run before client initialization.
• Unconfigured or explicitly disabled adapters do not validate connections or create clients. An explicitly enabled backend with partial configuration undergoes complete configuration validation; it is not ignored because some required settings are missing. With no active backend, no adapter or TGTemplate is auto-configured.
• No native client bean exists for a disabled backend. Code referring to multiple clients should use ObjectProvider or optional injection, or guard backend-specific components with @Conditional(TSDBAdapterEnabledCondition.IoTDB.class), InfluxDB.class, InfluxDB1.class or OpenGemini.class. If no backend is active, also disable components depending on TGTemplate, for example with @Conditional(TSDBAdapterEnabledCondition.class).
• Missing required settings, invalid batch limits and a disabled IoTDB pool are configuration errors that fail startup regardless of fail-fast.
• Adapter initialization creates client resources and binds the default database to the IoTDB pool; it does not establish physical Sessions. IoTDB validates the default database when the first Session is borrowed. Deployment must create that database in advance and keep it available, or the first borrow fails.
• fail-fast=true closes the adapter and rethrows a client-resource initialization failure. With false, all four source starters retain the adapter/template after that failure while the native client is unavailable for typed optional injection. Required native-client injection can still prevent startup. Use ObjectProvider or optional injection until resources are initialized. This policy does not probe database/table availability or alter runtime write/query errors.
• The starters do not provide a HealthIndicator, detect database outages or recovery, or stop the application when its TSDB becomes unavailable. Use database metrics or application monitoring for runtime health.

Configuration lifetime

All four source adapters defensively capture connection and operation settings at construction, including nested HTTP/table/pool settings and the IoTDB node URL list. Mutating the caller's Properties objects before or after init() does not change that adapter, its native client, or a replacement IoTDB physical pool. Configuration binding must finish before construction.

To change the endpoint, credentials, database, timeouts, discovery policy or limits, create a new adapter/context with the new settings and coordinate replacement with application operations. Retrying a transient initialization failure uses the original captured settings; correcting invalid settings requires a new instance. This is a configuration consistency rule and does not add live reconfiguration. Explicit per-operation database arguments remain supported.

Default database rules

• All four backends use tsdb when database is omitted; an explicit blank value is invalid, and an explicitly configured name is preserved. Changing the default does not create, rename or migrate an existing database.
• write(record), batchWrite(records) and fluent queries without database(...) use the default database configured in YAML.
• The IoTDB pool is bound to that default database. Operations with no explicit database, or with the same default database, execute directly. Only explicit access to another database issues USE.
• When a cross-database Session closes, the IoTDB client restores the pool's default database before returning the physical Session to the pool.
• InfluxDB 3 writes send the target database in the db parameter of /api/v3/write_lp; InfluxDB 1.x and openGemini use /write's db parameter.
• Native executeQuery(...) has no database argument and does not rewrite SQL. IoTDB does not explicitly issue USE, but its borrowed Session already has the default database context. InfluxDB 3 / 1.x / openGemini query APIs require a database and use tsdb.influxdb.database / tsdb.influxdb1.database / tsdb.opengemini.database respectively, without changing the query text.
• Native IoTDB SQL can directly reference tables in the default database. Prefer explicit database.table names for cross-database SQL.

Official and compatible client injection

The starter exposes the active adapter's native client as a Spring bean:

@Autowired
private ITableSessionPool tableSessionPool;

@Autowired
private InfluxDBClient influxDBClient;

IoTDB supports pool mode only; applications may directly inject ITableSessionPool. Only the active backend's client bean exists. All four source starters may be dependencies: set exactly one backend flag to true; other retained configuration blocks remain inactive without their own true flags.

These clients come from resources maintained internally by the adapter. Spring and the adapter manage their closure. Application methods must not close an injected InfluxDB client or IoTDB pool. A Session borrowed from ITableSessionPool must be closed after use to return it to the pool.

Native clients are borrowed references. Direct calls bypass the adapter's query row/byte limits and lifecycle read lock; applications must coordinate native operations during shutdown.

For the OpenGemini adapter, openGeminiClient is a stable proxy of the compatible org.influxdb.InfluxDB. ping() / version() use the captured endpoint, credentials and HTTP settings and inspect the real X-Geminidb-Version header. A successful HTTP response with a nonblank version is required for a good ping; failed or missing-header responses are not assigned a fictitious version. Other native operations preserve backend responses, including error DTOs. Database and selected retention policy must exist; write acknowledgment does not guarantee immediate visibility of a new measurement/tag-series index. See OpenGemini integration.

All four source adapters follow NEW → READY → CLOSED. Repeated init() does not create or overwrite resources. Failed initialization releases resources already created and allows retry. close() is idempotent, clears references and permanently closes that instance. Subsequent initialization, writes, queries or native-client access fail with ADAPTER_STATE_ERROR.

Close waits for reads/writes already inside the adapter, including entire batches, before releasing clients. For InfluxDB and openGemini, configure http-client.call-timeout-ms when shutdown wait must be bounded. Its default of 0 means no total call deadline; a slow response that keeps transferring data can prolong shutdown.

IoTDB repeat initialization retains the same exposed ITableSessionPool proxy; connection recovery replaces only its physical pool. Manual close() -> init() is no longer supported: create a new adapter/context. Its lifecycle lock protects complete adapter operations and terminal shutdown, while business code must still coordinate sessions borrowed directly from the native pool. Use IoTDB connection, borrow and query timeout settings to bound operations; InfluxDB http-client settings do not apply to IoTDB.

Inject the InfluxDB 1.x official client directly (openGemini uses the same compatible type with its bean openGeminiClient):

@Autowired
private org.influxdb.InfluxDB influxDB1Client;

With fail-fast=false, the native client may be unavailable after a tolerated resource initialization failure on any backend; use ObjectProvider or optional injection. Adapter/template operations fail with ADAPTER_STATE_ERROR until initialization succeeds. Retry adapter.init() after a transient resource problem is resolved, then obtain the borrowed client through getNativeClient() (InfluxDB 1.x / 3 / openGemini) or getSessionPool() (IoTDB). Spring does not automatically recreate a previously unavailable native-client bean. Missing required settings remain startup errors regardless of fail-fast.

Databases, tables and retention

The starters do not send requests to create databases, tables or measurements, or to create/modify retention policies or TTL. When a target is absent, native backend write behavior determines whether it is created or an error is returned. Queries do not create databases or tables.

• IoTDB: create the database and table in the application initialization or deployment process. A table without its own TTL/retention inherits the database-level policy.
• openGemini default engine: create the database and selected retention policy in advance; its adapter reuses the InfluxDB1 compatibility implementation and exposes org.influxdb.InfluxDB, not the openGemini-specific SDK.
• InfluxDB 1.x: create the database in advance; the server creates a measurement on its first line-protocol write.
• InfluxDB 3 Core: the first line-protocol write may create the database and table. Explicit creation during deployment remains appropriate when permissions, database names or retention must be managed in advance.

Use the official client or operations scripts in application initialization when explicit creation is needed.

---

← Getting started · Writes, models and errors →

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.