EN Release Notes 2.1.2

Home · GitHub

English | 简体中文

TsGate 2.1.2

Status: final-source local and main/tag GitHub CI verification fully passed. GitHub-only distribution; Maven Central remains at 2.1.0. GitHub package and reports. The 2.1.0 and 2.1.1 release-note pages remain unchanged historical records.

Changes

1. HTTP redirects: common HTTP adapter requests no longer automatically follow 3xx responses, including same-origin redirects. Configure the final endpoint. Backend error/commit distinctions remain; an uncertain write is never replayed through a redirect target.
2. InfluxDB 3 response integrity: a missing, empty or whitespace-only JSON response produces QUERY_ERROR. An actual JSON [] remains successful empty data; malformed/oversized responses retain their existing checks.
3. Aggregate output names: grouping tags, aggregate aliases and a generated window_start share a checked namespace. Collisions produce ARGUMENT_ERROR before I/O in direct query/count and template list/offset totals. Influx preserves case; IoTDB folds to lowercase. Without a generated window, window_start remains an available alias. InfluxDB 1.x/OpenGemini additionally reserve their implicit aggregate response column time; case-distinct Time remains available, and the two SQL adapters do not inherit this reservation. Unsupported capabilities keep their existing priority; native SQL is unchanged.
4. Combined HTTP batch byte budget: tsdb.influxdb.max-batch-bytes, tsdb.influxdb1.max-batch-bytes and tsdb.opengemini.max-batch-bytes default to 67108864 bytes (64 MiB). Positive constructor-snapshotted limits cover the prepared UTF-8 payloads of the complete application batch, including payload separators. Over-budget writes fail before any request with ARGUMENT_ERROR, NOT_COMMITTED and zero confirmed commits. Physical request and record limits remain separate; IoTDB has no new property.
5. POJO read plans: default reads reuse class-lifecycle constructor/field/type/candidate metadata, separately from write annotations. Lookup priority, inherited fields, explicit nulls, numeric/time conversion, plain DTOs and missing-column behavior are preserved. No result rows or business instances are cached; measured performance scope and limits are recorded below.

Upgrade and distribution

The verified source and annotated v2.1.2 tag have been pushed to GitHub. Both complete CI workflows are verified; see the GitHub distribution package and reports.

The public API, Java 17 baseline, existing SDKs, supported engine scope and TGTemplate → TSDBAdapter → backend architecture remain. Use the final HTTP URL, distinct aggregate output names and application batches within the configured byte budget. See configuration, queries and mapping.

Build and install the v2.1.2 source locally before declaring aligned io.github.alandevise modules/BOM at 2.1.2. This task does not sign, upload or publish Central artifacts; Central 2.1.0 remains unchanged. Local installation.

Result-mapping microbenchmark

The fresh benchmark on Java 17.0.14 / aarch64 compares the exact released 2.1.1 baseline core JAR with the current 2.1.2 JAR, using one unchanged harness and alternating three fresh JVM forks per variant. Each fork used four warmup rounds, seven measured iterations and two passes across all eight 1,000/10,000-row and one/four-thread scenarios. Baseline/current checksums were consistent across all six forks in every scenario.

The complete measured current JAR equals the staged audited release core JAR, SHA-256 b81f1f045ebed6cf5d35dfe9bf6473a121d325a093566dc4aed5cb6cfa27c6c2. The final benchmark/summary.json verifies that identity. The table reports the median of three fork medians; B→C means baseline 2.1.1 → current 2.1.2.

DTO scenario	Rows/thread	Threads	ns/row B→C	Allocated bytes/row B→C
Few fields, plain inherited DTO	1,000	1	3928.959 → 4110.209	3432.032 → 1936.032
Few fields, plain inherited DTO	1,000	4	235.734 → 161.094	3208.032 → 1520.032
Few fields, plain inherited DTO	10,000	1	749.252 → 417.742	3208.000 → 1520.000
Few fields, plain inherited DTO	10,000	4	203.924 → 118.673	3208.000 → 1520.000
Many fields, annotated inherited DTO	1,000	1	3205.458 → 2518.729	10942.872 → 6771.984
Many fields, annotated inherited DTO	1,000	4	906.245 → 503.427	10931.952 → 6771.952
Many fields, annotated inherited DTO	10,000	1	2947.825 → 2011.006	10942.803 → 6782.803
Many fields, annotated inherited DTO	10,000	4	900.102 → 527.461	10942.803 → 6782.803

