TsGate

English | 简体中文

TsGate is a modular Java adapter library for time-series databases. It brings annotated POJO writes, fluent queries and result mapping behind a shared API, with dedicated adapters for IoTDB's table model, InfluxDB 3 Core and InfluxDB OSS 1.x.

Applications can integrate an adapter directly or use its Spring Boot starter. Enable the selected starter with enable: true and supply its connection settings. Other backends stay inactive by default. TsGate keeps database-specific capabilities explicit while reducing repeated connection, mapping and query code.

• Annotated POJO mapping with @TGMeasurement, @TGTime, @TGTag and @TGField.
• Synchronous single and batch writes with explicit batch commit outcomes.
• Fluent filtering, projections, aggregation and pagination, subject to backend capabilities.
• Validated result conversion, bounded queries and consistent exception codes.
• Independent Spring Boot starters, YAML configuration and official native client access.
• A Java 17 baseline and Apache-2.0 licensing.

flowchart TB
    APP["Business application<br/>Annotated POJOs and query calls"]
    YAML["YAML configuration"]
    subgraph TSGATE["TsGate"]
        STARTER["Spring Boot starters<br/>Configuration and lifecycle"]
        API["TGTemplate<br/>TGQueryBuilder"]
        CORE["Metadata and result mapping<br/>Validation and query limits"]
        SPI["TSDBAdapter interface"]
        IOT["tsgate-iotdb<br/>Table Session and Tablet"]
        INF3["tsgate-influxdb3<br/>HTTP SQL and line protocol"]
        INF1["tsgate-influxdb1<br/>HTTP InfluxQL and line protocol"]
        STARTER -.-> API
        STARTER -. "one active backend" .-> SPI
        API <--> CORE
        API --> SPI
        SPI --> IOT
        SPI --> INF3
        SPI --> INF1
    end
    APP --> API
    YAML --> STARTER
    IOT --> DBI[("IoTDB table model")]
    INF3 --> DB3[("InfluxDB 3 Core")]
    INF1 --> DB1[("InfluxDB OSS 1.x")]
    classDef entry fill:#e5f6f3,stroke:#167d8d,color:#132d3a
    classDef shared fill:#edf3fb,stroke:#54789c,color:#132d3a
    classDef backend fill:#f4f0fa,stroke:#83709d,color:#132d3a
    class APP,YAML entry
    class STARTER,API,CORE,SPI shared
    class IOT,INF3,INF1,DBI,DB3,DB1 backend

TGTemplate and TGQueryBuilder provide the business-facing API. Shared metadata and mapping logic translate application objects into common records and query models. Implementations of TSDBAdapter translate those models into each database's protocol and query dialect.

The public annotations and query entry points use the TG prefix: TGMeasurement, TGTime, TGTag, TGField, TGTemplate and TGQueryBuilder. The default Spring template bean is named tgTemplate.

All three 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.

One Spring context enables at most one backend; multiple active backends fail before client initialization, and no explicitly enabled backend means no adapter, TGTemplate or official client bean is created. Active backends still undergo complete configuration validation. The three adapter branches above represent available implementations; official native clients are exposed for backend-specific operations.

These are verified versions, not a guarantee covering every release or version combination. Backend capabilities differ; the bilingual Wiki guides record the exact matrix and limitations.

Tablet RPC encoding/compression is enabled by default. For older IoTDB servers without this protocol capability, explicitly set tsdb.iotdb.table.rpc-compression-enabled: false; SDK versions are selected through build dependencies, independently of YAML connection settings.

InfluxDB 3 strict composite cursor pagination defaults to tsdb.influxdb.strict-cursor-sql: or. An explicit union-all strategy accommodates older query planners while preserving complete ordering and query limits. It may increase server-side scanning; the bilingual Wiki guides explain its scope and verified combinations.

Maven artifacts use the GitHub-identity groupId io.github.alandevise and Java packages use com.alandevise.tsdb.*. Strict cursors preserve backend column identity and reject invalid time boundaries. All adapters have idempotent initialization and terminal closure; IoTDB applications must create a new instance after close. The bilingual Wiki documents cursor keys, supported Map result types and lifecycle rules.

The optional tsgate-bom consolidates the verified client dependency versions into one explicit Maven import. It manages versions without adding unused clients to the application. InfluxDB 3 Arrow JVM options still belong to the application launcher; see the bilingual getting-started guides.

TsGate's English and Chinese guides are available on the GitHub Wiki. They cover getting started, connection configuration, annotated data models, fluent queries, pagination, backend compatibility, testing and upgrades.

English guide · 简体中文指南

The TsGate skill guides coding assistants through application integration and contributor maintenance, including API examples, module responsibilities, compatibility boundaries, tests and documentation updates. To use it, install this file in a tsgate skill directory recognized by your assistant, or explicitly ask the assistant to read it. Root-file discovery depends on the tool.

Refer to each module's Javadoc for API contracts, configuration options, resource lifecycle and backend-specific limits.

TsGate is licensed under the Apache License 2.0. Copyright attribution is retained in NOTICE; third-party dependencies retain their respective licenses.