EN Release Notes 2.1.3

Home · English | 简体中文

TsGate 2.1.3 release notes

2.1.3 is published through the GitHub source/tag and Maven Central; same-SHA CI and public artifact verification passed.

Version 2.1.3 tightens structured-filter validation, merges IoTDB physical table-name case variants before whole-batch checks, verifies backend registration in tests/CI, rejects duplicate IoTDB/InfluxDB 3 result keys, and checks direct-adapter batch counts before copying inputs. The public API, Template → SPI → adapter architecture, Java 17/client/server baselines and configuration defaults remain unchanged.

Changes in this patch

1. Structured filters and default count guard. Comparisons require one operand, BETWEEN two, and IN at least one. Blank/missing columns, missing operators, null operands and non-finite Float/Double operands fail with ARGUMENT_ERROR before database I/O. Fluent optional-input normalization is preserved. Query/count validate the retained filters; count still ignores pagination/cursors in a private copy, and the shared SPI default count(null) reports ARGUMENT_ERROR.
2. IoTDB physical table grouping. Table names are grouped by Locale.ROOT lowercase physical identity before complete-batch role/type validation. Compatible case variants share Tablets while retaining table-local row order and caller records/maps. Conflicting variants reject the whole application batch with METADATA_ERROR, NOT_COMMITTED and zero I/O. Identified failed tables use their lowercase physical name; an unidentified preflight/acquisition failure may still report null. This does not add cross-Tablet transactions.
3. Backend registration completeness. A test-only inventory and portable checker cross-check reactor modules, adapter activation, starter/imports, BOM, shared contracts, required Docker/CI execution and release artifact inventory. Missing required associations fail closed. The common runner and CI exercise this gate. Production activation and SPI are unchanged; backends need only their declared deployment topology.
4. Duplicate result decoding. IoTDB rejects exact duplicate SDK output column names before reading rows, including duplicate metadata for an empty result. InfluxDB 3 rejects exact duplicate JSON object keys in successful query responses, including an earlier null value or a later row. query, count and adapter executeQuery fail entirely with QUERY_ERROR, without partial rows or a fabricated successful count, while existing resource cleanup remains active. Case-distinct names, separate-row reuse, legitimate nulls and numeric precision remain unchanged. Native SQL text is not rewritten; the server can reject ambiguous aliases first. Borrowed native clients bypass the adapter decoder. InfluxDB 1.x/openGemini retain their existing duplicate-column and tag/field collision checks; this does not make all their JSON metadata keys strict. Loose DTO matching is unchanged.
5. Early direct-adapter batch count. All four adapters check reported nonempty collection size after lifecycle/null/empty checks and before List.copyOf, then recheck the snapshot before validating records or encoding. Clearly oversized inputs fail with ARGUMENT_ERROR, NOT_COMMITTED, zero validated/committed records, zero physical batches and zero I/O, without calling the collection’s iterator/copy methods. TGTemplate already had this protection. Null/empty behavior and existing limits/defaults remain unchanged. Arbitrary custom or concurrently modified collections still have no absolute memory/atomicity guarantee.

Upgrade impact

Before upgrading, review dynamically constructed filters: comparisons require exactly one operand, BETWEEN two, and IN at least one. Direct-model null operands and non-finite Float/Double values now fail with ARGUMENT_ERROR before I/O. Optional fluent-builder normalization remains unchanged; the literal string "null" remains an ordinary string. Count ignores pagination/cursors in a private copy, and the SPI default count(null) reports ARGUMENT_ERROR.

IoTDB groups table names by Locale.ROOT lowercase physical identity before checking complete-batch column roles/types. Conflicting variants now fail with METADATA_ERROR / NOT_COMMITTED before borrowing a session; compatible variants retain table-local row order and existing Tablet splitting. Use unique native-query output aliases: exact duplicate SDK columns or InfluxDB 3 JSON object keys now fail the entire query/count/executeQuery with QUERY_ERROR. Case-distinct result keys and the existing loose DTO mapping remain unchanged.

Direct adapter batchWriteDetailed / batchWrite rejects an obviously oversized reported collection size before copying or traversing records, then rechecks the snapshot. Lifecycle checks still come first and ready-state null/empty batches remain successful. Rejection is ARGUMENT_ERROR / NOT_COMMITTED with zero I/O. Split batches explicitly or assess the existing positive max-batch-records setting; this adds no resource-budget setting or hard memory guarantee for arbitrary custom collections.

Central consumers upgrading from 2.1.0 also receive the earlier GitHub-only 2.1.1/2.1.2 fixes: numeric cursor boundaries and IoTDB column identity, HTTP redirect commit reporting, missing InfluxDB 3 JSON errors, aggregate output-name checks, the configurable 64 MiB complete HTTP batch budget and POJO read-plan caching. These are inherited changes, not additions first made in 2.1.3. Review 2.1.1 notes and 2.1.2 notes, including final HTTP endpoint configuration and explicit batch splitting.

Public APIs, configuration defaults, dependency baselines and the main architecture remain unchanged. Existing resource limits and BOM verification retain their documented scope.

Verification evidence

The frozen implementation passed local prerelease verification: 1,476 unit checks on each of JDK 17/21/25, 323 Docker integration checks and 83 Python checks, with zero failures/errors/skips and successful owned-resource cleanup. The 166-input source manifest and implementation diff were checked before release preparation. These are the earlier local prerelease results, not newly executed 2.1.3 JDK 21/25 or Docker runs.

Final source 18fccb6 and tag v2.1.3 are pushed. Its fresh signed Temurin 17 build passed 1,476 unit checks. The release audit passed for nine JAR modules, 27 JARs / 11 POMs, 38 valid signatures and 228 signed-bundle entries; the credential scan passed. Bundle SHA-256: e192aec3177c6cb5ab2dd9cd4d6a61b31a6c8c2f01e7a0f921d599d90612bb3f. Same-SHA tag CI passed all 9 jobs, including 1,476 unit checks on each of JDK 17/21/25 and 323 Docker integration checks. Central is PUBLISHED; all 38 primary artifacts and 38 published signatures were downloaded from the public Maven repository and matched the signed bundle by SHA-256.

Local prerelease runtime	Unit checks
Temurin 17.0.14 / Spring Boot 2.7.18	1,476
JDK 21.0.11 / Spring Boot 3.5.14	1,476
JDK 25.0.2 / Spring Boot 4.1.0	1,476

The local Docker round covered IoTDB 2.0.10 (49 checks), InfluxDB OSS 1.13.1 (27), InfluxDB 3 Core 3.11.5 (55), and openGemini 1.4.1/1.5.2 default-engine single-node and three-node/three-replica deployments (48 each, 192 total): 323 Docker checks. All 11 owned containers and 4 networks were removed. The 83 Python checks covered runner/registration/fixture behavior. These representative versions do not certify every older supported combination afresh; older version evidence remains historical.

Publication verification passed: final-source signed Java 17 packaging, the full same-SHA tag CI matrix, Central publication and public artifact/signature hash matching are complete. The earlier local prerelease results above retain their separate source scope.

Central deployment 666534d2-2358-486c-bc96-0446619a3e12 reached PUBLISHED under user-managed publication. All 38 primary artifacts and 38 corresponding public signatures match the signed upload bundle.

Distribution

Coordinates are io.github.alandevise:*:2.1.3, including tsgate-bom and the four starters. Keep TsGate modules and BOM aligned. Version 2.1.3 is available from Maven Central; a matching local source installation remains optional. Follow Testing and publishing for current status; Getting started contains 2.1.3 examples. Historical 2.1.0, 2.1.1 and 2.1.2 release notes retain their original evidence.