The first 1,000-row, one-thread plain-DTO scenario took approximately 4.6% longer, while its allocation fell; the table therefore does not support a claim that every workload becomes faster. Earlier measurements are retained under history/pre-readiness/benchmark/ and history/readiness-v1/benchmark/, and are excluded from these final-JAR values.

This local non-JMH benchmark measures warm-cache DTO mapping only. It excludes database/network work, SQL, result parsing, write mapping and end-to-end throughput; it does not measure cold plan construction or persistent/peak memory. Allocation uses supported worker-thread counters, and multi-thread ns/row divides wall time by combined rows. Short warmup and fixed scenario order retain JIT/GC/scheduling effects. Matching selected-field checksums are a workload sanity check; functional regressions are verified separately.

Reproduce with the committed ResultMappingBenchmark source and separate baseline/current core JARs:

javac --release 17 -cp /path/to/baseline-core.jar -d /tmp/tsgate-benchmark-classes \
  tsgate-core/src/test/java/com/alandevise/tsgate/benchmark/ResultMappingBenchmark.java
java -Xms256m -Xmx512m -cp /tmp/tsgate-benchmark-classes:/path/to/baseline-core.jar \
  com.alandevise.tsgate.benchmark.ResultMappingBenchmark --label baseline \
  --warmup 4 --iterations 7 --passes 2 --rows 1000,10000 --threads 1,4
java -Xms256m -Xmx512m -cp /tmp/tsgate-benchmark-classes:/path/to/current-core.jar \
  com.alandevise.tsgate.benchmark.ResultMappingBenchmark --label current \
  --warmup 4 --iterations 7 --passes 2 --rows 1000,10000 --threads 1,4

Keep the compiled harness unchanged and alternate the two invocations for three fresh forks each. Use the platform's classpath separator when running outside Unix.

Verification evidence

Verified final source: 2ba077ac0f960555ccb00eee33373b7cd3ace324. Fresh runs of this commit passed 1,233 unit tests on each documented Temurin/Spring Boot pair (17.0.14/2.7.18, 21.0.11/3.5.14 and 25.0.2/4.1.0), with zero failures, errors or skips and unchanged source/Git identities. The unsigned 27-JAR/11-POM release audit passed, along with 71 Python runner/fixture cases (34 + 37) and actionlint. The fresh representative Docker suite also passed 120 integration tests with zero failures/errors/skips and all three owned containers removed. The eight-scenario final-JAR microbenchmark completed with consistent checksums and full JAR identity verification. The full OpenGemini matrix passed 184 tests across four deployments (46 each), with zero failures/errors/skips and all owned containers/networks removed. Combined with the representative suite, the final-source Docker total is 304 test executions. Both main/tag GitHub CI workflows also passed completely, with the downloaded original reports checked against this source and their cleanup evidence verified; superseded build results are excluded.

Validation scope	Final-source local result
Java 17 / Spring Boot 2.7.18 unit suite	1,233 passed; zero failures/errors/skips
Java 21 / Spring Boot 3.5.14 unit suite	1,233 passed; zero failures/errors/skips
Java 25 / Spring Boot 4.1.0 unit suite	1,233 passed; zero failures/errors/skips
Representative IoTDB / InfluxDB 1.x / InfluxDB 3 Docker suite	120 passed; zero failures/errors/skips; all three owned containers removed
OpenGemini 1.4.1 single node	46 passed; zero failures/errors/skips; owned resources removed
OpenGemini 1.4.1 three-node / three-replica cluster	46 passed; zero failures/errors/skips; owned resources removed
OpenGemini 1.5.2 single node	46 passed; zero failures/errors/skips; owned resources removed
OpenGemini 1.5.2 three-node / three-replica cluster	46 passed; zero failures/errors/skips; owned resources removed
Unsigned artifact audit	27 JARs and 11 POMs passed
Python runner/fixture regressions and actionlint	71 Python cases passed; workflow lint passed
Final audited-JAR mapping microbenchmark	Eight scenarios completed; all checksums consistent; complete release JAR identity verified
GitHub CI	Main run and v2.1.2 tag run: 9/9 jobs passed in each; original reports and cleanup verified
GitHub distribution	v2.1.2 package and reports; Maven Central remains at 2.1.0

