Repository navigation
EN OpenGemini
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 retainscom.alandevise.tsdb.*. See migration steps and release status.
TsGate 2.1.0 adds independent OpenGemini adapter and starter modules and manages them in the 2.1.0 BOM. The existing Central 2.0.0 artifacts do not contain these modules. Use aligned 2.1.0 dependencies and follow the package migration when upgrading an existing application. Release status is separate from compatibility validation.
The adapter targets openGemini 1.5.2 and 1.4.1, using the default storage engine's InfluxQL interface. It implements the existing TSDBAdapter contract and exposes the same TGTemplate, TGQueryBuilder, TG* annotations and error/result types as the other backends. The backend changes only the dependency, configuration and native query dialect. The shared SPI, business POJO mapping and query model are unchanged.
Modules: tsgate-opengemini for direct Java integration, and tsgate-opengemini-spring-boot-starter for Spring Boot. The adapter reuses the bounded InfluxDB 1.x HTTP/InfluxQL implementation through composition. It has its own backend identity and property namespace. The compatible native client type is org.influxdb.InfluxDB, not the separate openGemini asynchronous SDK.
Use the starter for Spring Boot, or depend on tsgate-opengemini directly for a manually owned adapter. The 2.1.0 BOM manages both modules:
<dependency>
<groupId>io.github.alandevise</groupId>
<artifactId>tsgate-opengemini-spring-boot-starter</artifactId>
<version>2.1.0</version>
</dependency>tsdb:
query-log-enabled: true
opengemini:
enable: true
fail-fast: true
url: http://127.0.0.1:8086
database: business_metrics
username: ""
password: ""
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: falseThe default URL is http://localhost:8086; the default database is tsdb. Create the selected database and any named retention policy beforehand. A blank retention policy uses the server default. Empty credentials select unauthenticated access; configured credentials use HTTP Basic authentication. Supply secrets through application deployment configuration.
Only explicit tsdb.opengemini.enable=true activates this starter. All other backends remain disabled unless explicitly enabled. Enabling OpenGemini and InfluxDB1 together is an error even though the OpenGemini implementation depends on the InfluxDB1 module. Multiple starter dependencies may coexist, but one Spring context still selects at most one backend. Backend-specific components can use @Conditional(TSDBAdapterEnabledCondition.OpenGemini.class).
Inject TGTemplate as before. For example, with the application's existing annotated Reading POJO:
tgTemplate.write(reading);
tgTemplate.batchWrite(readings);
BatchWriteResult written = tgTemplate.batchWriteDetailed(readings);
List<Reading> rows = tgTemplate.query(Reading.class)
.whereTag("device", "sensor-a")
.timeRange(startMillis, endMillis)
.orderByTimeAsc()
.limit(100)
.list();
PageResult<Reading> page = tgTemplate.query(Reading.class)
.orderByTimeAsc().page(1, 100);Direct integration uses OpenGeminiProperties, optional OpenGeminiHttpClientProperties, and OpenGeminiAdapter. Call init() before using an adapter constructed manually, and close it when its owner shuts down. Configuration is copied at construction; later mutation does not redirect adapter or native-client operations. Initialization is idempotent, failed resource initialization can be retried, and close is terminal. Startup fail-fast=false follows the existing optional native-client policy; it does not probe server/database availability.
Both topologies use the same business API and YAML shape. For a cluster, url is a reachable ts-sql endpoint or a deployment-managed load balancer. The adapter does not discover meta/store nodes or automatically replay a failed write through another SQL endpoint. Configure any ingress routing and failover in the deployment. HTTP connection-failure retries default to false for this backend so uncertain writes are not silently retried by the transport.
The local cluster fixture runs three separate Docker containers, each with one ts-meta, one ts-store and one ts-sql. Cluster readiness requires three registered meta nodes and three registered stores, followed by cross-endpoint write/read verification. Three independent single-node databases do not count as a cluster. The fixture records server versions, image/source provenance, membership and readback results.
The default engine flushes newly created series indexes asynchronously. A successful write acknowledgement can precede query visibility for a new measurement or tag combination. Appending to a series whose index is already visible may be immediately readable. The common write result reports the confirmed request boundary; it does not promise strong read-after-write consistency. Applications that need to observe a particular point should poll reads with a deadline and a concrete expected result. The adapter performs one query request; it does not replay writes or delay an empty query. Docker tests establish complete point visibility through an independent HTTP oracle before asserting the query under test.
Measurement names follow the server's printable-name rules: comma, semicolon, slash, backslash, and the complete names . / .. are rejected. The entire batch is checked before any request, producing NOT_COMMITTED for an invalid name. Accepted names retain their identity, including equals signs, ordinary spaces and Chinese text. Field/tag backslashes remain supported by the line-protocol and InfluxQL escaping rules.
The exact server query error measurement not found is normalized to an empty successful result by the common structured query and to zero by count. executeQuery and borrowed native query DTOs retain server errors, including missing measurements: native statements may address multiple measurements or subqueries, so converting their failure to empty rows would hide an invalid query. Other server errors remain errors.
getNativeClient() returns one stable InfluxDB compatibility proxy. Its ping() validates a successful real HTTP response and reads X-Geminidb-Version; version() caches only a confirmed version. Health requests honor the constructor-time URL, credentials and timeout settings and release their temporary HTTP resources. Other methods, native exceptions and close operations delegate to the original client. Fluent client settings preserve proxy identity. The adapter owns shutdown, including local validation and result normalization; callers coordinate borrowed native calls separately.
The tested 1.4.1/1.5.2 Influx-compatible HTTP write path converts integer fields through float64 before storing them. An integer protocol suffix does not prevent this conversion: 9007199254740993i reads back as 9007199254740992. The OpenGemini adapter therefore checks the complete batch before I/O and accepts integer-typed fields only within signed-int64 bounds and when their exact value is representable by IEEE 754 float64. All integers from -2^53 to 2^53 are exact; some larger values, including 2^53+2 and Long.MIN_VALUE, are also exact. 2^53+1, Long.MAX_VALUE and Long.MIN_VALUE+1 are rejected with ARGUMENT_ERROR, NOT_COMMITTED and zero physical requests, without coercion or string encoding. Structured query/count also preflight exact integer filter literals, including every IN/BETWEEN value, because backend numeric comparisons can round them. Extreme integer-valued BigDecimal predicates are compared with signed-int64 bounds before integer expansion, so very large exponents cannot bypass validation or force unbounded allocation. Float/Double and fractional query literals retain ordinary floating-point semantics; existing BigDecimal field checks still apply. Epoch-millisecond timestamps use their separate time path. Native SQL and borrowed native writes bypass these checks and retain backend precision limitations; aggregate overflow and floating-point accumulation are not made exact by this validation. This restriction is specific to the HTTP adapter, not a claim about every OpenGemini engine or alternate ingestion protocol.
| Operation | Default-engine contract |
|---|---|
| POJO/record single and batch writes | Existing annotation mapping, preflight validation and detailed commit states |
| Time ranges, tag/field predicates and field selection | Existing fluent API and bounded mapped results |
| ASC/DESC time ordering and offset pagination | Supported through the common query API |
| Time-cursor pagination | Supported; rows sharing a boundary timestamp can be omitted by a time-only cursor |
| Aggregates, tag grouping and UTC/fixed-offset windows | Existing aggregation API; time windows require explicit start and end bounds |
| Count | Result-row semantics before pagination; sparse fields do not define row identity; response-byte limit still applies |
| Read-only native queries | Single SELECT, SHOW, or supported EXPLAIN [ANALYZE] SELECT; native administration uses the borrowed client |
| Strict composite cursors, FIELD ordering, tag-only projection | Explicit UNSUPPORTED_OPERATION in the inherited compatibility contract |
| Regional calendar-day windows/DST | Explicit UNSUPPORTED_OPERATION; use supported UTC or fixed-offset windows |
| COLUMNSTORE/Arrow/PromQL/cluster management | Outside this first adapter's verified contract; no claim covering every openGemini feature |
Ordinary/native queries obey the configured row and decompressed-response limits. Page lookahead may read one additional row. Count ignores pagination and cursors while retaining time-bound validation and the response-byte cap. Unsupported operations fail explicitly rather than returning an empty successful result.
Writes report confirmed request boundaries. A preflight rejection is NOT_COMMITTED; errors that may have persisted data remain UNKNOWN with confirmed earlier batch counts retained. Do not automatically replay an uncertain batch. Native operations bypass common validation/limits and must coordinate with adapter shutdown; callers must not close the borrowed client.
The namespace-migration regression on 2026-10-03 reran all four deployments against com.alandevise.tsgate.*: each passed 44 adapter/starter tests, with zero failures/errors/skips. Source hashes and cleanup records are under .local-test/package-migration-20261003/opengemini-matrix/. This is a recorded pre-release source snapshot; final 2.1.0 release verification is tracked separately in Compatibility and validation. Earlier evidence retains its original snapshot.
Local Docker validation on 2026-10-03 used ARM64, Temurin 17 and Spring Boot 2.7.18. Each environment ran the actual adapter and auto-discovered starter tests. Compatibility covers these exact default-engine releases and settings.
| Server | Topology | Replicas | Java integration results |
|---|---|---|---|
| 1.4.1 | Single node | 1 | 44 passed; 0 failed/errors/skipped |
| 1.4.1 | Three-node cluster | 3 | 44 passed; 0 failed/errors/skipped |
| 1.5.2 | Single node | 1 | 44 passed; 0 failed/errors/skipped |
| 1.5.2 | Three-node cluster | 3 | 44 passed; 0 failed/errors/skipped |
The cluster has three separate meta/store/SQL containers with a real three-voter Raft quorum and three registered stores. Database and retention-policy metadata confirm three replicas. Tests write through each SQL endpoint with both TGTemplate and the borrowed compatible client, then read the complete data set through every endpoint. Every owned test container/network was removed.
Reproduce from the repository root with Java/Maven pointing to the same JDK:
python3 tsgate-opengemini/src/test/scripts/run-matrix.py \
--output .local-test/opengemini-matrixThe fixture verifies official archive checksums, records binary/source provenance, and may download archives even when a matching image is cached. The runner saves fresh Failsafe XML reports and source hashes under its output directory. The 1.4.1 official binary reports build commit 42678b4a23e0c7921548f6ceacb812659591d0bf; its release tag points to 5ff486d020cf52df11d8de73aa4664fd843a4e53. Those are recorded separately rather than treating the attachment as a build of the tag commit.
The recorded namespace-migration snapshot passed 888 unit tests on each documented JDK/Boot combination (17/2.7.18, 21/3.5.14 and 25/4.1.0), 114 representative existing-backend Docker tests, 176 OpenGemini Docker tests across four environments, 27 unsigned binary/source/Javadoc archive checks in nine JAR modules, and 34 Python runner tests. These are historical source-regression results, not final 2.1.0 publication evidence. TLS, authenticated deployments, ingress failover and node-failure recovery were not exercised by the local topology matrix.
The 1.4.1 fixture uses the official complete binary distribution. The 1.5.2 release has no binary attachments, so its fixture builds the exact official tag commit 19ba0e2d9b428579004eb53d37d0c9b23034e2a9; it does not substitute main or a release candidate.
The existing representative three-database runner retains its IoTDB/InfluxDB coverage. OpenGemini integration tests require an explicitly supplied endpoint or the dedicated fixture; excluding them from that runner without an endpoint is not evidence of OpenGemini compatibility. See the local validation report for the separate four-topology matrix.
TsGate · Wiki home · 文档首页 · Apache-2.0 · NOTICE
Compatibility claims apply only to documented capabilities and verified versions. 兼容性承诺仅适用于已列明的能力和已验证的版本。