Both CI runs use the same final source 2ba077ac0f960555ccb00eee33373b7cd3ace324. Each passed three JDK unit suites of 1,233 cases and 120 representative Docker tests (three backend runs of 43/52/25). Main CI additionally passed the two OpenGemini single-node deployments, 92 cases; tag CI passed the full four-deployment matrix, 184 cases. All downloaded original reports have zero failures/errors/skips, and owned-resource cleanup was checked. The downloaded-artifact validation manifest SHA-256 is ba2ed138cd8020466933075906d940211f08c196a442fe9f5ad7b73e530d8ef0. The local 304-execution Docker result above and these remote scopes are recorded separately.

The fresh representative Docker run used IoTDB 2.0.10 with RPC compression enabled, InfluxDB OSS 1.13.1 and InfluxDB 3 Core 3.11.5 with the default OR strategy; all three backend statuses passed. The completed runtime, representative-Docker and full OpenGemini matrix runs retain unchanged source/Git identities and successful owned-resource cleanup. The OpenGemini parent opengemini-matrix/summary.json confirms all four selected environments and 184 passed cases for the final source. Fresh reports are under .local-test/release-2.1.2-20261007/; superseded runs remain in the history directories below. No Central publication is performed; Maven Central remains at 2.1.0.

Initial cluster failures and test readiness correction

The first source-build matrix encountered three errors across the two cluster deployments: OpenGemini 1.4.1 ran 44 adapter cases with one error; 1.5.2 ran 44 adapter cases with two errors. Neither failed deployment reached its starter suite; stale starter XML was correctly excluded by the runner. The 1.4.1 aggregate case's seed write returned HTTP 500 (select timeout in 10s seconds); 1.5.2 also recorded uncertain write I/O. The adapter preserved the UNKNOWN commit contract and did not replay these writes.

Server logs and independent default-configuration controls with direct HTTP, released 2.1.1 and current 2.1.2 point to delayed per-database data-Raft readiness after CREATE DATABASE, despite healthy global metadata/membership. The test-only preparation waits read-only for initial data-Raft lifecycle evidence before each test's first write, with a 45-second deadline. Version 1.5.2 retains database/partition-scoped completion records; the official 1.4.1 binary needs a version-pinned complete-log transfer ledger and stable observations because its completion records lack those fields. This observes controlled serial fixture startup, not an atomic or ongoing health guarantee. See the readiness mechanism and limits.

All first-source reports/artifacts remain byte-preserved in history/pre-readiness/, including both failed opengemini-matrix/1.4.1-cluster/ and opengemini-matrix/1.5.2-cluster/ directories within it. Diagnostic controls remain in cluster-control/results*.json. Earlier single-node passes are not counted as final-source evidence. The zero-error final total refers only to the final-source runs; initial failures remain part of the release record.

An independent 1.4.1 three-node diagnostic exercised the corrected gate with three serially created databases. Six business writes were each attempted once and returned HTTP 204; all expected points were read from all three SQL endpoints, and owned resources were removed. Gate observations took approximately 6–7 seconds. Results and historical-log parser validation are retained in cluster-readiness-v2-control/results.json and history-validation.json. These controls validate the fixture observation under that controlled setup; they do not replace the separate formal four-deployment integration results or guarantee ongoing cluster health.

First readiness-gate defect and interruption

The first gate revision (b9ab030) incorrectly assumed that the 1.4.1 binary's transfer-completion records contained database and partition, causing the read-only gate to hit its 45-second deadline. The cluster run was deliberately interrupted; its finally cleanup passed. Complete summaries/logs and that revision's other reports/artifacts remain in history/readiness-v1/. The final source corrects this version-specific test assumption and changes no production adapter/POM behavior. Its complete validation and release-JAR benchmark were rerun, rather than reusing the previous revision's passes. This test-gate defect is separate from the initial server-readiness failures; uncertain writes are never automatically replayed.