feat(tdengine): replace Java agent with native Rust driver

This commit is contained in:
t8y2 committed 2026-08-04 17:42:05 +08:00
1 parent ec8f308c53
commit d38fe5b173
32 files changed
+5943 -1777

No files matched your search

+2 -1
View File
@@ -51,8 +51,9 @@ const nativeDriverDirectories = {
kingbase: "kingbase-go", kingbase: "kingbase-go",
vastbase: "vastbase-go", vastbase: "vastbase-go",
rabbitmq: "rabbitmq", rabbitmq: "rabbitmq",
tdengine: "tdengine",
}; };
const nativeDriverModules = new Set(["cassandra", "duckdb", "oracle", "xugu", "kingbase", "vastbase", "rabbitmq"]); const nativeDriverModules = new Set(["cassandra", "duckdb", "oracle", "xugu", "kingbase", "vastbase", "rabbitmq", "tdengine"]);
function resolveAgentModule(moduleName, { legacyStandaloneModules, moduleExists, readModuleFile }) { function resolveAgentModule(moduleName, { legacyStandaloneModules, moduleExists, readModuleFile }) {
let checkDir = null; let checkDir = null;
@@ -34,6 +34,20 @@ test("bumps DuckDB after its initial release", () => {
assert.equal(result.versions.duckdb, "0.1.1"); assert.equal(result.versions.duckdb, "0.1.1");
}); });
test("classifies TDengine Rust changes as native-only", () => {
const result = evaluateAgentVersionBump({
versions: { tdengine: "0.1.39" },
changedFiles: ["agents/drivers/tdengine/src/driver.rs"],
moduleExists: (path) => path === "agents/drivers/tdengine",
readModuleFile: () => "",
});
assert.equal(result.versions.tdengine, "0.1.40");
assert.deepEqual(result.changedModules, ["tdengine"]);
assert.deepEqual(result.javaModules, []);
assert.deepEqual(result.nativeModules, ["tdengine"]);
});
test("bumps the native RabbitMQ agent from its Go directory", () => { test("bumps the native RabbitMQ agent from its Go directory", () => {
const result = evaluateAgentVersionBump({ const result = evaluateAgentVersionBump({
versions: { rabbitmq: "0.1.0" }, versions: { rabbitmq: "0.1.0" },
@@ -15,7 +15,7 @@ import { basename, join } from "node:path";
import { tmpdir } from "node:os"; import { tmpdir } from "node:os";
const REGISTRY_ASSET = "agent-registry.json"; const REGISTRY_ASSET = "agent-registry.json";
const NATIVE_MODULES = new Set(["duckdb", "oracle", "xugu", "kingbase", "vastbase", "rabbitmq"]); const NATIVE_MODULES = new Set(["duckdb", "oracle", "xugu", "kingbase", "vastbase", "rabbitmq", "tdengine"]);
const PLATFORMS = [ const PLATFORMS = [
"macos-aarch64", "macos-aarch64",
"macos-x64", "macos-x64",
@@ -60,6 +60,24 @@ test("rejects an incomplete reusable native platform set", () => {
); );
}); });
test("requires all TDengine native platforms when reusing a release", () => {
const native = Object.fromEntries(
platforms.slice(0, -1).map((platform, index) => [platform, artifact(`dbx-agent-tdengine-0.1.40-${platform}.tar.zst`, String(index + 1))]),
);
const registry = { drivers: { tdengine: { version: "0.1.40", native } }, jres: {} };
assert.throws(
() => collectReusableAssetPlan({
registry,
release: releaseFor(Object.values(native)),
versions: { tdengine: "0.1.40" },
modules: ["tdengine"],
reuseJre: false,
}),
/missing=windows-x64/,
);
});
test("ignores zero-size legacy JAR placeholders for native-only modules", () => { test("ignores zero-size legacy JAR placeholders for native-only modules", () => {
const native = Object.fromEntries( const native = Object.fromEntries(
platforms.map((platform, index) => [platform, artifact(`dbx-agent-duckdb-0.1.2-${platform}.tar.zst`, String(index + 1))]), platforms.map((platform, index) => [platform, artifact(`dbx-agent-duckdb-0.1.2-${platform}.tar.zst`, String(index + 1))]),
+115 -2
View File
@@ -515,6 +515,117 @@ jobs:
name: duckdb-native-${{ matrix.platform }} name: duckdb-native-${{ matrix.platform }}
path: "release-native/dbx-agent-duckdb-*" path: "release-native/dbx-agent-duckdb-*"
build-tdengine-native:
needs: [bump-versions]
if: ${{ contains(fromJSON(needs.bump-versions.outputs.native_modules), 'tdengine') }}
strategy:
fail-fast: false
matrix:
include:
- runner: macos-latest
target: aarch64-apple-darwin
platform: macos-aarch64
extension: ""
smoke: true
- runner: macos-15-intel
target: x86_64-apple-darwin
platform: macos-x64
extension: ""
smoke: true
- runner: ubuntu-22.04-arm
target: aarch64-unknown-linux-gnu
platform: linux-aarch64
extension: ""
manylinux_image: quay.io/pypa/manylinux_2_28_aarch64
- runner: ubuntu-22.04
target: x86_64-unknown-linux-gnu
platform: linux-x64
extension: ""
manylinux_image: quay.io/pypa/manylinux_2_28_x86_64
- runner: windows-2022
target: aarch64-pc-windows-msvc
platform: windows-aarch64
extension: .exe
- runner: windows-2022
target: x86_64-win7-windows-msvc
platform: windows-x64
extension: .exe
smoke: true
win7: true
runs-on: ${{ matrix.runner }}
env:
CARGO_INCREMENTAL: "0"
CARGO_TARGET_DIR: ${{ github.workspace }}/target/tdengine-driver
RUSTC_WRAPPER: sccache
steps:
- uses: actions/checkout@v5
- uses: dtolnay/rust-toolchain@1.97.1
if: runner.os != 'Linux' && matrix.win7 != true
with:
targets: ${{ matrix.target }}
- name: Setup Rust for Windows 7
if: matrix.win7 == true
uses: dtolnay/rust-toolchain@nightly
with:
toolchain: nightly-2026-07-22
components: rust-src
- uses: mozilla-actions/sccache-action@9e7fa8a12102821edf02ca5dbea1acd0f89a2696 # v0.0.10
with:
version: "v0.10.0"
- name: Build TDengine native driver
shell: bash
run: |
if [ -n "${{ matrix.manylinux_image }}" ]; then
docker run --rm \
--user "$(id -u):$(id -g)" \
-e HOME=/tmp/dbx-rust-home \
-e CARGO_INCREMENTAL=0 \
-e CARGO_TARGET_DIR=/workspace/target/tdengine-driver \
-v "${{ github.workspace }}:/workspace" \
-w /workspace \
"${{ matrix.manylinux_image }}" \
bash -lc '
mkdir -p "$HOME"
curl --proto "=https" --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --profile minimal --default-toolchain 1.97.1
source "$HOME/.cargo/env"
cargo build \
--manifest-path agents/drivers/tdengine/Cargo.toml \
--locked \
--release \
--bin dbx-tdengine-driver \
--target "${{ matrix.target }}"
'
else
BUILD_STD=()
if [ "${{ matrix.win7 }}" = "true" ]; then
BUILD_STD=(-Z build-std=std,panic_abort)
fi
cargo build \
--manifest-path agents/drivers/tdengine/Cargo.toml \
--locked \
--release \
--bin dbx-tdengine-driver \
--target "${{ matrix.target }}" \
"${BUILD_STD[@]}"
fi
mkdir -p release-native
cp \
"target/tdengine-driver/${{ matrix.target }}/release/dbx-tdengine-driver${{ matrix.extension }}" \
"release-native/dbx-agent-tdengine-${{ matrix.platform }}${{ matrix.extension }}"
if [ -n "${{ matrix.manylinux_image }}" ]; then
docker run --rm \
--user "$(id -u):$(id -g)" \
-v "${{ github.workspace }}/release-native:/driver:ro" \
"${{ matrix.manylinux_image }}" \
"/driver/dbx-agent-tdengine-${{ matrix.platform }}" < /dev/null
elif [ "${{ matrix.smoke }}" = "true" ]; then
"release-native/dbx-agent-tdengine-${{ matrix.platform }}${{ matrix.extension }}" < /dev/null
fi
- uses: actions/upload-artifact@v4
with:
name: tdengine-native-${{ matrix.platform }}
path: "release-native/dbx-agent-tdengine-*"
build-jre: build-jre:
needs: [bump-versions] needs: [bump-versions]
if: ${{ needs.bump-versions.outputs.build_jre == 'true' }} if: ${{ needs.bump-versions.outputs.build_jre == 'true' }}
@@ -624,7 +735,7 @@ jobs:
retention-days: 1 retention-days: 1
release: release:
needs: [bump-versions, commit-versions, build-agents, build-oracle-native, build-xugu-native, build-rabbitmq-native, build-cassandra-native, build-kingbase-native, build-vastbase-native, build-duckdb-native, build-jre, reuse-previous-assets] needs: [bump-versions, commit-versions, build-agents, build-oracle-native, build-xugu-native, build-rabbitmq-native, build-cassandra-native, build-kingbase-native, build-vastbase-native, build-duckdb-native, build-tdengine-native, build-jre, reuse-previous-assets]
if: ${{ always() && !contains(needs.*.result, 'failure') && !contains(needs.*.result, 'cancelled') }} if: ${{ always() && !contains(needs.*.result, 'failure') && !contains(needs.*.result, 'cancelled') }}
runs-on: ubuntu-latest runs-on: ubuntu-latest
steps: steps:
@@ -747,6 +858,7 @@ jobs:
xugu) echo "虚谷 XuguDB" ;; xugu) echo "虚谷 XuguDB" ;;
rabbitmq) echo "RabbitMQ" ;; rabbitmq) echo "RabbitMQ" ;;
cassandra) echo "Apache Cassandra" ;; cassandra) echo "Apache Cassandra" ;;
tdengine) echo "TDengine" ;;
*) echo "$name" ;; *) echo "$name" ;;
esac esac
} }
@@ -810,7 +922,7 @@ jobs:
[ -n "$DRIVERS" ] && DRIVERS="${DRIVERS},"$'\n' [ -n "$DRIVERS" ] && DRIVERS="${DRIVERS},"$'\n'
DRIVERS="${DRIVERS}$(generate_jar_entry "$name" "$label" "$f" "$jre_key" "$version" "$external_driver" "$native_json")" DRIVERS="${DRIVERS}$(generate_jar_entry "$name" "$label" "$f" "$jre_key" "$version" "$external_driver" "$native_json")"
done done
for name in oracle xugu kingbase vastbase duckdb rabbitmq cassandra; do for name in oracle xugu kingbase vastbase duckdb rabbitmq cassandra tdengine; do
version=$(get_module_version "$name") version=$(get_module_version "$name")
[ -f "release/dbx-agent-${name}-${version}.jar" ] && continue [ -f "release/dbx-agent-${name}-${version}.jar" ] && continue
native_json=$(generate_native_platforms "$name" "$version") native_json=$(generate_native_platforms "$name" "$version")
@@ -881,6 +993,7 @@ jobs:
xugu) echo "虚谷 XuguDB" ;; xugu) echo "虚谷 XuguDB" ;;
rabbitmq) echo "RabbitMQ" ;; rabbitmq) echo "RabbitMQ" ;;
cassandra) echo "Apache Cassandra" ;; cassandra) echo "Apache Cassandra" ;;
tdengine) echo "TDengine" ;;
*) echo "$name" ;; *) echo "$name" ;;
esac esac
} }
+49
View File
@@ -575,6 +575,9 @@ jobs:
- name: DuckDB driver tests - name: DuckDB driver tests
run: cargo test --manifest-path drivers/duckdb/Cargo.toml --locked run: cargo test --manifest-path drivers/duckdb/Cargo.toml --locked
- name: TDengine driver tests
run: cargo test --manifest-path drivers/tdengine/Cargo.toml --locked
- name: Agent validation - name: Agent validation
run: python3 scripts/validate_agents.py run: python3 scripts/validate_agents.py
@@ -618,6 +621,52 @@ jobs:
run: CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -trimpath -ldflags="-s -w" -o /tmp/dbx-agent-vastbase-linux-x64 . run: CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -trimpath -ldflags="-s -w" -o /tmp/dbx-agent-vastbase-linux-x64 .
working-directory: agents/drivers/vastbase-go working-directory: agents/drivers/vastbase-go
- name: TDengine native agent build
run: cargo build --manifest-path drivers/tdengine/Cargo.toml --locked --release --bin dbx-tdengine-driver
- name: TDengine native agent integration tests
shell: bash
run: |
set -euo pipefail
while IFS='|' read -r version image; do
name="dbx-tdengine-${version//./-}"
docker rm -fv "$name" >/dev/null 2>&1 || true
docker run -d --name "$name" \
--memory 4g \
--ulimit nofile=65535:65535 \
-p 6030:6030 \
-p 6041:6041 \
"$image"
cleanup() {
docker rm -fv "$name" >/dev/null 2>&1 || true
}
trap cleanup EXIT
ready=false
for _ in $(seq 1 90); do
if docker exec "$name" taos -s 'SELECT server_version()' >/dev/null 2>&1; then
ready=true
break
fi
sleep 2
done
if [ "$ready" != "true" ]; then
docker logs "$name"
exit 1
fi
TDENGINE_INTEGRATION=1 \
TDENGINE_TEST_HOST=127.0.0.1 \
TDENGINE_TEST_PORT=6041 \
cargo test --manifest-path drivers/tdengine/Cargo.toml --locked --test live -- --nocapture
cleanup
trap - EXIT
done <<'EOF'
2.4.0.14|tdengine/tdengine:2.4.0.14
2.6.0.34|tdengine/tdengine:2.6.0.34
3.0.7.1|tdengine/tdengine:3.0.7.1
3.3.6.13|tdengine/tdengine:3.3.6.13
3.4.2.2|tdengine/tsdb:3.4.2.2
EOF
- name: Cassandra native agent integration tests - name: Cassandra native agent integration tests
shell: bash shell: bash
working-directory: agents/drivers/cassandra-go working-directory: agents/drivers/cassandra-go
+7 -6
View File
@@ -38,7 +38,7 @@ Each agent runs as a standalone process and communicates with DBX via stdin/stdo
| bigquery | Google BigQuery | BigQuery JDBC | | bigquery | Google BigQuery | BigQuery JDBC |
| kylin | Apache Kylin | Kylin JDBC | | kylin | Apache Kylin | Kylin JDBC |
| sundb | SunDB | SunDB JDBC | | sundb | SunDB | SunDB JDBC |
| tdengine | TDengine | taos-jdbcdriver (WebSocket, REST fallback) | | tdengine | TDengine 2.4+ | taos-connector-rust native WebSocket agent |
| yashandb | 崖山 YashanDB | YashanDB JDBC | | yashandb | 崖山 YashanDB | YashanDB JDBC |
| xugu | 虚谷 XuguDB | XuguDB Go native agent | | xugu | 虚谷 XuguDB | XuguDB Go native agent |
| iotdb | Apache IoTDB | IoTDB JDBC | | iotdb | Apache IoTDB | IoTDB JDBC |
@@ -49,7 +49,7 @@ Each agent runs as a standalone process and communicates with DBX via stdin/stdo
## Multi-JRE Support ## Multi-JRE Support
Most Java agents target JRE 21. Native agents, such as `cassandra`, `duckdb`, `oracle`, `kingbase`, `xugu`, and `rabbitmq`, do not require a JRE. DBX downloads and manages the JRE 21 installation automatically for Java agents. Most Java agents target JRE 21. Native agents, such as `cassandra`, `duckdb`, `oracle`, `kingbase`, `tdengine`, `xugu`, and `rabbitmq`, do not require a JRE. DBX downloads and manages the JRE 21 installation automatically for Java agents.
## JDBC Connection Pooling ## JDBC Connection Pooling
@@ -75,7 +75,7 @@ Set `DBX_AGENT_JDBC_POOL_ENABLED=false` for a runtime-level compatibility fallba
For new agents, prefer a **native (Go or Rust) driver** over a Java/JDBC agent whenever a mature, license-compatible native driver is available. Native agents ship as a single self-contained executable with no JRE, which significantly reduces memory footprint and startup time — the JVM baseline that every Java agent pays even when idle is avoided entirely. For new agents, prefer a **native (Go or Rust) driver** over a Java/JDBC agent whenever a mature, license-compatible native driver is available. Native agents ship as a single self-contained executable with no JRE, which significantly reduces memory footprint and startup time — the JVM baseline that every Java agent pays even when idle is avoided entirely.
- **Native (C++/Go/Rust)** — preferred when a usable native driver exists. See `drivers/cassandra-go` (Apache cassandra-gocql-driver), `drivers/duckdb`, `drivers/oracle-go` (go-ora), `drivers/kingbase-go` (gokb), `drivers/vastbase-go` (openGauss connector), `drivers/xugu`, and `drivers/rabbitmq` (amqp091-go) as reference implementations. No JRE download or management is needed. - **Native (C++/Go/Rust)** — preferred when a usable native driver exists. See `drivers/cassandra-go` (Apache cassandra-gocql-driver), `drivers/duckdb`, `drivers/oracle-go` (go-ora), `drivers/kingbase-go` (gokb), `drivers/vastbase-go` (openGauss connector), `drivers/tdengine` (taos-connector-rust), `drivers/xugu`, and `drivers/rabbitmq` (amqp091-go) as reference implementations. No JRE download or management is needed.
- **Java/JDBC** — the default fallback when only a JDBC driver exists for the database, or when the native driver is immature or unmaintained. Most agents still fall in this category. - **Java/JDBC** — the default fallback when only a JDBC driver exists for the database, or when the native driver is immature or unmaintained. Most agents still fall in this category.
Native agents implement the same JSON-RPC contract and `versions.json` registration as Java agents; they ship an `agent` executable instead of `agent.jar`. If both native and Java source implementations exist for the same database, publish only the native artifact unless the Java variant has a separately registered compatibility profile, such as `oracle-legacy` / `oracle-10g`. Native agents implement the same JSON-RPC contract and `versions.json` registration as Java agents; they ship an `agent` executable instead of `agent.jar`. If both native and Java source implementations exist for the same database, publish only the native artifact unless the Java variant has a separately registered compatibility profile, such as `oracle-legacy` / `oracle-10g`.
@@ -90,11 +90,12 @@ Requires JDK 21 (Gradle toolchain auto-downloads if needed).
(cd drivers/cassandra-go && go build -o agent .) (cd drivers/cassandra-go && go build -o agent .)
(cd drivers/kingbase-go && go build -o agent .) (cd drivers/kingbase-go && go build -o agent .)
(cd drivers/vastbase-go && go build -o agent .) (cd drivers/vastbase-go && go build -o agent .)
(cargo build --manifest-path drivers/tdengine/Cargo.toml --release --locked)
(cd drivers/xugu && go build -o agent .) (cd drivers/xugu && go build -o agent .)
(cd drivers/rabbitmq && go build -o agent .) (cd drivers/rabbitmq && go build -o agent .)
``` ```
Output JARs are in `drivers/{module}/build/libs/`. Native agents build from `drivers/cassandra-go`, `drivers/oracle-go`, `drivers/kingbase-go`, `drivers/vastbase-go`, `drivers/xugu`, and `drivers/rabbitmq`. Output JARs are in `drivers/{module}/build/libs/`. Native agents build from `drivers/cassandra-go`, `drivers/oracle-go`, `drivers/kingbase-go`, `drivers/vastbase-go`, `drivers/tdengine`, `drivers/xugu`, and `drivers/rabbitmq`.
### Local DBX Runtime Test ### Local DBX Runtime Test
@@ -108,14 +109,14 @@ cp agents/drivers/<db_type>/build/libs/*-all.jar ~/.dbx/agents/drivers/<db_type>
Restart DBX or disconnect and reconnect the database so the new agent process loads the replacement JAR. Restart DBX or disconnect and reconnect the database so the new agent process loads the replacement JAR.
Native agents such as `cassandra`, `oracle`, `kingbase`, `xugu`, and `rabbitmq` use the `agent` executable in the driver directory instead of `agent.jar`. Native agents such as `cassandra`, `oracle`, `kingbase`, `tdengine`, `xugu`, and `rabbitmq` use an `agent` executable instead of `agent.jar`. TDengine builds `target/release/dbx-tdengine-driver` from `drivers/tdengine/Cargo.toml`.
## Versioning ## Versioning
Agent module versions are tracked in [`versions.json`](versions.json). Agent module versions are tracked in [`versions.json`](versions.json).
- **Changing an existing driver** — do not edit `versions.json` manually. The release CI diffs each `drivers/<module>/` directory against the previous tag and auto-bumps the patch version for every changed module (see [`bump-agent-versions.mjs`](../.github/scripts/bump-agent-versions.mjs)). A change to the shared `agents/common` runtime bumps every module that packages it. - **Changing an existing driver** — do not edit `versions.json` manually. The release CI diffs each `drivers/<module>/` directory against the previous tag and auto-bumps the patch version for every changed module (see [`bump-agent-versions.mjs`](../.github/scripts/bump-agent-versions.mjs)). A change to the shared `agents/common` runtime bumps every module that packages it.
- **Adding a new driver** — add an entry to `versions.json`, e.g. `"rabbitmq": "0.1.0"`. The CI only bumps keys already present in the file, so a new module is invisible to versioning until it is registered here. In the same change, also add the module to `settings.gradle` and the support table above — `versions.json` keys must match the agent modules declared in `settings.gradle`, excluding the infrastructure modules `common` and `test-support`. - **Adding a new driver** — add an entry to `versions.json`, e.g. `"rabbitmq": "0.1.0"`. The CI only bumps keys already present in the file, so a new module is invisible to versioning until it is registered here. Java modules must also be added to `settings.gradle`; native modules must be registered in the release version script and workflow. Update the support table in the same change.
## Development ## Development
+7 -6
View File
@@ -38,7 +38,7 @@ DBX 的 Agent 驱动 —— 通过 JDBC 和原生数据库驱动支持各种数
| bigquery | Google BigQuery | BigQuery JDBC | | bigquery | Google BigQuery | BigQuery JDBC |
| kylin | Apache Kylin | Kylin JDBC | | kylin | Apache Kylin | Kylin JDBC |
| sundb | SunDB | SunDB JDBC | | sundb | SunDB | SunDB JDBC |
| tdengine | TDengine | taos-jdbcdriver(WebSocket,REST 兜底) | | tdengine | TDengine 2.4+ | taos-connector-rust 原生 WebSocket agent |
| yashandb | 崖山 YashanDB | YashanDB JDBC | | yashandb | 崖山 YashanDB | YashanDB JDBC |
| xugu | 虚谷 XuguDB | XuguDB Go 原生 agent | | xugu | 虚谷 XuguDB | XuguDB Go 原生 agent |
| iotdb | Apache IoTDB | IoTDB JDBC | | iotdb | Apache IoTDB | IoTDB JDBC |
@@ -49,7 +49,7 @@ DBX 的 Agent 驱动 —— 通过 JDBC 和原生数据库驱动支持各种数
## 多 JRE 支持 ## 多 JRE 支持
多数 Java agent 以 JRE 21 为目标。原生 agent(如 `cassandra`、`oracle`、`kingbase`、`xugu` 和 `rabbitmq`)不需要 JRE。对 Java agent,DBX 会自动下载并管理 JRE 21 安装。 多数 Java agent 以 JRE 21 为目标。原生 agent(如 `cassandra`、`duckdb`、`oracle`、`kingbase`、`tdengine`、`xugu` 和 `rabbitmq`)不需要 JRE。对 Java agent,DBX 会自动下载并管理 JRE 21 安装。
## JDBC 连接池 ## JDBC 连接池
@@ -75,7 +75,7 @@ HikariCP 会直接打进启用连接池的 Agent JAR。已经使用 DBX 托管 J
对于新 agent,只要存在成熟、许可证兼容的原生驱动,优先选择**原生(Go 或 Rust)驱动**而非 Java/JDBC agent。原生 agent 以单一自包含可执行文件发布,无需 JRE,可显著降低内存占用和启动时间 —— 完全避开 Java agent 即便空闲也要付出的 JVM 基线开销。 对于新 agent,只要存在成熟、许可证兼容的原生驱动,优先选择**原生(Go 或 Rust)驱动**而非 Java/JDBC agent。原生 agent 以单一自包含可执行文件发布,无需 JRE,可显著降低内存占用和启动时间 —— 完全避开 Java agent 即便空闲也要付出的 JVM 基线开销。
- **原生(Go/Rust)** —— 存在可用原生驱动时首选。参考 `drivers/cassandra-go`(Apache cassandra-gocql-driver)、`drivers/oracle-go`(go-ora)、`drivers/kingbase-go`(gokb)、`drivers/vastbase-go`(openGauss connector)、`drivers/xugu` 和 `drivers/rabbitmq`(amqp091-go)。无需 JRE 下载与管理。 - **原生(Go/Rust)** —— 存在可用原生驱动时首选。参考 `drivers/cassandra-go`(Apache cassandra-gocql-driver)、`drivers/duckdb`、`drivers/oracle-go`(go-ora)、`drivers/kingbase-go`(gokb)、`drivers/vastbase-go`(openGauss connector)、`drivers/tdengine`(taos-connector-rust)、`drivers/xugu` 和 `drivers/rabbitmq`(amqp091-go)。无需 JRE 下载与管理。
- **Java/JDBC** —— 当某数据库只有 JDBC 驱动,或原生驱动不成熟、缺乏维护时的默认兜底方案。多数 agent 仍属此类。 - **Java/JDBC** —— 当某数据库只有 JDBC 驱动,或原生驱动不成熟、缺乏维护时的默认兜底方案。多数 agent 仍属此类。
原生 agent 实现与 Java agent 相同的 JSON-RPC 契约和 `versions.json` 登记;它发布的是 `agent` 可执行文件而非 `agent.jar`。若同一数据库同时保留原生和 Java 源码实现,默认只发布原生产物;只有 Java 变体以独立兼容配置登记时才同时发布,例如 `oracle-legacy` / `oracle-10g`。 原生 agent 实现与 Java agent 相同的 JSON-RPC 契约和 `versions.json` 登记;它发布的是 `agent` 可执行文件而非 `agent.jar`。若同一数据库同时保留原生和 Java 源码实现,默认只发布原生产物;只有 Java 变体以独立兼容配置登记时才同时发布,例如 `oracle-legacy` / `oracle-10g`。
@@ -90,11 +90,12 @@ HikariCP 会直接打进启用连接池的 Agent JAR。已经使用 DBX 托管 J
(cd drivers/cassandra-go && go build -o agent .) (cd drivers/cassandra-go && go build -o agent .)
(cd drivers/kingbase-go && go build -o agent .) (cd drivers/kingbase-go && go build -o agent .)
(cd drivers/vastbase-go && go build -o agent .) (cd drivers/vastbase-go && go build -o agent .)
(cargo build --manifest-path drivers/tdengine/Cargo.toml --release --locked)
(cd drivers/xugu && go build -o agent .) (cd drivers/xugu && go build -o agent .)
(cd drivers/rabbitmq && go build -o agent .) (cd drivers/rabbitmq && go build -o agent .)
``` ```
产物 JAR 在 `drivers/{module}/build/libs/`。原生 agent 从 `drivers/cassandra-go`、`drivers/oracle-go`、`drivers/kingbase-go`、`drivers/vastbase-go`、`drivers/xugu` 和 `drivers/rabbitmq` 构建。 产物 JAR 在 `drivers/{module}/build/libs/`。原生 agent 从 `drivers/cassandra-go`、`drivers/duckdb`、`drivers/oracle-go`、`drivers/kingbase-go`、`drivers/vastbase-go`、`drivers/tdengine`、`drivers/xugu` 和 `drivers/rabbitmq` 构建。
### 本地 DBX 运行时测试 ### 本地 DBX 运行时测试
@@ -108,14 +109,14 @@ cp agents/drivers/<db_type>/build/libs/*-all.jar ~/.dbx/agents/drivers/<db_type>
重启 DBX 或断开重连数据库,使新 agent 进程加载替换后的 JAR。 重启 DBX 或断开重连数据库,使新 agent 进程加载替换后的 JAR。
`cassandra`、`oracle`、`kingbase`、`xugu` 和 `rabbitmq` 等原生 agent 使用驱动目录下的 `agent` 可执行文件而非 `agent.jar`。 `cassandra`、`oracle`、`kingbase`、`tdengine`、`xugu` 和 `rabbitmq` 等原生 agent 使用可执行文件而非 `agent.jar`。TDengine 从 `drivers/tdengine/Cargo.toml` 构建 `target/release/dbx-tdengine-driver`。
## 版本管理 ## 版本管理
Agent 模块的版本记录在 [`versions.json`](versions.json) 中,遵循以下规则: Agent 模块的版本记录在 [`versions.json`](versions.json) 中,遵循以下规则:
- **修改现有驱动**:无需手动编辑 `versions.json`。发版 CI 会把每个 `drivers/<module>/` 目录与上一个 tag 做对比,对有变更的模块自动 bump patch 版本号(见 [`bump-agent-versions.mjs`](../.github/scripts/bump-agent-versions.mjs))。若改动的是共享运行时 `agents/common`,所有依赖它的模块会一并 bump。 - **修改现有驱动**:无需手动编辑 `versions.json`。发版 CI 会把每个 `drivers/<module>/` 目录与上一个 tag 做对比,对有变更的模块自动 bump patch 版本号(见 [`bump-agent-versions.mjs`](../.github/scripts/bump-agent-versions.mjs))。若改动的是共享运行时 `agents/common`,所有依赖它的模块会一并 bump。
- **新增驱动**:在 `versions.json` 中新增一行,例如 `"rabbitmq": "0.1.0"`。CI 只 bump 文件里已存在的 key,所以新模块在登记到这里之前对版本管理完全不可见。同一次改动中,还要把模块加进 `settings.gradle` 并更新上方的支持表 —— `versions.json` 的 key 必须与 `settings.gradle` 声明的 agent 模块一致(不含 `common`、`test-support` 这类基础设施模块)。 - **新增驱动**:在 `versions.json` 中新增一行,例如 `"rabbitmq": "0.1.0"`。CI 只 bump 文件里已存在的 key,所以新模块在登记到这里之前对版本管理完全不可见。Java 模块还要加入 `settings.gradle`;原生模块要在发版版本脚本与 workflow 中登记,并同步更新上方支持表。
## 开发 ## 开发
+1 -1
View File
@@ -8,7 +8,7 @@ def pooledJdbcProjects = [
'access', 'bigquery', 'dameng', 'databend', 'databricks', 'db2', 'exasol', 'access', 'bigquery', 'dameng', 'databend', 'databricks', 'db2', 'exasol',
'firebird', 'gbase8a', 'gbase8s', 'goldendb', 'h2', 'h2-legacy', 'highgo', 'hive', 'firebird', 'gbase8a', 'gbase8s', 'goldendb', 'h2', 'h2-legacy', 'highgo', 'hive',
'informix', 'iotdb', 'iris', 'kylin', 'neo4j', 'oceanbase-oracle', 'oscar', 'saphana', 'informix', 'iotdb', 'iris', 'kylin', 'neo4j', 'oceanbase-oracle', 'oscar', 'saphana',
'snowflake', 'spark', 'sqlserver-legacy', 'sundb', 'tdengine', 'teradata', 'trino', 'uxdb', 'snowflake', 'spark', 'sqlserver-legacy', 'sundb', 'teradata', 'trino', 'uxdb',
'vertica', 'yashandb' 'vertica', 'yashandb'
] as Set ] as Set
def agentProjects = subprojects.findAll { !infrastructureProjects.contains(it.name) } def agentProjects = subprojects.findAll { !infrastructureProjects.contains(it.name) }
@@ -62,6 +62,8 @@ class MetadataConstraintCoverageTest {
result.add(driversRoot.relativize(file).getName(0).toString()); result.add(driversRoot.relativize(file).getName(0).toString());
} else if ("main.go".equals(fileName) && hasGoMetadataDispatcher(file)) { } else if ("main.go".equals(fileName) && hasGoMetadataDispatcher(file)) {
result.add(driversRoot.relativize(file).getName(0).toString()); result.add(driversRoot.relativize(file).getName(0).toString());
} else if (fileName.endsWith(".rs") && hasRustMetadataDispatcher(file)) {
result.add(driversRoot.relativize(file).getName(0).toString());
} }
}); });
} }
@@ -85,6 +87,15 @@ class MetadataConstraintCoverageTest {
} }
} }
private static boolean hasRustMetadataDispatcher(Path file) {
try {
String source = readUtf8(file);
return source.contains("\"list_tables\"") || source.contains("\"list_objects\"");
} catch (IOException e) {
throw new RuntimeException(e);
}
}
private static Map<String, String> readCoverageMatrix(Path matrix) throws IOException { private static Map<String, String> readCoverageMatrix(Path matrix) throws IOException {
Map<String, String> result = new HashMap<>(); Map<String, String> result = new HashMap<>();
for (String line : Files.readAllLines(matrix, StandardCharsets.UTF_8)) { for (String line : Files.readAllLines(matrix, StandardCharsets.UTF_8)) {
+1
View File
@@ -0,0 +1 @@
/target/
+2842
View File
File diff suppressed because it is too large. Load diff
+30
View File
@@ -0,0 +1,30 @@
[workspace]
[package]
name = "dbx-tdengine-driver"
version = "0.1.0"
edition = "2021"
license = "Apache-2.0"
publish = false
[dependencies]
anyhow = "1"
base64 = "0.22"
chrono = "0.4"
chrono-tz = "0.10"
futures = "0.3"
percent-encoding = "2"
serde = { version = "1", features = ["derive"] }
serde_json = "1"
taos = { git = "https://github.com/taosdata/taos-connector-rust.git", rev = "f49c37185987a3f5a893a02d04fe5db662a79c37", default-features = false, features = ["ws-rustls"] }
tokio = { version = "1", features = ["full"] }
tokio-util = { version = "0.7", features = ["rt"] }
url = "2"
uuid = { version = "1", features = ["v4"] }
[profile.release]
panic = "abort"
strip = true
lto = true
codegen-units = 1
opt-level = "s"
-10
View File
@@ -1,10 +0,0 @@
dependencies {
implementation fileTree(dir: 'libs', include: ['*.jar'])
implementation 'com.taosdata.jdbc:taos-jdbcdriver:3.6.3'
}
tasks.named('shadowJar') {
manifest {
attributes('Agent-Label': 'TDengine', 'Main-Class': 'com.dbx.agent.tdengine.TDengineAgent')
}
}
+274
View File
@@ -0,0 +1,274 @@
use anyhow::{bail, Context, Result};
use percent_encoding::percent_decode_str;
use std::net::IpAddr;
use url::Url;
use crate::model::ConnectParams;
const DEFAULT_HOST: &str = "127.0.0.1";
const DEFAULT_PORT: u16 = 6041;
const DEFAULT_USER: &str = "root";
const DEFAULT_PASSWORD: &str = "taosdata";
#[derive(Debug)]
pub struct BuiltDsn {
pub value: String,
pub database: String,
}
pub fn build_dsn(params: &ConnectParams) -> Result<BuiltDsn> {
if !params.client_cert_path.trim().is_empty() || !params.client_key_path.trim().is_empty() {
bail!("TDengine Rust WebSocket connector does not support client certificate authentication");
}
let mut url = if params.connection_string.trim().is_empty() {
build_from_fields(params)?
} else {
normalize_connection_string(params.connection_string.trim(), params.ssl)?
};
apply_connection_fields(&mut url, params)?;
merge_query_params(&mut url, &params.url_params);
if (params.ssl || !params.ca_cert_path.trim().is_empty()) && url.scheme() == "ws" {
url.set_scheme("wss").map_err(|_| anyhow::anyhow!("failed to enable TLS in TDengine connection URL"))?;
}
if !params.ca_cert_path.trim().is_empty() {
set_query_param(&mut url, "tls_mode", "verify_identity");
set_query_param(&mut url, "tls_ca", params.ca_cert_path.trim());
}
let database = url
.path_segments()
.and_then(|mut segments| segments.find(|segment| !segment.is_empty()))
.map(|segment| percent_decode_str(segment).decode_utf8_lossy().into_owned())
.unwrap_or_default();
Ok(BuiltDsn { value: url.into(), database })
}
fn build_from_fields(params: &ConnectParams) -> Result<Url> {
let scheme = if params.ssl { "wss" } else { "ws" };
let host = if params.host.trim().is_empty() { DEFAULT_HOST } else { params.host.trim() };
let port = if params.port == 0 { DEFAULT_PORT } else { params.port };
let username = if params.username.is_empty() { DEFAULT_USER } else { &params.username };
let password = if params.password.is_empty() { DEFAULT_PASSWORD } else { &params.password };
let mut url = Url::parse(&format!("{scheme}://{DEFAULT_HOST}:{port}/"))?;
if let Ok(address) = host.parse::<IpAddr>() {
url.set_ip_host(address).map_err(|_| anyhow::anyhow!("invalid TDengine host"))?;
} else {
url.set_host(Some(host)).map_err(|_| anyhow::anyhow!("invalid TDengine host"))?;
}
url.set_username(username).map_err(|_| anyhow::anyhow!("invalid TDengine username"))?;
url.set_password(Some(password)).map_err(|_| anyhow::anyhow!("invalid TDengine password"))?;
if !params.database.trim().is_empty() {
url.set_path(&format!("/{}", params.database.trim()));
}
Ok(url)
}
fn apply_connection_fields(url: &mut Url, params: &ConnectParams) -> Result<()> {
if url.username().is_empty() {
let username = if params.username.is_empty() { DEFAULT_USER } else { &params.username };
url.set_username(username).map_err(|_| anyhow::anyhow!("invalid TDengine username"))?;
}
if url.password().is_none() {
let password = if params.password.is_empty() { DEFAULT_PASSWORD } else { &params.password };
url.set_password(Some(password)).map_err(|_| anyhow::anyhow!("invalid TDengine password"))?;
}
if url.path().trim_matches('/').is_empty() && !params.database.trim().is_empty() {
url.set_path(&format!("/{}", params.database.trim()));
}
Ok(())
}
fn normalize_connection_string(raw: &str, ssl: bool) -> Result<Url> {
let trimmed = raw.trim();
let normalized = if let Some(value) = strip_prefix_ignore_ascii_case(trimmed, "jdbc:TAOS-WS://") {
format!("{}://{value}", if ssl { "wss" } else { "ws" })
} else if let Some(value) = strip_prefix_ignore_ascii_case(trimmed, "jdbc:TAOS-RS://") {
format!("{}://{value}", if ssl { "wss" } else { "ws" })
} else if let Some(value) = strip_prefix_ignore_ascii_case(trimmed, "tdengine://") {
format!("{}://{value}", if ssl { "wss" } else { "ws" })
} else if let Some(value) = strip_prefix_ignore_ascii_case(trimmed, "taosws://") {
format!("{}://{value}", if ssl { "wss" } else { "ws" })
} else if let Some(value) = strip_prefix_ignore_ascii_case(trimmed, "taoswss://") {
format!("wss://{value}")
} else {
trimmed.to_string()
};
let mut url = Url::parse(&normalized).with_context(|| "invalid TDengine connection string")?;
if !matches!(url.scheme(), "ws" | "wss" | "http" | "https") {
bail!("TDengine native agent supports only WebSocket connection strings");
}
if matches!(url.scheme(), "http") {
url.set_scheme("ws").map_err(|_| anyhow::anyhow!("invalid TDengine HTTP connection string"))?;
} else if matches!(url.scheme(), "https") {
url.set_scheme("wss").map_err(|_| anyhow::anyhow!("invalid TDengine HTTPS connection string"))?;
}
remove_control_params(&mut url);
Ok(url)
}
fn merge_query_params(url: &mut Url, raw: &str) {
let raw = raw.trim().trim_start_matches('?');
if raw.is_empty() {
return;
}
let additions = url::form_urlencoded::parse(raw.as_bytes())
.filter(|(key, _)| !is_control_param(key))
.map(|(key, value)| (key.into_owned(), value.into_owned()))
.collect::<Vec<_>>();
let mut query = url.query_pairs_mut();
for (key, value) in additions {
query.append_pair(&key, &value);
}
}
fn remove_control_params(url: &mut Url) {
let kept = url
.query_pairs()
.filter(|(key, _)| !is_control_param(key))
.map(|(key, value)| (key.into_owned(), value.into_owned()))
.collect::<Vec<_>>();
url.set_query(None);
if kept.is_empty() {
return;
}
let mut query = url.query_pairs_mut();
for (key, value) in kept {
query.append_pair(&key, &value);
}
}
fn set_query_param(url: &mut Url, key: &str, value: &str) {
let mut pairs = url
.query_pairs()
.filter(|(existing, _)| !existing.eq_ignore_ascii_case(key))
.map(|(existing, value)| (existing.into_owned(), value.into_owned()))
.collect::<Vec<_>>();
pairs.push((key.to_string(), value.to_string()));
url.set_query(None);
let mut query = url.query_pairs_mut();
for (key, value) in pairs {
query.append_pair(&key, &value);
}
}
fn is_control_param(key: &str) -> bool {
key.eq_ignore_ascii_case("transport") || key.eq_ignore_ascii_case("dbx.transport")
}
fn strip_prefix_ignore_ascii_case<'a>(value: &'a str, prefix: &str) -> Option<&'a str> {
value.get(..prefix.len()).filter(|head| head.eq_ignore_ascii_case(prefix))?;
value.get(prefix.len()..)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn builds_ws_dsn_from_connection_fields() {
let dsn = build_dsn(&ConnectParams {
host: "db.example.com".into(),
port: 6041,
database: "power_data".into(),
username: "root".into(),
password: "secret".into(),
url_params: "timezone=UTC&dbx.transport=rest".into(),
..Default::default()
})
.unwrap();
assert_eq!(dsn.value, "ws://root:secret@db.example.com:6041/power_data?timezone=UTC");
assert_eq!(dsn.database, "power_data");
}
#[test]
fn accepts_legacy_jdbc_urls_without_transport_controls() {
let dsn = build_dsn(&ConnectParams {
connection_string: "jdbc:TAOS-WS://127.0.0.1:6041/db?transport=ws&timezone=UTC".into(),
..Default::default()
})
.unwrap();
assert_eq!(dsn.value, "ws://root:taosdata@127.0.0.1:6041/db?timezone=UTC");
assert_eq!(dsn.database, "db");
}
#[test]
fn fills_connection_string_credentials_and_database_from_fields() {
let dsn = build_dsn(&ConnectParams {
username: "reader".into(),
password: "secret".into(),
database: "metrics".into(),
connection_string: "jdbc:TAOS-WS://td.example.com:6041?transport=ws".into(),
..Default::default()
})
.unwrap();
assert_eq!(dsn.value, "ws://reader:secret@td.example.com:6041/metrics");
assert_eq!(dsn.database, "metrics");
}
#[test]
fn preserves_explicit_connection_string_credentials_and_database() {
let dsn = build_dsn(&ConnectParams {
username: "ignored".into(),
password: "ignored".into(),
database: "ignored".into(),
connection_string: "ws://url-user:url-pass@td.example.com:6041/url-db".into(),
..Default::default()
})
.unwrap();
assert_eq!(dsn.value, "ws://url-user:url-pass@td.example.com:6041/url-db");
assert_eq!(dsn.database, "url-db");
}
#[test]
fn passes_ca_certificate_path_to_the_websocket_connector() {
let dsn =
build_dsn(&ConnectParams { ssl: true, ca_cert_path: "/tmp/tdengine-ca.pem".into(), ..Default::default() })
.unwrap();
let url = Url::parse(&dsn.value).unwrap();
assert_eq!(url.scheme(), "wss");
let query = url.query_pairs().collect::<std::collections::HashMap<_, _>>();
assert_eq!(query.get("tls_mode").map(|value| value.as_ref()), Some("verify_identity"));
assert_eq!(query.get("tls_ca").map(|value| value.as_ref()), Some("/tmp/tdengine-ca.pem"));
}
#[test]
fn rejects_mutual_tls_paths_instead_of_ignoring_them() {
let error =
build_dsn(&ConnectParams { client_cert_path: "/tmp/client.pem".into(), ..Default::default() }).unwrap_err();
assert!(error.to_string().contains("client certificate"));
}
#[test]
fn ca_certificate_enables_tls_and_replaces_conflicting_query_values() {
let dsn = build_dsn(&ConnectParams {
connection_string: "ws://td.example.com:6041/db?tls_mode=verify_ca&tls_ca=old.pem".into(),
ca_cert_path: "/tmp/new-ca.pem".into(),
..Default::default()
})
.unwrap();
let url = Url::parse(&dsn.value).unwrap();
assert_eq!(url.scheme(), "wss");
let tls_mode = url.query_pairs().filter(|(key, _)| key == "tls_mode").collect::<Vec<_>>();
let tls_ca = url.query_pairs().filter(|(key, _)| key == "tls_ca").collect::<Vec<_>>();
assert_eq!(tls_mode.as_slice(), &[("tls_mode".into(), "verify_identity".into())]);
assert_eq!(tls_ca.as_slice(), &[("tls_ca".into(), "/tmp/new-ca.pem".into())]);
}
#[test]
fn supports_ipv6_hosts_and_decodes_connection_database() {
let fields =
build_dsn(&ConnectParams { host: "::1".into(), database: "power data".into(), ..Default::default() })
.unwrap();
assert_eq!(fields.value, "ws://root:taosdata@[::1]:6041/power%20data");
assert_eq!(fields.database, "power data");
let connection = build_dsn(&ConnectParams {
connection_string: "taoswss://td.example.com:6041/power%20data".into(),
..Default::default()
})
.unwrap();
assert_eq!(connection.value, "wss://root:taosdata@td.example.com:6041/power%20data");
assert_eq!(connection.database, "power data");
}
}
File diff suppressed because it is too large. Load diff
+7
View File
@@ -0,0 +1,7 @@
mod config;
mod driver;
mod model;
mod runtime;
mod value;
pub use runtime::run;
+7
View File
@@ -0,0 +1,7 @@
#[tokio::main]
async fn main() {
if let Err(error) = dbx_tdengine_driver::run().await {
eprintln!("TDengine driver failed: {error:#}");
std::process::exit(1);
}
}
@@ -1,980 +0,0 @@
package com.dbx.agent.tdengine;
import com.dbx.agent.AbstractJdbcAgent;
import com.dbx.agent.ColumnInfo;
import com.dbx.agent.ConnectParams;
import com.dbx.agent.DatabaseInfo;
import com.dbx.agent.ExecuteQueryOptions;
import com.dbx.agent.ForeignKeyInfo;
import com.dbx.agent.IndexInfo;
import com.dbx.agent.JdbcExecutor;
import com.dbx.agent.MultiSessionJsonRpcServer;
import com.dbx.agent.MetadataListConstraints;
import com.dbx.agent.ObjectInfo;
import com.dbx.agent.ObjectSource;
import com.dbx.agent.QueryPageOptions;
import com.dbx.agent.QueryPageResult;
import com.dbx.agent.QueryResult;
import com.dbx.agent.TableInfo;
import com.dbx.agent.TriggerInfo;
import com.taosdata.jdbc.TSDBDriver;
import com.taosdata.jdbc.rs.RestfulConnection;
import java.nio.charset.StandardCharsets;
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.sql.Timestamp;
import java.sql.Types;
import java.time.format.DateTimeFormatter;
import java.time.format.DateTimeFormatterBuilder;
import java.time.temporal.ChronoField;
import java.util.ArrayList;
import java.util.Collections;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Locale;
import java.util.Map;
import java.util.concurrent.Callable;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
import java.util.concurrent.Future;
import java.util.concurrent.ThreadFactory;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
public final class TDengineAgent extends AbstractJdbcAgent {
private static final long TABLE_CACHE_TTL_MILLIS = 10_000L;
private static final DateTimeFormatter TDENGINE_TIMESTAMP_FORMAT =
new DateTimeFormatterBuilder()
.appendPattern("yyyy-MM-dd HH:mm:ss")
.appendFraction(ChronoField.NANO_OF_SECOND, 3, 9, true)
.toFormatter();
private static final Pattern NUMERIC_PRECISION_PATTERN =
Pattern.compile("(?i)^(decimal|numeric)\\((\\d+)(?:,\\s*\\d+)?\\)");
private static final Pattern NUMERIC_SCALE_PATTERN =
Pattern.compile("(?i)^(decimal|numeric)\\(\\d+,\\s*(\\d+)\\)");
private static final Pattern CHARACTER_LENGTH_PATTERN =
Pattern.compile("(?i)^(binary|nchar|varchar|varbinary)\\((\\d+)\\)");
private static final Pattern COMPOSITE_KEY_PATTERN =
Pattern.compile("(?i)\\bCOMPOSITE\\s+KEY\\b");
private static final Pattern TDENGINE_VERSION_PATTERN =
Pattern.compile("^(\\d+)\\.(\\d+)\\.(\\d+)(?:\\.|$)");
private final Object tableCacheLock = new Object();
private String tableCacheSchema = "";
private long tableCacheTimeMillis;
private List<TableInfo> tableCache = Collections.emptyList();
private Connection restfulStateConnection;
private String restfulOriginalCatalog;
private String restfulOriginalDatabase;
private boolean restInformationSchemaPagingEnabled;
@Override
protected String driverClass() {
return TDengineTransport.WEBSOCKET.driverClass();
}
@Override
protected String buildJdbcUrl(ConnectParams params) {
String connectionString = params.getConnection_string() == null ? "" : params.getConnection_string().trim();
if (!connectionString.isBlank()) {
return TDengineJdbcUrl.sanitizeConnectionString(connectionString);
}
TDengineJdbcUrl.TransportPreference preference = TDengineJdbcUrl.transportPreference(params.getUrl_params());
TDengineTransport transport = preference == TDengineJdbcUrl.TransportPreference.REST
? TDengineTransport.REST
: TDengineTransport.WEBSOCKET;
return TDengineJdbcUrl.from(params, transport);
}
@Override
protected void loadDriver(ConnectParams params) {
}
@Override
protected Connection openConnection(ConnectParams params) throws Exception {
return TDengineConnectionFactory.open(params);
}
@Override
protected void afterConnect(ConnectParams params, Connection connection) {
clearTableCache();
clearRestfulState();
restInformationSchemaPagingEnabled = supportsRestInformationSchemaPaging(connection);
}
@Override
protected void beforePooledConnectionReturn(Connection connection) throws Exception {
if (restfulStateConnection != connection) {
return;
}
try {
restoreRestfulConnectionState(connection, restfulOriginalCatalog, restfulOriginalDatabase);
} finally {
clearRestfulState();
}
}
@Override
protected void afterDisconnect() {
clearTableCache();
clearRestfulState();
restInformationSchemaPagingEnabled = false;
}
@Override
public List<DatabaseInfo> listDatabases() {
return unchecked(() -> {
List<DatabaseInfo> result = new ArrayList<>();
try (java.sql.Statement stmt = requireConnected().createStatement();
ResultSet rs = stmt.executeQuery("SHOW DATABASES")) {
while (rs.next()) {
String name = rs.getString(1);
if (!isSystemDatabase(name)) {
result.add(new DatabaseInfo(name));
}
}
}
return result;
});
}
@Override
public List<String> listSchemas() {
return Collections.emptyList();
}
@Override
public List<TableInfo> listTables(String schema) {
return listTables(schema, MetadataListConstraints.NONE);
}
@Override
public List<TableInfo> listTables(String schema, MetadataListConstraints constraints) {
MetadataListConstraints normalized = MetadataListConstraints.orNone(constraints);
if (!normalized.tableTypeAllowed("TABLE")) {
return Collections.emptyList();
}
if (normalized.hasLimit() && !normalized.hasFilter()) {
if (restInformationSchemaPagingEnabled) {
try {
return listTablesPageFromRestInformationSchema(schema, normalized);
} catch (RuntimeException ignored) {
}
}
return listTablesPageFromShow(schema, normalized);
}
return normalized.filterTables(listTablesFromShow(schema));
}
private List<TableInfo> listTablesPageFromRestInformationSchema(
String schema,
MetadataListConstraints constraints
) {
return unchecked(() -> {
int limit = constraints.getLimit();
int offset = constraints.getOffset() == null ? 0 : constraints.getOffset();
List<TableInfo> result = new ArrayList<>(limit);
TablePageScan stablePage = queryTablesPage(
"SHOW " + quoteQualifiedPrefix(schema) + "STABLES",
"STABLE",
false,
offset,
limit
);
result.addAll(stablePage.tables());
if (result.size() >= limit) {
return result;
}
int tableOffset = Math.max(0, offset - stablePage.scannedRows());
result.addAll(queryInformationSchemaTablePage(
schema,
tableOffset,
limit - result.size()
));
return result;
});
}
private List<TableInfo> listTablesPageFromShow(String schema, MetadataListConstraints constraints) {
return unchecked(() -> {
int limit = constraints.getLimit();
int offset = constraints.getOffset() == null ? 0 : constraints.getOffset();
List<TableInfo> result = new ArrayList<>(limit);
TablePageScan stablePage = queryTablesPage(
"SHOW " + quoteQualifiedPrefix(schema) + "STABLES",
"STABLE",
false,
offset,
limit
);
result.addAll(stablePage.tables());
if (result.size() >= limit) {
return result;
}
int tableOffset = Math.max(0, offset - stablePage.scannedRows());
result.addAll(queryTablesPage(
"SHOW " + quoteQualifiedPrefix(schema) + "TABLES",
"TABLE",
true,
tableOffset,
limit - result.size()
).tables());
return result;
});
}
private List<TableInfo> listTablesFromShow(String schema) {
List<TableInfo> cached = cachedTables(schema);
if (cached != null) {
return cached;
}
return unchecked(() -> {
List<TableInfo> result = new ArrayList<>();
// Connector/J 3.6.3 ignores Statement#setMaxRows. Filtered and
// unbounded callers still need the complete result, so cache that
// scan briefly instead of repeating it for adjacent requests.
result.addAll(queryTables("SHOW " + quoteQualifiedPrefix(schema) + "STABLES", "STABLE", false));
result.addAll(queryTables("SHOW " + quoteQualifiedPrefix(schema) + "TABLES", "TABLE", true));
Map<String, TableInfo> distinct = new LinkedHashMap<>();
for (TableInfo table : result) {
distinct.putIfAbsent(table.getTable_type() + ":" + table.getName(), table);
}
List<TableInfo> sorted = new ArrayList<>(distinct.values());
sortTablesForHierarchy(sorted);
cacheTables(schema, sorted);
return copyTables(sorted);
});
}
@Override
public List<ObjectInfo> listObjects(String schema) {
List<ObjectInfo> result = new ArrayList<>();
for (TableInfo table : listTables(schema)) {
result.add(new ObjectInfo(table.getName(), table.getTable_type(), schema, table.getComment()));
}
return result;
}
@Override
public List<ColumnInfo> getColumns(String schema, String table) {
return unchecked(() -> {
try (java.sql.Statement stmt = requireConnected().createStatement();
ResultSet rs = stmt.executeQuery("DESCRIBE " + qualifiedName(schema, table))) {
return readDescribeColumns(rs);
}
});
}
@Override
public ObjectSource getObjectSource(String schema, String name, String objectType) {
String source = getCreateSql(schema, name, objectType);
if (source.isBlank()) {
source = getTableDdl(schema, name);
}
return new ObjectSource(name, objectType, schema, source);
}
@Override
public String getTableDdl(String schema, String table) {
String source = getCreateSql(schema, table, "STABLE");
if (source.isBlank()) {
source = getCreateSql(schema, table, "TABLE");
}
if (source.isBlank()) {
return super.getTableDdl(schema, table);
}
return source;
}
@Override
public List<IndexInfo> listIndexes(String schema, String table) {
return Collections.emptyList();
}
@Override
public List<ForeignKeyInfo> listForeignKeys(String schema, String table) {
return Collections.emptyList();
}
@Override
public List<TriggerInfo> listTriggers(String schema, String table) {
return Collections.emptyList();
}
@Override
public QueryResult executeQuery(String sql, String schema, ExecuteQueryOptions options) {
QueryResult result = JdbcExecutor.current().execute(
requireConnected(),
sql,
prepareExecutionSchema(schema),
this::setSchemaSQL,
options.getMaxRows(),
options.getFetchSize(),
options.getTimeoutSecs(),
this::resultValue
);
if (mayChangeMetadata(sql)) {
clearTableCache();
}
return result;
}
@Override
public QueryPageResult executeQueryPage(String sql, String schema, QueryPageOptions options) {
return JdbcExecutor.current().executePage(
requireConnected(),
sql,
prepareExecutionSchema(schema),
this::setSchemaSQL,
options,
this::resultValue
);
}
@Override
public QueryPageResult startTableRead(String sql, String schema, QueryPageOptions options) {
return JdbcExecutor.current().startTableRead(
requireConnected(),
sql,
prepareExecutionSchema(schema),
this::setSchemaSQL,
options,
this::resultValue
);
}
@Override
public String setSchemaSQL(String schema) {
return "USE " + quoteIdentifier(schema);
}
@Override
public QueryResult executeTransaction(List<String> statements, String schema) {
QueryResult result = super.executeTransaction(statements, prepareExecutionSchema(schema));
if (statements.stream().anyMatch(TDengineAgent::mayChangeMetadata)) {
clearTableCache();
}
return result;
}
@Override
public QueryResult executeBatch(List<String> statements, String schema) {
QueryResult result = super.executeBatch(statements, prepareExecutionSchema(schema));
if (statements.stream().anyMatch(TDengineAgent::mayChangeMetadata)) {
clearTableCache();
}
return result;
}
private String prepareExecutionSchema(String schema) {
return unchecked(() -> {
Connection connection = requireConnected();
if (schema != null
&& !schema.trim().isEmpty()
&& unwrapConnection(connection, RestfulConnection.class) != null
&& restfulStateConnection != connection) {
restfulStateConnection = connection;
restfulOriginalCatalog = connection.getCatalog();
restfulOriginalDatabase = connection.getClientInfo(TSDBDriver.PROPERTY_KEY_DBNAME);
}
return prepareExecutionSchema(connection, schema);
});
}
static String prepareExecutionSchema(Connection connection, String schema) throws SQLException {
if (unwrapConnection(connection, RestfulConnection.class) == null || schema == null || schema.trim().isEmpty()) {
return schema;
}
String database = schema.trim();
// Connector/J 3.6.3 misparses quoted USE statements and puts the whole SQL in /rest/sql/<db>.
connection.setCatalog(database);
connection.setClientInfo(TSDBDriver.PROPERTY_KEY_DBNAME, database);
return null;
}
static void restoreRestfulConnectionState(Connection connection, String catalog, String database) throws SQLException {
connection.setCatalog(catalog);
if (database == null) {
connection.getClientInfo().remove(TSDBDriver.PROPERTY_KEY_DBNAME);
} else {
connection.setClientInfo(TSDBDriver.PROPERTY_KEY_DBNAME, database);
}
}
private List<TableInfo> queryTables(String sql, String tableType, boolean includesStableName) throws Exception {
List<TableInfo> result = new ArrayList<>();
try (java.sql.Statement stmt = requireConnected().createStatement()) {
try (ResultSet rs = stmt.executeQuery(sql)) {
while (rs.next()) {
result.add(readShowTable(rs, tableType, includesStableName));
}
}
}
return result;
}
private TablePageScan queryTablesPage(
String sql,
String tableType,
boolean includesStableName,
int offset,
int limit
) throws Exception {
List<TableInfo> result = new ArrayList<>(limit);
int scannedRows = 0;
try (java.sql.Statement stmt = requireConnected().createStatement();
ResultSet rs = stmt.executeQuery(sql)) {
while (result.size() < limit && rs.next()) {
scannedRows += 1;
if (scannedRows <= offset) {
continue;
}
result.add(readShowTable(rs, tableType, includesStableName));
}
}
return new TablePageScan(result, scannedRows);
}
private List<TableInfo> queryInformationSchemaTablePage(String database, int offset, int limit) throws Exception {
StringBuilder sql = new StringBuilder(
"SELECT table_name, stable_name FROM information_schema.ins_tables WHERE db_name = ? LIMIT "
).append(limit);
if (offset > 0) {
sql.append(" OFFSET ").append(offset);
}
List<TableInfo> result = new ArrayList<>(limit);
try (java.sql.PreparedStatement stmt = requireConnected().prepareStatement(sql.toString())) {
stmt.setString(1, database);
try (ResultSet rs = stmt.executeQuery()) {
while (rs.next()) {
String parentName = optionalString(rs, 2);
if (parentName != null && parentName.trim().isEmpty()) {
parentName = null;
}
result.add(new TableInfo(rs.getString(1), "TABLE", null, null, parentName));
}
}
}
return result;
}
private static TableInfo readShowTable(ResultSet rs, String tableType, boolean includesStableName) throws Exception {
// SHOW TABLES returns the owning STABLE as its fourth column. It
// is absent for ordinary tables and older servers, where this
// best-effort read simply leaves the table at the root level.
String parentName = includesStableName ? optionalString(rs, 4) : null;
if (parentName != null && parentName.trim().isEmpty()) {
parentName = null;
}
return new TableInfo(rs.getString(1), tableType, null, null, parentName);
}
private record TablePageScan(List<TableInfo> tables, int scannedRows) {
}
private static boolean supportsRestInformationSchemaPaging(Connection connection) {
if (unwrapConnection(connection, RestfulConnection.class) == null) {
return false;
}
try {
return supportsRestInformationSchemaPagingVersion(connection.getMetaData().getDatabaseProductVersion());
} catch (Exception ignored) {
return false;
}
}
static boolean supportsRestInformationSchemaPagingVersion(String version) {
Matcher matcher = TDENGINE_VERSION_PATTERN.matcher(version == null ? "" : version.trim());
if (!matcher.find()) {
return false;
}
int major = Integer.parseInt(matcher.group(1));
int minor = Integer.parseInt(matcher.group(2));
int patch = Integer.parseInt(matcher.group(3));
return major > 3 || (major == 3 && (minor > 3 || (minor == 3 && patch >= 8)));
}
private List<TableInfo> cachedTables(String schema) {
String normalizedSchema = normalizedSchema(schema);
synchronized (tableCacheLock) {
if (cacheFresh(tableCacheTimeMillis) && tableCacheSchema.equals(normalizedSchema)) {
return copyTables(tableCache);
}
}
return null;
}
private void cacheTables(String schema, List<TableInfo> tables) {
synchronized (tableCacheLock) {
tableCacheSchema = normalizedSchema(schema);
tableCache = copyTables(tables);
tableCacheTimeMillis = System.currentTimeMillis();
}
}
private void clearTableCache() {
synchronized (tableCacheLock) {
tableCacheSchema = "";
tableCacheTimeMillis = 0L;
tableCache = Collections.emptyList();
}
}
private void clearRestfulState() {
restfulStateConnection = null;
restfulOriginalCatalog = null;
restfulOriginalDatabase = null;
}
private static boolean cacheFresh(long cachedAtMillis) {
return cachedAtMillis > 0L && System.currentTimeMillis() - cachedAtMillis <= TABLE_CACHE_TTL_MILLIS;
}
private static String normalizedSchema(String schema) {
return schema == null ? "" : schema.trim();
}
private static List<TableInfo> copyTables(List<TableInfo> tables) {
List<TableInfo> copies = new ArrayList<>(tables.size());
for (TableInfo table : tables) {
copies.add(new TableInfo(
table.getName(),
table.getTable_type(),
table.getComment(),
table.getParent_schema(),
table.getParent_name()
));
}
return copies;
}
private static boolean mayChangeMetadata(String sql) {
String normalized = sql == null ? "" : sql.trim().toLowerCase(Locale.ROOT);
return normalized.startsWith("create ")
|| normalized.startsWith("drop ")
|| normalized.startsWith("alter ")
|| normalized.startsWith("rename ")
|| normalized.startsWith("truncate ");
}
static void sortTablesForHierarchy(List<TableInfo> tables) {
tables.sort((left, right) -> {
String leftGroup = hierarchyGroupName(left);
String rightGroup = hierarchyGroupName(right);
int groupCompared = leftGroup.compareTo(rightGroup);
if (groupCompared != 0) {
return groupCompared;
}
boolean leftIsParent = left.getParent_name() == null;
boolean rightIsParent = right.getParent_name() == null;
if (leftIsParent != rightIsParent) {
return leftIsParent ? -1 : 1;
}
return left.getName().toLowerCase(Locale.ROOT).compareTo(right.getName().toLowerCase(Locale.ROOT));
});
}
private static String hierarchyGroupName(TableInfo table) {
String parentName = table.getParent_name();
String groupName = parentName == null || parentName.trim().isEmpty() ? table.getName() : parentName;
return groupName.toLowerCase(Locale.ROOT);
}
static List<ColumnInfo> readDescribeColumns(ResultSet rs) throws Exception {
List<ColumnInfo> result = new ArrayList<>();
int ordinal = 0;
while (rs.next()) {
ordinal += 1;
String name = rs.getString(1);
String dataType = coalesce(rs.getString(2));
String note = optionalString(rs, 4);
boolean isTag = note != null && note.toUpperCase(Locale.ROOT).contains("TAG");
boolean isPrimaryKey = !isTag && (ordinal == 1 || (note != null && COMPOSITE_KEY_PATTERN.matcher(note).find()));
result.add(new ColumnInfo(
name,
dataType,
!isPrimaryKey,
null,
isPrimaryKey,
note,
isTag ? "TAG" : null,
parseNumericPrecision(dataType),
parseNumericScale(dataType),
parseCharacterMaximumLength(dataType)
));
}
return result;
}
private String getCreateSql(String schema, String name, String objectType) {
String showType = switch (objectType.toUpperCase(Locale.ROOT)) {
case "STABLE", "SUPER TABLE", "SUPERTABLE" -> "STABLE";
case "TABLE", "BASE TABLE", "CHILD TABLE" -> "TABLE";
default -> null;
};
if (showType == null) {
return "";
}
try (java.sql.Statement stmt = requireConnected().createStatement();
ResultSet rs = stmt.executeQuery("SHOW CREATE " + showType + " " + qualifiedName(schema, name))) {
if (!rs.next()) {
return "";
}
int columnCount = rs.getMetaData().getColumnCount();
for (int i = 2; i <= columnCount; i++) {
String value = rs.getString(i);
if (value != null && value.toUpperCase(Locale.ROOT).contains("CREATE")) {
return value;
}
}
String value = rs.getString(columnCount);
return value == null ? "" : value;
} catch (Exception e) {
return "";
}
}
@Override
protected Object resultValue(ResultSet rs, int index, int sqlType) {
return unchecked(() -> {
Object value = switch (sqlType) {
case Types.BIGINT -> rs.getLong(index);
case Types.INTEGER, Types.SMALLINT, Types.TINYINT -> rs.getInt(index);
case Types.FLOAT, Types.REAL -> rs.getFloat(index);
case Types.DOUBLE -> rs.getDouble(index);
case Types.DECIMAL, Types.NUMERIC -> rs.getBigDecimal(index);
case Types.BOOLEAN, Types.BIT -> rs.getBoolean(index);
default -> rs.getObject(index);
};
return rs.wasNull() ? null : decodeTdengineValue(value);
});
}
public static Object decodeTdengineValue(Object value) {
if (value instanceof byte[] bytes) {
return new String(bytes, StandardCharsets.UTF_8);
}
if (value instanceof Timestamp timestamp) {
return TDENGINE_TIMESTAMP_FORMAT.format(timestamp.toLocalDateTime());
}
return value;
}
private static String quoteQualifiedPrefix(String schema) {
String trimmed = schema.trim();
return trimmed.isEmpty() ? "" : quoteIdentifier(trimmed) + ".";
}
private static String qualifiedName(String schema, String name) {
String table = quoteIdentifier(name);
String trimmed = schema.trim();
return trimmed.isEmpty() ? table : quoteIdentifier(trimmed) + "." + table;
}
private static String quoteIdentifier(String identifier) {
return "`" + identifier.replace("`", "``") + "`";
}
private static boolean isSystemDatabase(String name) {
if (name == null) {
return false;
}
String normalized = name.trim().toLowerCase(Locale.ROOT);
return "information_schema".equals(normalized) || "performance_schema".equals(normalized);
}
private static Integer parseNumericPrecision(String dataType) {
return parseIntGroup(NUMERIC_PRECISION_PATTERN, dataType, 2);
}
private static Integer parseNumericScale(String dataType) {
return parseIntGroup(NUMERIC_SCALE_PATTERN, dataType, 2);
}
private static Integer parseCharacterMaximumLength(String dataType) {
return parseIntGroup(CHARACTER_LENGTH_PATTERN, dataType, 2);
}
private static Integer parseIntGroup(Pattern pattern, String value, int group) {
Matcher matcher = pattern.matcher(value);
if (!matcher.find()) {
return null;
}
try {
return Integer.valueOf(matcher.group(group));
} catch (NumberFormatException e) {
return null;
}
}
private static String optionalString(ResultSet rs, int index) {
try {
return rs.getString(index);
} catch (Exception e) {
return null;
}
}
private static String coalesce(String value) {
return value == null ? "" : value;
}
public static void main(String[] args) {
new MultiSessionJsonRpcServer(TDengineAgent::new).run();
}
}
final class TDengineJdbcUrl {
enum TransportPreference {
AUTO,
WEBSOCKET,
REST
}
private static final String PARAM_TRANSPORT = "transport";
private static final String PARAM_DBX_TRANSPORT = "dbx.transport";
private TDengineJdbcUrl() {
}
static String from(ConnectParams params) {
TransportPreference preference = transportPreference(params.getUrl_params());
if (preference == TransportPreference.REST) {
return from(params, TDengineTransport.REST);
}
String host = params.getHost().isBlank() ? "localhost" : params.getHost();
int port = params.getPort() > 0 ? params.getPort() : 6041;
String database = params.getDatabase().trim();
String path = database.isBlank() ? "/" : "/" + database;
String query = normalizeQueryString(params.getUrl_params());
String suffix = query.isBlank() ? "" : "?" + query;
return "jdbc:TAOS-WS://" + host + ":" + port + path + suffix;
}
static String from(ConnectParams params, TDengineTransport transport) {
String host = params.getHost().isBlank() ? "localhost" : params.getHost();
int port = params.getPort() > 0 ? params.getPort() : 6041;
String database = params.getDatabase().trim();
String path = database.isBlank() ? "/" : "/" + database;
String query = normalizeQueryString(params.getUrl_params());
String suffix = query.isBlank() ? "" : "?" + query;
return transport.urlPrefix() + host + ":" + port + path + suffix;
}
static String sanitizeConnectionString(String connectionString) {
if (connectionString == null || connectionString.isBlank()) {
return "";
}
int queryIndex = connectionString.indexOf('?');
if (queryIndex < 0) {
return connectionString;
}
String base = connectionString.substring(0, queryIndex);
String rawQuery = connectionString.substring(queryIndex + 1);
int fragmentIndex = rawQuery.indexOf('#');
String fragment = "";
if (fragmentIndex >= 0) {
fragment = rawQuery.substring(fragmentIndex);
rawQuery = rawQuery.substring(0, fragmentIndex);
}
String query = normalizeQueryString(rawQuery);
if (query.isBlank()) {
return base + fragment;
}
return base + "?" + query + fragment;
}
static TransportPreference transportPreference(String rawQuery) {
String query = rawQuery == null ? "" : rawQuery.trim();
if (query.startsWith("?")) {
query = query.substring(1);
}
if (query.isBlank()) {
return TransportPreference.AUTO;
}
String[] parts = query.split("&");
for (String part : parts) {
if (part == null || part.isBlank()) {
continue;
}
int index = part.indexOf('=');
String key = index < 0 ? part.trim() : part.substring(0, index).trim();
if (!PARAM_TRANSPORT.equalsIgnoreCase(key) && !PARAM_DBX_TRANSPORT.equalsIgnoreCase(key)) {
continue;
}
String value = index < 0 ? "" : part.substring(index + 1).trim();
if ("rest".equalsIgnoreCase(value) || "rs".equalsIgnoreCase(value)) {
return TransportPreference.REST;
}
if ("ws".equalsIgnoreCase(value) || "websocket".equalsIgnoreCase(value)) {
return TransportPreference.WEBSOCKET;
}
}
return TransportPreference.AUTO;
}
private static String normalizeQueryString(String rawQuery) {
String query = rawQuery == null ? "" : rawQuery.trim();
if (query.startsWith("?")) {
query = query.substring(1);
}
if (query.isBlank()) {
return "";
}
String[] parts = query.split("&");
List<String> kept = new ArrayList<>();
for (String part : parts) {
if (part == null || part.isBlank()) {
continue;
}
int index = part.indexOf('=');
String key = index < 0 ? part.trim() : part.substring(0, index).trim();
if (PARAM_TRANSPORT.equalsIgnoreCase(key) || PARAM_DBX_TRANSPORT.equalsIgnoreCase(key)) {
continue;
}
kept.add(part);
}
return String.join("&", kept);
}
}
enum TDengineTransport {
WEBSOCKET("jdbc:TAOS-WS://", "com.taosdata.jdbc.ws.WebSocketDriver"),
REST("jdbc:TAOS-RS://", "com.taosdata.jdbc.rs.RestfulDriver");
private final String urlPrefix;
private final String driverClass;
TDengineTransport(String urlPrefix, String driverClass) {
this.urlPrefix = urlPrefix;
this.driverClass = driverClass;
}
String urlPrefix() {
return urlPrefix;
}
String driverClass() {
return driverClass;
}
}
final class TDengineConnectionFactory {
private static final int AUTO_TRANSPORT_ATTEMPT_TIMEOUT_SECONDS = 8;
private TDengineConnectionFactory() {
}
static Connection open(ConnectParams params) throws Exception {
String explicitConnectionString = params.getConnection_string() == null ? "" : params.getConnection_string().trim();
if (!explicitConnectionString.isBlank()) {
String sanitizedConnectionString = TDengineJdbcUrl.sanitizeConnectionString(explicitConnectionString);
Class.forName(driverClassFromConnectionString(sanitizedConnectionString));
return DriverManager.getConnection(sanitizedConnectionString, params.getUsername(), params.getPassword());
}
TDengineJdbcUrl.TransportPreference preference = TDengineJdbcUrl.transportPreference(params.getUrl_params());
TDengineTransport[] candidates = transportsFor(preference);
Exception firstError = null;
for (TDengineTransport transport : candidates) {
try {
Connection connection = preference == TDengineJdbcUrl.TransportPreference.AUTO
? openWithAttemptTimeout(params, transport)
: openDirect(params, transport);
return connection;
} catch (Exception e) {
if (firstError == null) {
firstError = e;
} else {
firstError.addSuppressed(e);
}
}
}
if (firstError != null) {
throw new RuntimeException("Failed to connect TDengine using transports: " + candidateNames(candidates), firstError);
}
throw new IllegalStateException("No TDengine transport available.");
}
private static Connection openDirect(ConnectParams params, TDengineTransport transport) throws Exception {
Class.forName(transport.driverClass());
String url = TDengineJdbcUrl.from(params, transport);
return DriverManager.getConnection(url, params.getUsername(), params.getPassword());
}
private static Connection openWithAttemptTimeout(ConnectParams params, TDengineTransport transport) throws Exception {
String threadName = "tdengine-connect-" + transport.name().toLowerCase(Locale.ROOT);
ThreadFactory factory = runnable -> {
Thread thread = new Thread(runnable, threadName);
thread.setDaemon(true);
return thread;
};
ExecutorService executor = Executors.newSingleThreadExecutor(factory);
try {
Future<Connection> future = executor.submit(new Callable<Connection>() {
@Override
public Connection call() throws Exception {
return openDirect(params, transport);
}
});
return future.get(AUTO_TRANSPORT_ATTEMPT_TIMEOUT_SECONDS, TimeUnit.SECONDS);
} catch (TimeoutException e) {
throw new RuntimeException(
"TDengine " + transport.name().toLowerCase(Locale.ROOT)
+ " transport connect timed out after " + AUTO_TRANSPORT_ATTEMPT_TIMEOUT_SECONDS + "s",
e
);
} catch (InterruptedException e) {
Thread.currentThread().interrupt();
throw new RuntimeException("Interrupted while connecting TDengine via " + transport.name().toLowerCase(Locale.ROOT), e);
} catch (ExecutionException e) {
Throwable cause = e.getCause();
if (cause instanceof Exception exception) {
throw exception;
}
throw new RuntimeException(cause);
} finally {
executor.shutdownNow();
}
}
private static TDengineTransport[] transportsFor(TDengineJdbcUrl.TransportPreference preference) {
return switch (preference) {
case REST -> new TDengineTransport[] {TDengineTransport.REST};
case WEBSOCKET -> new TDengineTransport[] {TDengineTransport.WEBSOCKET};
case AUTO -> new TDengineTransport[] {TDengineTransport.WEBSOCKET, TDengineTransport.REST};
};
}
private static String candidateNames(TDengineTransport[] candidates) {
List<String> names = new ArrayList<>();
for (TDengineTransport candidate : candidates) {
names.add(candidate.name().toLowerCase(Locale.ROOT));
}
return String.join(" -> ", names);
}
private static String driverClassFromConnectionString(String connectionString) {
if (connectionString.regionMatches(true, 0, TDengineTransport.REST.urlPrefix(), 0, TDengineTransport.REST.urlPrefix().length())) {
return TDengineTransport.REST.driverClass();
}
if (connectionString.regionMatches(true, 0, TDengineTransport.WEBSOCKET.urlPrefix(), 0, TDengineTransport.WEBSOCKET.urlPrefix().length())) {
return TDengineTransport.WEBSOCKET.driverClass();
}
return TDengineTransport.WEBSOCKET.driverClass();
}
}
+279
View File
@@ -0,0 +1,279 @@
use serde::{Deserialize, Deserializer, Serialize};
use serde_json::Value;
pub const PROTOCOL_VERSION: u32 = 2;
pub const LEGACY_SESSION_ID: &str = "__legacy__";
pub const DEFAULT_MAX_ROWS: usize = 10_000;
pub const MAX_AGENT_SESSIONS: usize = 256;
pub const MAX_CONCURRENT_REQUESTS: usize = 64;
#[derive(Debug, Deserialize)]
pub struct RpcRequest {
#[serde(default)]
pub id: Value,
pub method: String,
#[serde(default)]
pub params: Value,
}
#[derive(Debug, Serialize)]
pub struct RpcResponse {
pub jsonrpc: &'static str,
pub id: Value,
#[serde(skip_serializing_if = "Option::is_none")]
pub result: Option<Value>,
#[serde(skip_serializing_if = "Option::is_none")]
pub error: Option<RpcError>,
}
#[derive(Debug, Serialize)]
pub struct RpcError {
pub code: i32,
pub message: String,
#[serde(skip_serializing_if = "Option::is_none")]
pub data: Option<StructuredError>,
}
#[derive(Debug, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct StructuredError {
pub category: &'static str,
pub retryable: bool,
pub session_disposition: &'static str,
pub stage: &'static str,
pub contract_version: u32,
pub operation_outcome: &'static str,
#[serde(skip_serializing_if = "Option::is_none")]
pub agent_session_id: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub exception_class: Option<String>,
}
#[derive(Debug, Clone, Default, Deserialize)]
pub struct ConnectParams {
#[serde(default)]
pub host: String,
#[serde(default)]
pub port: u16,
#[serde(default)]
pub database: String,
#[serde(default)]
pub username: String,
#[serde(default)]
pub password: String,
#[serde(default)]
pub url_params: String,
#[serde(default)]
pub connection_string: String,
#[serde(default)]
pub ssl: bool,
#[serde(default)]
pub ca_cert_path: String,
#[serde(default)]
pub client_cert_path: String,
#[serde(default)]
pub client_key_path: String,
#[serde(default)]
pub connect_timeout_secs: u64,
}
#[derive(Debug, Clone, Default, Deserialize)]
pub struct QueryOptions {
#[serde(default)]
pub sql: String,
#[serde(default)]
pub database: String,
#[serde(default)]
pub schema: String,
#[serde(default, rename = "maxRows")]
pub max_rows: usize,
#[serde(default, rename = "fetchSize")]
pub fetch_size: usize,
#[serde(default, rename = "timeoutSecs")]
pub timeout_secs: u64,
#[serde(default, rename = "pageSize")]
pub page_size: usize,
}
#[derive(Debug, Clone, Default, Deserialize)]
pub struct MetadataListConstraints {
#[serde(default)]
pub filter: String,
#[serde(default)]
pub limit: usize,
#[serde(default)]
pub offset: usize,
#[serde(default)]
pub object_types: Vec<String>,
}
#[derive(Debug, Clone, Default, Deserialize)]
pub struct CompletionAssistantRequest {
#[serde(default)]
pub database: String,
#[serde(default, deserialize_with = "deserialize_null_default")]
pub schema: String,
#[serde(default)]
pub object_kinds: Vec<String>,
#[serde(default)]
pub mask: String,
#[serde(default)]
pub case_sensitive: bool,
#[serde(default)]
pub global_search: bool,
#[serde(default, deserialize_with = "deserialize_null_default")]
pub max_results: usize,
#[serde(default, deserialize_with = "deserialize_null_default")]
pub parent_schema: String,
#[serde(default, deserialize_with = "deserialize_null_default")]
pub parent_name: String,
#[serde(default, deserialize_with = "deserialize_null_default")]
pub match_mode: String,
}
fn deserialize_null_default<'de, D, T>(deserializer: D) -> Result<T, D::Error>
where
D: Deserializer<'de>,
T: Deserialize<'de> + Default,
{
Ok(Option::<T>::deserialize(deserializer)?.unwrap_or_default())
}
#[derive(Debug, Serialize)]
pub struct HandshakeResult {
#[serde(rename = "protocolVersion")]
pub protocol_version: u32,
#[serde(rename = "agentProtocolVersion")]
pub agent_protocol_version: u32,
pub capabilities: Vec<&'static str>,
}
#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
pub struct DatabaseInfo {
pub name: String,
}
#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
pub struct TableInfo {
pub name: String,
pub table_type: String,
pub comment: Option<String>,
pub parent_schema: Option<String>,
pub parent_name: Option<String>,
}
#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
pub struct ObjectInfo {
pub name: String,
pub object_type: String,
pub schema: String,
pub comment: Option<String>,
}
#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
pub struct ColumnInfo {
pub name: String,
pub data_type: String,
pub is_nullable: bool,
pub column_default: Option<String>,
pub is_primary_key: bool,
pub extra: Option<String>,
pub comment: Option<String>,
pub numeric_precision: Option<u32>,
pub numeric_scale: Option<u32>,
pub character_maximum_length: Option<u32>,
}
#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
pub struct ObjectSource {
pub name: String,
pub object_type: String,
pub schema: String,
pub source: String,
pub editable: bool,
}
#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
pub struct CompletionAssistantCandidate {
pub name: String,
pub kind: String,
pub database: Option<String>,
pub schema: Option<String>,
pub parent_schema: Option<String>,
pub parent_name: Option<String>,
pub comment: Option<String>,
pub data_type: Option<String>,
}
#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
pub struct CompletionAssistantResponse {
pub candidates: Vec<CompletionAssistantCandidate>,
pub incomplete: bool,
pub fallback_used: bool,
}
#[derive(Debug, Clone, Default, Serialize, PartialEq)]
pub struct QueryResult {
pub columns: Vec<String>,
pub column_types: Vec<String>,
pub rows: Vec<Vec<Value>>,
pub affected_rows: i64,
pub execution_time_ms: i64,
pub truncated: bool,
}
#[derive(Debug, Clone, Default, Serialize, PartialEq)]
pub struct QueryPageResult {
pub columns: Vec<String>,
pub column_types: Vec<String>,
pub rows: Vec<Vec<Value>>,
pub affected_rows: i64,
pub execution_time_ms: i64,
pub truncated: bool,
pub session_id: Option<String>,
pub has_more: bool,
}
#[derive(Debug, Clone, Default, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct DatabaseConnectionInfo {
pub product_name: Option<String>,
pub product_version: Option<String>,
pub current_database: Option<String>,
pub driver_name: Option<String>,
pub driver_version: Option<String>,
pub unquoted_identifier_case: Option<&'static str>,
pub quoted_identifier_case: Option<&'static str>,
}
#[derive(Debug, Clone, Default, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct AgentConnectionInfo {
pub identifier_quote: String,
pub compatibility_mode: Option<String>,
pub database_info: Option<DatabaseConnectionInfo>,
}
pub const TDENGINE_DATA_TYPES: &[&str] = &[
"TIMESTAMP",
"BOOL",
"TINYINT",
"SMALLINT",
"INT",
"BIGINT",
"TINYINT UNSIGNED",
"SMALLINT UNSIGNED",
"INT UNSIGNED",
"BIGINT UNSIGNED",
"FLOAT",
"DOUBLE",
"BINARY",
"VARCHAR",
"NCHAR",
"JSON",
"VARBINARY",
"GEOMETRY",
"DECIMAL",
"BLOB",
"MEDIUMBLOB",
];
+662
View File
@@ -0,0 +1,662 @@
use std::collections::HashMap;
use std::sync::atomic::{AtomicU64, Ordering};
use std::sync::{Arc, Mutex as StdMutex};
use anyhow::{anyhow, bail, Context, Result};
use serde::de::DeserializeOwned;
use serde_json::{json, Value};
use tokio::io::{AsyncBufReadExt, AsyncWriteExt, BufReader};
use tokio::sync::{mpsc, Mutex, OwnedSemaphorePermit, RwLock, Semaphore};
use tokio::task::JoinSet;
use tokio_util::sync::CancellationToken;
use crate::driver::TdengineDriver;
use crate::model::{
ConnectParams, HandshakeResult, RpcError, RpcRequest, RpcResponse, StructuredError, LEGACY_SESSION_ID,
MAX_AGENT_SESSIONS, MAX_CONCURRENT_REQUESTS, PROTOCOL_VERSION,
};
struct RuntimeServer {
sessions: RwLock<HashMap<String, Arc<AgentSession>>>,
session_slots: Arc<Semaphore>,
request_slots: Arc<Semaphore>,
}
struct AgentSession {
driver: Mutex<TdengineDriver>,
active: StdMutex<Option<ActiveOperation>>,
next_operation_id: AtomicU64,
_slot: OwnedSemaphorePermit,
}
struct ActiveOperation {
id: u64,
token: CancellationToken,
}
struct OperationGuard<'a> {
session: &'a AgentSession,
id: u64,
}
impl Drop for OperationGuard<'_> {
fn drop(&mut self) {
let mut active = self.session.active.lock().expect("active operation lock poisoned");
if active.as_ref().is_some_and(|operation| operation.id == self.id) {
*active = None;
}
}
}
impl AgentSession {
fn begin_operation(&self) -> (CancellationToken, OperationGuard<'_>) {
let id = self.next_operation_id.fetch_add(1, Ordering::Relaxed);
let token = CancellationToken::new();
*self.active.lock().expect("active operation lock poisoned") =
Some(ActiveOperation { id, token: token.clone() });
(token, OperationGuard { session: self, id })
}
fn cancel(&self) {
if let Some(operation) = self.active.lock().expect("active operation lock poisoned").as_ref() {
operation.token.cancel();
}
}
}
pub async fn run() -> Result<()> {
let runtime = Arc::new(RuntimeServer::new());
let (responses, mut response_rx) = mpsc::unbounded_channel::<RpcResponse>();
let writer = tokio::spawn(async move {
let mut stdout = tokio::io::stdout();
stdout.write_all(b"{\"ready\":true}\n").await?;
stdout.flush().await?;
while let Some(response) = response_rx.recv().await {
let line = serde_json::to_vec(&response)?;
stdout.write_all(&line).await?;
stdout.write_all(b"\n").await?;
stdout.flush().await?;
}
Ok::<(), anyhow::Error>(())
});
let mut lines = BufReader::new(tokio::io::stdin()).lines();
let mut requests = JoinSet::new();
while let Some(line) = lines.next_line().await? {
while requests.try_join_next().is_some() {}
let line = line.trim();
if line.is_empty() {
continue;
}
let parsed = serde_json::from_str::<RpcRequest>(line);
if parsed.as_ref().is_ok_and(|request| request.method == "shutdown") {
let response = match parsed {
Ok(request) => handle_request(runtime.clone(), request).await,
Err(error) => error_response(Value::Null, "request", None, error.into()),
};
responses.send(response).map_err(|_| anyhow!("TDengine response writer stopped"))?;
while requests.join_next().await.is_some() {}
break;
}
let request_permit = if parsed.as_ref().is_ok_and(|request| is_capacity_exempt(&request.method)) {
None
} else {
match runtime.request_slots.clone().try_acquire_owned() {
Ok(permit) => Some(permit),
Err(_) => {
let response = match parsed {
Ok(request) => error_response(
if request.id.is_null() { json!(1) } else { request.id },
&request.method,
session_id(&request.params),
anyhow!("agent request capacity is temporarily exhausted"),
),
Err(error) => error_response(Value::Null, "request", None, error.into()),
};
responses.send(response).map_err(|_| anyhow!("TDengine response writer stopped"))?;
continue;
}
}
};
let runtime = runtime.clone();
let responses = responses.clone();
requests.spawn(async move {
let _request_permit = request_permit;
let response = match parsed {
Ok(request) => handle_request(runtime, request).await,
Err(error) => error_response(Value::Null, "request", None, error.into()),
};
let _ = responses.send(response);
});
}
runtime.close_all_sessions().await;
while requests.join_next().await.is_some() {}
drop(responses);
writer.await.context("TDengine response writer task failed")??;
Ok(())
}
async fn handle_request(runtime: Arc<RuntimeServer>, request: RpcRequest) -> RpcResponse {
let id = if request.id.is_null() { json!(1) } else { request.id.clone() };
let session_id = session_id(&request.params);
match runtime.dispatch(&request.method, request.params).await {
Ok(result) => RpcResponse { jsonrpc: "2.0", id, result: Some(result), error: None },
Err(error) => error_response(id, &request.method, session_id, error),
}
}
impl RuntimeServer {
fn new() -> Self {
Self {
sessions: RwLock::new(HashMap::new()),
session_slots: Arc::new(Semaphore::new(MAX_AGENT_SESSIONS)),
request_slots: Arc::new(Semaphore::new(MAX_CONCURRENT_REQUESTS)),
}
}
async fn dispatch(&self, method: &str, params: Value) -> Result<Value> {
match method {
"handshake" => serialize(HandshakeResult {
protocol_version: PROTOCOL_VERSION,
agent_protocol_version: PROTOCOL_VERSION,
capabilities: vec![
"connect",
"test_connection",
"metadata",
"query",
"paged_query",
"transaction",
"ddl",
"multi_session",
"structured_error_v1",
],
}),
"open_session" => {
let id = required_string(&params, "agentSessionId")?;
let connect = decode::<ConnectParams>(&params)?;
self.open_session(&id, connect).await?;
Ok(json!({"ok": true}))
}
"close_session" => {
self.close_session(&required_string(&params, "agentSessionId")?).await?;
Ok(json!({"ok": true}))
}
"validate_session" => {
let session = self.session(&required_string(&params, "agentSessionId")?).await?;
let driver = session.driver.lock().await;
let (token, _operation) = session.begin_operation();
driver.validate_connection(&token).await?;
Ok(json!({"ok": true}))
}
"cancel_session" => {
self.session(&required_string(&params, "agentSessionId")?).await?.cancel();
Ok(json!({"ok": true}))
}
"test_connection" => {
let database_info = TdengineDriver::test_connection(decode::<ConnectParams>(&params)?).await?;
Ok(json!({"ok": true, "databaseInfo": database_info}))
}
"connect" => {
self.close_session(LEGACY_SESSION_ID).await?;
self.open_session(LEGACY_SESSION_ID, decode::<ConnectParams>(&params)?).await?;
Ok(json!({"ok": true}))
}
"disconnect" => {
self.close_session(LEGACY_SESSION_ID).await?;
Ok(json!({"ok": true}))
}
"shutdown" => {
self.close_all_sessions().await;
Ok(json!({"ok": true}))
}
_ => {
if !is_driver_method(method) {
bail!("unknown method: {method}");
}
let id = session_id(&params).unwrap_or_else(|| LEGACY_SESSION_ID.to_string());
let session = self.session(&id).await?;
let mut driver = session.driver.lock().await;
let (token, _operation) = session.begin_operation();
dispatch_driver(&mut driver, method, &params, &token).await
}
}
}
async fn open_session(&self, id: &str, params: ConnectParams) -> Result<()> {
if id.trim().is_empty() {
bail!("agentSessionId is required");
}
{
let sessions = self.sessions.read().await;
if sessions.contains_key(id) {
bail!("agent session already exists: {id}");
}
}
let slot = self
.session_slots
.clone()
.try_acquire_owned()
.map_err(|_| anyhow!("agent session limit reached: {MAX_AGENT_SESSIONS}"))?;
let mut driver = TdengineDriver::new();
driver.connect(params).await?;
let session = Arc::new(AgentSession {
driver: Mutex::new(driver),
active: StdMutex::new(None),
next_operation_id: AtomicU64::new(1),
_slot: slot,
});
let mut sessions = self.sessions.write().await;
if sessions.contains_key(id) {
bail!("agent session already exists: {id}");
}
sessions.insert(id.to_string(), session);
Ok(())
}
async fn session(&self, id: &str) -> Result<Arc<AgentSession>> {
self.sessions.read().await.get(id).cloned().ok_or_else(|| anyhow!("agent session not found: {id}"))
}
async fn close_session(&self, id: &str) -> Result<()> {
let session = self.sessions.write().await.remove(id);
let Some(session) = session else {
return Ok(());
};
session.cancel();
session.driver.lock().await.disconnect().await;
Ok(())
}
async fn close_all_sessions(&self) {
let sessions = {
let mut sessions = self.sessions.write().await;
std::mem::take(&mut *sessions)
};
for (_, session) in sessions {
session.cancel();
session.driver.lock().await.disconnect().await;
}
}
}
async fn dispatch_driver(
driver: &mut TdengineDriver,
method: &str,
params: &Value,
token: &CancellationToken,
) -> Result<Value> {
let scope = database_scope(params);
match method {
"validate_connection" => {
driver.validate_connection(token).await?;
Ok(json!({"ok": true}))
}
"connection_info" => serialize(driver.connection_info()?),
"list_databases" => serialize(driver.list_databases(token).await?),
"list_schemas" => serialize(driver.list_schemas()),
"list_tables" => serialize(driver.list_tables(&scope, decode(params)?, token).await?),
"get_table_comment" => serialize(driver.get_table_comment(&scope, &required_string(params, "table")?).await?),
"list_objects" => serialize(driver.list_objects(&scope, decode(params)?, token).await?),
"list_data_types" => serialize(driver.list_data_types()),
"completion_assistant_search_v1" => {
serialize(driver.completion_assistant_search(decode(params)?, token).await?)
}
"get_columns" => serialize(driver.get_columns(&scope, &required_string(params, "table")?, token).await?),
"list_indexes" | "list_foreign_keys" | "list_triggers" | "list_constraints" | "list_partitions"
| "list_subpartitions" => Ok(json!([])),
"get_object_source" => serialize(
driver
.get_object_source(
&scope,
&required_string(params, "name")?,
&required_string(params, "object_type")?,
token,
)
.await?,
),
"get_table_ddl" => serialize(driver.get_table_ddl(&scope, &required_string(params, "table")?, token).await?),
"get_explain_info" => Ok(json!({
"plan": driver
.get_explain_info(
&required_string(params, "sql")?,
token,
optional_u64(params, "timeoutSecs").unwrap_or(0),
)
.await?,
"has_actual_stats": false,
})),
"execute_query" => serialize(driver.execute_query(decode(params)?, token).await?),
"execute_query_page" | "start_table_read" => {
serialize(driver.execute_query_page(decode(params)?, token).await?)
}
"fetch_query_page" | "fetch_table_read_page" => serialize(
driver
.fetch_query_page(
&required_string(params, "sessionId")?,
optional_usize(params, "pageSize").unwrap_or(100),
optional_u64(params, "timeoutSecs").unwrap_or(0),
token,
)
.await?,
),
"close_query_session" | "close_table_read_session" => {
serialize(driver.close_query_session(&required_string(params, "sessionId")?))
}
"execute_transaction" | "execute_batch" => serialize(
driver
.execute_statements(
string_array(params, "statements")?,
&scope,
optional_u64(params, "timeoutSecs").unwrap_or(0),
token,
)
.await?,
),
"disconnect" => {
driver.disconnect().await;
Ok(json!({"ok": true}))
}
"shutdown" => {
driver.disconnect().await;
Ok(json!({"ok": true}))
}
_ => bail!("unknown method: {method}"),
}
}
fn decode<T: DeserializeOwned>(params: &Value) -> Result<T> {
serde_json::from_value(params.clone()).with_context(|| "invalid TDengine agent request parameters")
}
fn serialize<T: serde::Serialize>(value: T) -> Result<Value> {
serde_json::to_value(value).map_err(anyhow::Error::from)
}
fn required_string(params: &Value, key: &str) -> Result<String> {
params
.get(key)
.and_then(Value::as_str)
.map(str::to_string)
.filter(|value| !value.trim().is_empty())
.ok_or_else(|| anyhow!("{key} is required"))
}
fn optional_string(params: &Value, key: &str) -> String {
params.get(key).and_then(Value::as_str).unwrap_or_default().to_string()
}
fn optional_usize(params: &Value, key: &str) -> Option<usize> {
params.get(key).and_then(Value::as_u64).and_then(|value| usize::try_from(value).ok())
}
fn optional_u64(params: &Value, key: &str) -> Option<u64> {
params.get(key).and_then(Value::as_u64)
}
fn string_array(params: &Value, key: &str) -> Result<Vec<String>> {
params
.get(key)
.cloned()
.ok_or_else(|| anyhow!("{key} is required"))
.and_then(|value| serde_json::from_value(value).map_err(anyhow::Error::from))
}
fn database_scope(params: &Value) -> String {
let schema = optional_string(params, "schema");
if schema.trim().is_empty() {
optional_string(params, "database")
} else {
schema
}
}
fn session_id(params: &Value) -> Option<String> {
params.get("agentSessionId").and_then(Value::as_str).map(str::to_string)
}
fn is_driver_method(method: &str) -> bool {
matches!(
method,
"validate_connection"
| "connection_info"
| "list_databases"
| "list_schemas"
| "list_tables"
| "get_table_comment"
| "list_objects"
| "list_data_types"
| "completion_assistant_search_v1"
| "get_columns"
| "list_indexes"
| "list_foreign_keys"
| "list_triggers"
| "list_constraints"
| "list_partitions"
| "list_subpartitions"
| "get_object_source"
| "get_table_ddl"
| "get_explain_info"
| "execute_query"
| "execute_query_page"
| "start_table_read"
| "fetch_query_page"
| "fetch_table_read_page"
| "close_query_session"
| "close_table_read_session"
| "execute_transaction"
| "execute_batch"
)
}
fn is_capacity_exempt(method: &str) -> bool {
matches!(method, "handshake" | "cancel_session" | "close_session" | "disconnect")
}
fn error_response(id: Value, method: &str, session_id: Option<String>, error: anyhow::Error) -> RpcResponse {
let message = format!("{error:#}");
let lower = message.to_ascii_lowercase();
let stage = error_stage(method);
let (category, retryable, session_disposition) = if lower.contains("cancel") {
("canceled", false, "quarantine")
} else if lower.contains("timed out") || lower.contains("timeout") {
("timeout", false, "quarantine")
} else if lower.contains("memory exhausted")
|| lower.contains("resource exhausted")
|| lower.contains("session limit reached")
|| lower.contains("request capacity")
{
("resource", true, "keep")
} else if lower.contains("agent session not found")
|| lower.contains("query session not found")
|| lower.contains("agent session already exists")
|| lower.contains("unknown method")
|| lower.contains("invalid tdengine agent request parameters")
|| lower.contains(" is required")
{
("protocol", false, "keep")
} else if stage == "connect" || stage == "validate" || lower.contains("connection") || lower.contains("websocket") {
(
"connection",
stage == "connect" || stage == "validate",
if stage == "connect" { "keep" } else { "quarantine" },
)
} else if matches!(stage, "execute" | "fetch") {
("sql", false, "keep")
} else {
("protocol", false, "keep")
};
RpcResponse {
jsonrpc: "2.0",
id,
result: None,
error: Some(RpcError {
code: -1,
message,
data: Some(StructuredError {
category,
retryable,
session_disposition,
stage,
contract_version: 1,
operation_outcome: if matches!(stage, "request" | "connect" | "validate") {
"not_started"
} else {
"unknown"
},
agent_session_id: session_id,
exception_class: Some("dbx_tdengine_driver::Error".into()),
}),
}),
}
}
fn error_stage(method: &str) -> &'static str {
match method {
"request" | "handshake" => "request",
"connect" | "open_session" | "test_connection" => "connect",
"validate_connection" | "validate_session" => "validate",
"cancel_session" => "cancel",
"close_session" | "disconnect" | "close_query_session" | "close_table_read_session" | "shutdown" => "close",
"fetch_query_page" | "fetch_table_read_page" => "fetch",
_ => "execute",
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn structured_errors_keep_stage_and_outcome_consistent() {
let response = error_response(json!(1), "open_session", Some("s1".into()), anyhow!("connection refused"));
let data = response.error.unwrap().data.unwrap();
assert_eq!(data.category, "connection");
assert_eq!(data.stage, "connect");
assert_eq!(data.operation_outcome, "not_started");
assert_eq!(data.agent_session_id.as_deref(), Some("s1"));
}
#[test]
fn classifies_tdengine_execution_failures_as_sql_errors() {
let response = error_response(json!(1), "execute_query", Some("s1".into()), anyhow!("invalid function"));
let data = response.error.unwrap().data.unwrap();
assert_eq!(data.category, "sql");
assert_eq!(data.stage, "execute");
assert_eq!(data.operation_outcome, "unknown");
}
#[test]
fn keeps_invalid_request_parameters_as_protocol_errors() {
let response = error_response(
json!(1),
"execute_query",
Some("s1".into()),
anyhow!("invalid TDengine agent request parameters"),
);
assert_eq!(response.error.unwrap().data.unwrap().category, "protocol");
}
#[test]
fn keeps_missing_query_sessions_as_protocol_errors() {
let response =
error_response(json!(1), "fetch_query_page", Some("s1".into()), anyhow!("query session not found"));
let data = response.error.unwrap().data.unwrap();
assert_eq!(data.category, "protocol");
assert_eq!(data.stage, "fetch");
}
#[test]
fn quarantines_connections_lost_during_execution() {
let response = error_response(json!(1), "execute_query", Some("s1".into()), anyhow!("connection reset"));
let data = response.error.unwrap().data.unwrap();
assert_eq!(data.category, "connection");
assert_eq!(data.session_disposition, "quarantine");
assert!(!data.retryable);
}
#[test]
fn tdengine_uses_database_when_schema_is_empty() {
assert_eq!(database_scope(&json!({"database": "power", "schema": ""})), "power");
assert_eq!(database_scope(&json!({"database": "power", "schema": "metrics"})), "metrics");
}
#[test]
fn metadata_constraints_ignore_protocol_session_fields() {
let constraints: crate::model::MetadataListConstraints = decode(&json!({
"agentSessionId": "session-1",
"filter": "meter",
"limit": 10,
}))
.unwrap();
assert_eq!(constraints.filter, "meter");
assert_eq!(constraints.limit, 10);
}
#[test]
fn query_options_accept_protocol_camel_case_fields() {
let options: crate::model::QueryOptions =
decode(&json!({"sql": "SELECT 1", "pageSize": 25, "maxRows": 100})).unwrap();
assert_eq!(options.page_size, 25);
assert_eq!(options.max_rows, 100);
}
#[test]
fn completion_request_accepts_null_optional_fields() {
let request: crate::model::CompletionAssistantRequest = decode(&json!({
"connection_id": "connection-1",
"database": "power",
"schema": null,
"object_kinds": ["table"],
"max_results": null,
"parent_schema": null,
"parent_name": null,
"match_mode": null,
}))
.unwrap();
assert_eq!(request.schema, "");
assert_eq!(request.max_results, 0);
assert_eq!(request.parent_schema, "");
assert_eq!(request.parent_name, "");
assert_eq!(request.match_mode, "");
}
#[test]
fn cancel_session_cancels_the_active_operation() {
let slot = Arc::new(Semaphore::new(1)).try_acquire_owned().unwrap();
let session = AgentSession {
driver: Mutex::new(TdengineDriver::new()),
active: StdMutex::new(None),
next_operation_id: AtomicU64::new(1),
_slot: slot,
};
let (token, operation) = session.begin_operation();
session.cancel();
assert!(token.is_cancelled());
drop(operation);
assert!(session.active.lock().unwrap().is_none());
}
#[test]
fn session_slots_bound_connects_in_flight_and_open_sessions() {
let runtime = RuntimeServer::new();
let permits = (0..MAX_AGENT_SESSIONS)
.map(|_| runtime.session_slots.clone().try_acquire_owned().unwrap())
.collect::<Vec<_>>();
assert!(runtime.session_slots.clone().try_acquire_owned().is_err());
drop(permits);
assert!(runtime.session_slots.clone().try_acquire_owned().is_ok());
}
#[test]
fn request_slots_bound_non_control_work_without_blocking_cancellation() {
let runtime = RuntimeServer::new();
let permits = (0..MAX_CONCURRENT_REQUESTS)
.map(|_| runtime.request_slots.clone().try_acquire_owned().unwrap())
.collect::<Vec<_>>();
assert!(runtime.request_slots.clone().try_acquire_owned().is_err());
assert!(is_capacity_exempt("cancel_session"));
assert!(is_capacity_exempt("close_session"));
assert!(!is_capacity_exempt("execute_query"));
drop(permits);
}
}
@@ -1,178 +0,0 @@
package com.dbx.agent.tdengine;
import com.dbx.agent.JsonRpcServer;
import com.dbx.agent.test.TestSupport;
import org.junit.jupiter.api.Test;
import java.lang.reflect.InvocationHandler;
import java.lang.reflect.Method;
import java.lang.reflect.Proxy;
import java.nio.charset.StandardCharsets;
import java.sql.Connection;
import java.sql.ResultSet;
import java.sql.ResultSetMetaData;
import java.sql.Statement;
import java.sql.Types;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertTrue;
class TDengineAgentPagingTest {
@Test
void executeQueryPageDecodesBinaryVarcharValuesAsStrings() {
TDengineAgent agent = new TDengineAgent();
TestSupport.setPrivateConnection(agent, binaryVarcharConnection());
JsonRpcServer server = new JsonRpcServer(agent);
String response = handleRequest(server, """
{
"jsonrpc": "2.0",
"id": 1,
"method": "execute_query_page",
"params": {
"sql": "SELECT v FROM sample",
"schema": "power",
"pageSize": 100
}
}
""");
assertFalse(response.contains("\"error\""), response);
assertTrue(response.contains("\"hello\""), response);
assertFalse(response.contains("[104,101,108,108,111]"), response);
}
private static Connection binaryVarcharConnection() {
Statement statement = binaryVarcharStatement();
return proxy(Connection.class, (method, args) -> {
String name = method.getName();
if ("createStatement".equals(name)) {
return statement;
}
if ("getAutoCommit".equals(name)) {
return true;
}
if ("setAutoCommit".equals(name) || "commit".equals(name) || "rollback".equals(name) || "close".equals(name)) {
return null;
}
if ("isClosed".equals(name)) {
return false;
}
return defaultValue(method.getReturnType());
});
}
private static Statement binaryVarcharStatement() {
ResultSet resultSet = binaryVarcharResultSet();
return proxy(Statement.class, (method, args) -> {
String name = method.getName();
if ("execute".equals(name)) {
return true;
}
if ("getResultSet".equals(name)) {
return resultSet;
}
if ("getUpdateCount".equals(name)) {
return 0;
}
if ("setMaxRows".equals(name) || "setFetchSize".equals(name) || "close".equals(name)) {
return null;
}
return defaultValue(method.getReturnType());
});
}
private static ResultSet binaryVarcharResultSet() {
final int[] index = {-1};
ResultSetMetaData metadata = binaryVarcharMetadata();
byte[] value = "hello".getBytes(StandardCharsets.UTF_8);
return proxy(ResultSet.class, (method, args) -> {
String name = method.getName();
if ("next".equals(name)) {
index[0] += 1;
return index[0] == 0;
}
if ("getMetaData".equals(name)) {
return metadata;
}
if ("getObject".equals(name)) {
return value;
}
if ("wasNull".equals(name)) {
return false;
}
if ("close".equals(name)) {
return null;
}
return defaultValue(method.getReturnType());
});
}
private static ResultSetMetaData binaryVarcharMetadata() {
return proxy(ResultSetMetaData.class, (method, args) -> {
String name = method.getName();
if ("getColumnCount".equals(name)) {
return 1;
}
if ("getColumnLabel".equals(name)) {
return "v";
}
if ("getColumnType".equals(name)) {
return Types.VARCHAR;
}
return defaultValue(method.getReturnType());
});
}
private static String handleRequest(JsonRpcServer server, String request) {
try {
Method method = JsonRpcServer.class.getDeclaredMethod("handleRequest", String.class);
method.setAccessible(true);
return (String) method.invoke(server, request);
} catch (Exception e) {
throw new RuntimeException(e);
}
}
private static <T> T proxy(Class<T> type, MethodHandler handler) {
InvocationHandler invocationHandler = new InvocationHandler() {
@Override
public Object invoke(Object proxy, Method method, Object[] args) {
return handler.handle(method, args);
}
};
return type.cast(Proxy.newProxyInstance(type.getClassLoader(), new Class<?>[]{type}, invocationHandler));
}
private static Object defaultValue(Class<?> type) {
if (Boolean.TYPE.equals(type)) {
return false;
}
if (Byte.TYPE.equals(type)) {
return (byte) 0;
}
if (Short.TYPE.equals(type)) {
return (short) 0;
}
if (Integer.TYPE.equals(type)) {
return 0;
}
if (Long.TYPE.equals(type)) {
return 0L;
}
if (Float.TYPE.equals(type)) {
return 0f;
}
if (Double.TYPE.equals(type)) {
return 0.0d;
}
if (Character.TYPE.equals(type)) {
return '\0';
}
return null;
}
private interface MethodHandler {
Object handle(Method method, Object[] args);
}
}
@@ -1,584 +0,0 @@
package com.dbx.agent.tdengine;
import com.dbx.agent.ColumnInfo;
import com.dbx.agent.ConnectParams;
import com.dbx.agent.DatabaseAgent;
import com.dbx.agent.ExecuteQueryOptions;
import com.dbx.agent.MetadataListConstraints;
import com.dbx.agent.TableInfo;
import com.dbx.agent.test.JdbcAgentFake;
import com.dbx.agent.test.JdbcFakeExecutionBehaviorTest;
import com.dbx.agent.test.JdbcMetadataSqlFake;
import com.dbx.agent.test.TestSupport;
import com.taosdata.jdbc.TSDBDriver;
import com.taosdata.jdbc.rs.RestfulConnection;
import com.zaxxer.hikari.HikariConfig;
import com.zaxxer.hikari.HikariDataSource;
import java.lang.reflect.InvocationHandler;
import java.lang.reflect.Proxy;
import java.nio.charset.StandardCharsets;
import java.sql.Connection;
import java.sql.ResultSet;
import java.sql.Timestamp;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;
import java.util.Properties;
import javax.sql.DataSource;
import org.junit.jupiter.api.Assertions;
import org.junit.jupiter.api.Test;
class TDengineAgentExecutionTest extends JdbcFakeExecutionBehaviorTest {
@Override
protected DatabaseAgent createAgent() {
return new TDengineAgent();
}
@Override
protected String resultSetSql() {
return "SHOW DATABASES";
}
}
class TDengineAgentMetadataTest {
@Test
void buildsWebsocketJdbcUrlWithDefaultPortAndDatabase() {
String url = TDengineJdbcUrl.from(
new ConnectParams("127.0.0.1", 0, "meters", "root", "taosdata", "", "", false)
);
Assertions.assertEquals("jdbc:TAOS-WS://127.0.0.1:6041/meters", url);
}
@Test
void preservesCustomWebsocketPortAndUrlParams() {
String url = TDengineJdbcUrl.from(
new ConnectParams("td.local", 6042, "", "", "", "timezone=UTC&charset=UTF-8", "", false)
);
Assertions.assertEquals("jdbc:TAOS-WS://td.local:6042/?timezone=UTC&charset=UTF-8", url);
}
@Test
void supportsRestTransportViaCompatibilityUrlParam() {
String url = TDengineJdbcUrl.from(
new ConnectParams("127.0.0.1", 0, "testdb", "", "", "dbx.transport=rest&charset=UTF-8", "", false)
);
Assertions.assertEquals("jdbc:TAOS-RS://127.0.0.1:6041/testdb?charset=UTF-8", url);
}
@Test
void stripsTransportControlParamFromJdbcQuery() {
String url = TDengineJdbcUrl.from(
new ConnectParams("127.0.0.1", 6041, "", "", "", "transport=ws&timezone=UTC", "", false)
);
Assertions.assertEquals("jdbc:TAOS-WS://127.0.0.1:6041/?timezone=UTC", url);
}
@Test
void usesTdengineShowStatementsForMetadata() {
TDengineAgent agent = new TDengineAgent();
TestSupport.setPrivateConnection(agent, JdbcMetadataSqlFake.connection());
agent.listDatabases();
agent.listTables("power");
agent.getColumns("power", "meters");
Assertions.assertEquals("SHOW DATABASES", JdbcMetadataSqlFake.statements.get(0));
Assertions.assertEquals("SHOW `power`.STABLES", JdbcMetadataSqlFake.statements.get(1));
Assertions.assertEquals("SHOW `power`.TABLES", JdbcMetadataSqlFake.statements.get(2));
Assertions.assertFalse(JdbcMetadataSqlFake.statements.stream().anyMatch(sql -> sql.contains("information_schema")));
Assertions.assertTrue(JdbcMetadataSqlFake.statements.contains("DESCRIBE `power`.`meters`"));
}
@Test
void showMetadataStopsReadingAtTheRequestedPageBoundary() {
List<String> statements = new ArrayList<>();
List<Integer> maxRows = new ArrayList<>();
List<String> rowReads = new ArrayList<>();
TDengineAgent agent = new TDengineAgent();
TestSupport.setPrivateConnection(agent, showMetadataConnection(statements, maxRows, rowReads));
List<TableInfo> firstPage = agent.listTables(
"dbx_alpha",
new MetadataListConstraints(null, 3, null, List.of("TABLE"))
);
List<TableInfo> secondPage = agent.listTables(
"dbx_alpha",
new MetadataListConstraints(null, 2, 3, List.of("TABLE"))
);
Assertions.assertEquals(List.of("meters", "weather", "device_a"), firstPage.stream().map(TableInfo::getName).toList());
Assertions.assertEquals(List.of("device_b", "standalone"), secondPage.stream().map(TableInfo::getName).toList());
Assertions.assertEquals("meters", firstPage.get(2).getParent_name());
Assertions.assertEquals("meters", secondPage.get(0).getParent_name());
Assertions.assertTrue(maxRows.isEmpty());
Assertions.assertEquals(
List.of(
"SHOW `dbx_alpha`.STABLES",
"SHOW `dbx_alpha`.TABLES",
"SHOW `dbx_alpha`.STABLES",
"SHOW `dbx_alpha`.TABLES"
),
statements
);
Assertions.assertEquals(4, rowReads.stream().filter("STABLE"::equals).count());
Assertions.assertEquals(4, rowReads.stream().filter("TABLE"::equals).count());
}
@Test
void showMetadataCachesOnlyUnboundedResults() {
List<String> statements = new ArrayList<>();
List<Integer> maxRows = new ArrayList<>();
TDengineAgent agent = new TDengineAgent();
TestSupport.setPrivateConnection(agent, showMetadataConnection(statements, maxRows));
agent.listTables("dbx_alpha");
agent.listTables("dbx_alpha");
Assertions.assertEquals(
List.of(
"SHOW `dbx_alpha`.STABLES",
"SHOW `dbx_alpha`.TABLES"
),
statements
);
}
@Test
void showMetadataFiltersLocallyBeforeApplyingRowLimit() {
List<String> statements = new ArrayList<>();
List<Integer> maxRows = new ArrayList<>();
TDengineAgent agent = new TDengineAgent();
TestSupport.setPrivateConnection(agent, showMetadataConnection(statements, maxRows));
List<TableInfo> tables = agent.listTables(
"dbx_alpha",
new MetadataListConstraints("stand", 1, null, List.of("TABLE"))
);
Assertions.assertEquals(List.of("standalone"), tables.stream().map(TableInfo::getName).toList());
Assertions.assertTrue(maxRows.isEmpty());
Assertions.assertEquals(
List.of(
"SHOW `dbx_alpha`.STABLES",
"SHOW `dbx_alpha`.TABLES"
),
statements
);
}
@Test
void showMetadataFallsBackToLocalFilteringForLongLikePatterns() {
List<String> statements = new ArrayList<>();
List<Integer> maxRows = new ArrayList<>();
TDengineAgent agent = new TDengineAgent();
TestSupport.setPrivateConnection(agent, showMetadataConnection(statements, maxRows));
agent.listTables(
"dbx_alpha",
new MetadataListConstraints("a".repeat(50), 1, null, List.of("TABLE"))
);
Assertions.assertTrue(maxRows.isEmpty());
Assertions.assertEquals(
List.of(
"SHOW `dbx_alpha`.STABLES",
"SHOW `dbx_alpha`.TABLES"
),
statements
);
}
@Test
void showMetadataDoesNotLoadTableComments() {
List<String> statements = new ArrayList<>();
List<Integer> maxRows = new ArrayList<>();
TDengineAgent agent = new TDengineAgent();
TestSupport.setPrivateConnection(agent, showMetadataConnection(statements, maxRows));
List<TableInfo> tables = agent.listTables("dbx_alpha");
Assertions.assertNull(tables.get(0).getComment());
Assertions.assertEquals(
List.of(
"SHOW `dbx_alpha`.STABLES",
"SHOW `dbx_alpha`.TABLES"
),
statements
);
}
@Test
void showMetadataFiltersByNameWithoutInformationSchema() {
List<String> statements = new ArrayList<>();
List<Integer> maxRows = new ArrayList<>();
TDengineAgent agent = new TDengineAgent();
TestSupport.setPrivateConnection(agent, showMetadataConnection(statements, maxRows));
List<TableInfo> tables = agent.listTables(
"dbx_alpha",
new MetadataListConstraints("device_b", 1, null, List.of("TABLE"))
);
Assertions.assertEquals(List.of("device_b"), tables.stream().map(TableInfo::getName).toList());
Assertions.assertTrue(maxRows.isEmpty());
}
@Test
void sortsSupertablesBeforeTheirChildTables() {
List<TableInfo> tables = new ArrayList<>(Arrays.asList(
new TableInfo("device_b", "TABLE", null, null, "meters"),
new TableInfo("standalone", "TABLE", null),
new TableInfo("meters", "STABLE", null),
new TableInfo("device_a", "TABLE", null, null, "meters")
));
TDengineAgent.sortTablesForHierarchy(tables);
Assertions.assertEquals(
Arrays.asList("meters", "device_a", "device_b", "standalone"),
tables.stream().map(TableInfo::getName).toList()
);
Assertions.assertEquals("meters", tables.get(1).getParent_name());
}
@Test
void marksTimestampAndCompositeKeyDescribeColumnsAsPrimaryKeys() throws Exception {
ResultSet resultSet = describeResultSet(new String[][] {
{"ts", "TIMESTAMP", "8", ""},
{"seq", "INT", "4", "COMPOSITE KEY"},
{"voltage", "FLOAT", "4", ""},
{"site", "VARCHAR(32)", "32", "TAG"}
});
List<ColumnInfo> columns = TDengineAgent.readDescribeColumns(resultSet);
Assertions.assertTrue(columns.get(0).getIs_primary_key());
Assertions.assertFalse(columns.get(0).getIs_nullable());
Assertions.assertTrue(columns.get(1).getIs_primary_key());
Assertions.assertFalse(columns.get(1).getIs_nullable());
Assertions.assertFalse(columns.get(2).getIs_primary_key());
Assertions.assertFalse(columns.get(3).getIs_primary_key());
Assertions.assertEquals("TAG", columns.get(3).getExtra());
}
@Test
void doesNotExposeDatabasesAsSchemas() {
TDengineAgent agent = new TDengineAgent();
TestSupport.setPrivateConnection(agent, JdbcMetadataSqlFake.connection());
Assertions.assertTrue(agent.listSchemas().isEmpty());
Assertions.assertTrue(JdbcMetadataSqlFake.statements.isEmpty());
}
private static Connection showMetadataConnection(List<String> statements, List<Integer> maxRows) {
return showMetadataConnection(statements, maxRows, null);
}
private static Connection showMetadataConnection(
List<String> statements,
List<Integer> maxRows,
List<String> rowReads
) {
return proxy(Connection.class, (proxy, method, args) -> {
String name = method.getName();
if ("createStatement".equals(name)) {
return showMetadataStatement(statements, maxRows, rowReads);
}
if ("isClosed".equals(name)) return false;
if ("close".equals(name)) return null;
return defaultValue(method.getReturnType());
});
}
private static java.sql.Statement showMetadataStatement(
List<String> statements,
List<Integer> maxRows,
List<String> rowReads
) {
int[] activeMaxRows = {0};
return proxy(java.sql.Statement.class, (proxy, method, args) -> {
String name = method.getName();
if ("setMaxRows".equals(name)) {
activeMaxRows[0] = (Integer) args[0];
maxRows.add(activeMaxRows[0]);
return null;
}
if ("executeQuery".equals(name)) {
String sql = (String) args[0];
statements.add(sql);
if (sql.endsWith("STABLES")) {
return showTableResultSet(
List.of(new String[] {"meters"}, new String[] {"weather"}),
activeMaxRows[0],
"STABLE",
rowReads
);
}
if (sql.endsWith("TABLES")) {
return showTableResultSet(
List.of(
new String[] {"device_a", "", "", "meters"},
new String[] {"device_b", "", "", "meters"},
new String[] {"standalone", "", "", ""}
),
activeMaxRows[0],
"TABLE",
rowReads
);
}
}
if ("close".equals(name)) return null;
return defaultValue(method.getReturnType());
});
}
private static ResultSet showTableResultSet(
List<String[]> rows,
int maxRows,
String tableType,
List<String> rowReads
) {
List<String[]> limitedRows = maxRows > 0 ? rows.subList(0, Math.min(rows.size(), maxRows)) : rows;
int[] index = {-1};
return proxy(ResultSet.class, (proxy, method, args) -> {
String name = method.getName();
if ("next".equals(name)) {
index[0] += 1;
boolean hasNext = index[0] < limitedRows.size();
if (hasNext && rowReads != null) {
rowReads.add(tableType);
}
return hasNext;
}
if ("getString".equals(name)) {
int column = (Integer) args[0];
String[] row = limitedRows.get(index[0]);
return column <= row.length ? row[column - 1] : null;
}
if ("isClosed".equals(name)) return false;
if ("close".equals(name)) return null;
return defaultValue(method.getReturnType());
});
}
private static <T> T proxy(Class<T> type, InvocationHandler handler) {
return type.cast(Proxy.newProxyInstance(type.getClassLoader(), new Class<?>[]{type}, handler));
}
private static Object defaultValue(Class<?> type) {
if (Boolean.TYPE.equals(type)) return false;
if (Integer.TYPE.equals(type)) return 0;
if (Long.TYPE.equals(type)) return 0L;
if (Double.TYPE.equals(type)) return 0.0d;
if (Float.TYPE.equals(type)) return 0.0f;
if (Short.TYPE.equals(type)) return (short) 0;
if (Byte.TYPE.equals(type)) return (byte) 0;
if (Character.TYPE.equals(type)) return '\0';
return null;
}
@Test
void setsDatabaseBeforeExecutionWhenSchemaIsProvided() {
TDengineAgent agent = new TDengineAgent();
TestSupport.setPrivateConnection(agent, JdbcAgentFake.connection());
agent.executeQuery("SELECT 1", "power", new ExecuteQueryOptions());
// JdbcSchemaSwitcher executes the USE statement (recorded as "execute")
// before the query runs, so the database is switched prior to execution.
Assertions.assertEquals(
Arrays.asList("execute", "setMaxRows:10001", "execute"),
JdbcAgentFake.calls
);
}
@Test
void restExecutionSwitchesCatalogWithoutGeneratingUseSql() throws Exception {
try (RestfulConnection connection = restfulConnection()) {
String executionSchema = TDengineAgent.prepareExecutionSchema(connection, " power-data ");
Assertions.assertNull(executionSchema);
Assertions.assertEquals("power-data", connection.getCatalog());
Assertions.assertEquals(
"power-data",
connection.getClientInfo(TSDBDriver.PROPERTY_KEY_DBNAME)
);
}
}
@Test
void restExecutionSupportsPooledWrappersAndRestoresOriginalDatabase() throws Exception {
Properties properties = new Properties();
properties.setProperty(TSDBDriver.PROPERTY_KEY_DBNAME, "original");
try (RestfulConnection physical = restfulConnection(properties)) {
physical.setCatalog("original");
Connection pooled = wrapperConnection(physical);
Assertions.assertNull(TDengineAgent.prepareExecutionSchema(pooled, "power"));
Assertions.assertEquals("power", pooled.getCatalog());
Assertions.assertEquals("power", pooled.getClientInfo(TSDBDriver.PROPERTY_KEY_DBNAME));
TDengineAgent.restoreRestfulConnectionState(pooled, "original", "original");
Assertions.assertEquals("original", pooled.getCatalog());
Assertions.assertEquals("original", pooled.getClientInfo(TSDBDriver.PROPERTY_KEY_DBNAME));
}
}
@Test
void hikariCanManageRestfulConnectionsWithoutLosingNativeAccess() throws Exception {
RestfulConnection physical = restfulConnection();
DataSource dataSource = proxy(DataSource.class, (proxy, method, args) -> {
if ("getConnection".equals(method.getName())) {
return physical;
}
return defaultValue(method.getReturnType());
});
HikariConfig config = new HikariConfig();
config.setPoolName("tdengine-rest-test");
config.setDataSource(dataSource);
config.setMaximumPoolSize(1);
config.setMinimumIdle(0);
config.setInitializationFailTimeout(-1L);
try (HikariDataSource pool = new HikariDataSource(config);
Connection connection = pool.getConnection()) {
Assertions.assertTrue(connection.isWrapperFor(RestfulConnection.class));
Assertions.assertSame(physical, connection.unwrap(RestfulConnection.class));
Assertions.assertNull(TDengineAgent.prepareExecutionSchema(connection, "power"));
Assertions.assertEquals("power", connection.getCatalog());
}
}
@Test
void websocketExecutionKeepsSchemaForUseSqlSwitching() throws Exception {
Connection connection = JdbcAgentFake.connection();
Assertions.assertEquals(
"power",
TDengineAgent.prepareExecutionSchema(connection, "power")
);
}
@Test
void decodesTdengineByteArrayTextValues() {
Assertions.assertEquals(
"d1001",
TDengineAgent.decodeTdengineValue("d1001".getBytes(StandardCharsets.UTF_8))
);
}
@Test
void formatsTdengineTimestampsAsSqlLiterals() {
Assertions.assertEquals(
"2026-05-16 09:35:58.123",
TDengineAgent.decodeTdengineValue(Timestamp.valueOf("2026-05-16 09:35:58.123"))
);
Assertions.assertEquals(
"2026-05-16 09:35:58.000",
TDengineAgent.decodeTdengineValue(Timestamp.valueOf("2026-05-16 09:35:58"))
);
Assertions.assertEquals(
"2026-05-16 09:35:58.123456",
TDengineAgent.decodeTdengineValue(Timestamp.valueOf("2026-05-16 09:35:58.123456"))
);
Assertions.assertEquals(
"2026-05-16 09:35:58.123456789",
TDengineAgent.decodeTdengineValue(Timestamp.valueOf("2026-05-16 09:35:58.123456789"))
);
}
@Test
void unknownTransportValueDefaultsToWebsocketAndKeepsOtherParams() {
String url = TDengineJdbcUrl.from(
new ConnectParams("127.0.0.1", 6041, "", "", "", "transport=foo&timezone=UTC", "", false)
);
Assertions.assertEquals("jdbc:TAOS-WS://127.0.0.1:6041/?timezone=UTC", url);
}
@Test
void sanitizeConnectionStringStripsTransportControlParams() {
String sanitized = TDengineJdbcUrl.sanitizeConnectionString(
"jdbc:TAOS-WS://127.0.0.1:6041/db?dbx.transport=rest&charset=UTF-8&transport=ws"
);
Assertions.assertEquals("jdbc:TAOS-WS://127.0.0.1:6041/db?charset=UTF-8", sanitized);
}
@Test
void sanitizeConnectionStringKeepsFragmentAndNonControlParams() {
String sanitized = TDengineJdbcUrl.sanitizeConnectionString(
"jdbc:TAOS-RS://127.0.0.1:6041/db?timezone=UTC&dbx.transport=rest#anchor"
);
Assertions.assertEquals("jdbc:TAOS-RS://127.0.0.1:6041/db?timezone=UTC#anchor", sanitized);
}
@Test
void enablesRestInformationSchemaPagingForTdengine338AndNewer() {
Assertions.assertFalse(TDengineAgent.supportsRestInformationSchemaPagingVersion(null));
Assertions.assertFalse(TDengineAgent.supportsRestInformationSchemaPagingVersion("3.3.7.9"));
Assertions.assertTrue(TDengineAgent.supportsRestInformationSchemaPagingVersion("3.3.8.0"));
Assertions.assertTrue(TDengineAgent.supportsRestInformationSchemaPagingVersion("3.3.8.1"));
Assertions.assertTrue(TDengineAgent.supportsRestInformationSchemaPagingVersion("4.0.0.0"));
}
private static ResultSet describeResultSet(String[][] rows) {
int[] rowIndex = {-1};
return (ResultSet) Proxy.newProxyInstance(
ResultSet.class.getClassLoader(),
new Class<?>[] {ResultSet.class},
(proxy, method, args) -> {
if ("next".equals(method.getName())) {
rowIndex[0] += 1;
return rowIndex[0] < rows.length;
}
if ("getString".equals(method.getName())) {
return rows[rowIndex[0]][((Integer) args[0]) - 1];
}
if ("close".equals(method.getName())) {
return null;
}
throw new UnsupportedOperationException(method.getName());
}
);
}
private static RestfulConnection restfulConnection() {
return restfulConnection(new Properties());
}
private static RestfulConnection restfulConnection(Properties properties) {
return new RestfulConnection(
"127.0.0.1",
"6041",
properties,
"",
"jdbc:TAOS-RS://127.0.0.1:6041/",
null,
false,
null,
null
);
}
private static Connection wrapperConnection(Connection physical) {
return proxy(Connection.class, (proxy, method, args) -> {
if ("isWrapperFor".equals(method.getName())) {
return ((Class<?>) args[0]).isInstance(physical);
}
if ("unwrap".equals(method.getName())) {
return ((Class<?>) args[0]).cast(physical);
}
try {
return method.invoke(physical, args);
} catch (java.lang.reflect.InvocationTargetException error) {
throw error.getCause();
}
});
}
}
+124
View File
@@ -0,0 +1,124 @@
use base64::engine::general_purpose::STANDARD;
use base64::Engine;
use chrono::{NaiveDateTime, Timelike};
use chrono_tz::Tz;
use serde_json::{json, Number, Value};
use taos::taos_query::common::Timestamp;
use taos::BorrowedValue;
pub fn borrowed_value_to_json(value: BorrowedValue<'_>, timezone: Option<Tz>) -> Value {
match value {
BorrowedValue::Null(_) => Value::Null,
BorrowedValue::Bool(value) => Value::Bool(value),
BorrowedValue::TinyInt(value) => json!(value),
BorrowedValue::SmallInt(value) => json!(value),
BorrowedValue::Int(value) => json!(value),
BorrowedValue::BigInt(value) => json!(value),
BorrowedValue::UTinyInt(value) => json!(value),
BorrowedValue::USmallInt(value) => json!(value),
BorrowedValue::UInt(value) => json!(value),
BorrowedValue::UBigInt(value) => json!(value),
BorrowedValue::Float(value) => finite_number(value as f64),
BorrowedValue::Double(value) => finite_number(value),
BorrowedValue::VarChar(value) => Value::String(value.to_string()),
BorrowedValue::NChar(value) => Value::String(value.into_owned()),
BorrowedValue::Timestamp(value) => Value::String(format_timestamp(value, timezone)),
BorrowedValue::Json(value) => serde_json::from_slice(&value)
.unwrap_or_else(|_| Value::String(String::from_utf8_lossy(&value).into_owned())),
BorrowedValue::VarBinary(value) | BorrowedValue::Blob(value) | BorrowedValue::MediumBlob(value) => {
binary_json(&value)
}
BorrowedValue::Geometry(value) => geometry_json(&value),
BorrowedValue::Decimal(value) => Value::String(value.to_string()),
BorrowedValue::Decimal64(value) => Value::String(value.to_string()),
}
}
fn finite_number(value: f64) -> Value {
Number::from_f64(value).map(Value::Number).unwrap_or_else(|| Value::String(value.to_string()))
}
fn binary_json(value: &[u8]) -> Value {
json!({ "$binary": STANDARD.encode(value) })
}
fn geometry_json(value: &[u8]) -> Value {
if let Ok(text) = std::str::from_utf8(value) {
let trimmed = text.trim();
if looks_like_wkt(trimmed) {
return Value::String(trimmed.to_string());
}
}
binary_json(value)
}
fn looks_like_wkt(value: &str) -> bool {
let upper = value.to_ascii_uppercase();
["POINT", "LINESTRING", "POLYGON", "MULTIPOINT", "MULTILINESTRING", "MULTIPOLYGON", "GEOMETRYCOLLECTION"]
.iter()
.any(|prefix| upper.starts_with(prefix))
}
fn format_timestamp(timestamp: Timestamp, timezone: Option<Tz>) -> String {
let datetime = match timezone {
Some(timezone) => timestamp.to_datetime_with_custom_tz(&timezone).naive_local(),
None => timestamp.to_naive_datetime(),
};
format_naive_datetime(datetime, timestamp)
}
fn format_naive_datetime(datetime: NaiveDateTime, timestamp: Timestamp) -> String {
let digits = match timestamp {
Timestamp::Milliseconds(_) => 3,
Timestamp::Microseconds(_) => 6,
Timestamp::Nanoseconds(_) => 9,
};
let mut fraction = format!("{:09}", datetime.nanosecond());
fraction.truncate(digits);
while fraction.len() > 3 && fraction.ends_with('0') {
fraction.pop();
}
format!("{}.{}", datetime.format("%Y-%m-%d %H:%M:%S"), fraction)
}
#[cfg(test)]
mod tests {
use super::*;
use taos::Ty;
#[test]
fn preserves_timestamp_precision_with_at_least_milliseconds() {
assert_eq!(
borrowed_value_to_json(
BorrowedValue::Timestamp(Timestamp::Milliseconds(1_704_067_200_123)),
Some(chrono_tz::UTC)
),
Value::String("2024-01-01 00:00:00.123".into())
);
assert_eq!(
borrowed_value_to_json(
BorrowedValue::Timestamp(Timestamp::Microseconds(1_704_067_200_123_400)),
Some(chrono_tz::UTC)
),
Value::String("2024-01-01 00:00:00.1234".into())
);
}
#[test]
fn keeps_text_and_binary_values_distinct() {
assert_eq!(borrowed_value_to_json(BorrowedValue::VarChar("hello"), None), json!("hello"));
assert_eq!(
borrowed_value_to_json(BorrowedValue::VarBinary(vec![0, 255].into()), None),
json!({"$binary": "AP8="})
);
assert_eq!(borrowed_value_to_json(BorrowedValue::Null(Ty::Int), None), Value::Null);
}
#[test]
fn returns_wkt_geometry_as_text() {
assert_eq!(
borrowed_value_to_json(BorrowedValue::Geometry(b"POINT (1 2)".as_slice().into()), None),
json!("POINT (1 2)")
);
}
}
+219
View File
@@ -0,0 +1,219 @@
use std::env;
use std::io::{BufRead, BufReader, Write};
use std::process::{Child, ChildStdin, ChildStdout, Command, Stdio};
use serde_json::{json, Value};
struct AgentProcess {
child: Child,
stdin: ChildStdin,
stdout: BufReader<ChildStdout>,
next_id: u64,
}
impl AgentProcess {
fn spawn() -> Self {
let mut child = Command::new(env!("CARGO_BIN_EXE_dbx-tdengine-driver"))
.stdin(Stdio::piped())
.stdout(Stdio::piped())
.stderr(Stdio::inherit())
.spawn()
.expect("start TDengine agent");
let stdin = child.stdin.take().expect("agent stdin");
let mut stdout = BufReader::new(child.stdout.take().expect("agent stdout"));
let mut ready = String::new();
stdout.read_line(&mut ready).expect("read ready line");
assert_eq!(serde_json::from_str::<Value>(&ready).unwrap(), json!({"ready": true}));
Self { child, stdin, stdout, next_id: 1 }
}
fn call(&mut self, method: &str, params: Value) -> Value {
let id = self.next_id;
self.next_id += 1;
let request = json!({"jsonrpc": "2.0", "id": id, "method": method, "params": params});
writeln!(self.stdin, "{request}").expect("write request");
self.stdin.flush().expect("flush request");
let mut line = String::new();
self.stdout.read_line(&mut line).expect("read response");
let response: Value = serde_json::from_str(&line).expect("valid JSON response");
assert_eq!(response["id"], id, "unexpected response: {response}");
if let Some(error) = response.get("error") {
panic!("{method} failed: {error}");
}
response["result"].clone()
}
fn shutdown(mut self) {
assert_eq!(self.call("shutdown", json!({})), json!({"ok": true}));
drop(self.stdin);
assert!(self.child.wait().expect("wait for agent").success());
}
}
fn integration_params() -> Option<Value> {
if env::var("TDENGINE_INTEGRATION").ok().as_deref() != Some("1") {
return None;
}
Some(json!({
"host": env::var("TDENGINE_TEST_HOST").unwrap_or_else(|_| "127.0.0.1".into()),
"port": env::var("TDENGINE_TEST_PORT").ok().and_then(|value| value.parse::<u16>().ok()).unwrap_or(6041),
"username": env::var("TDENGINE_TEST_USERNAME").unwrap_or_else(|_| "root".into()),
"password": env::var("TDENGINE_TEST_PASSWORD").unwrap_or_else(|_| "taosdata".into()),
"connect_timeout_secs": 20,
}))
}
#[test]
fn tdengine_websocket_live_compatibility() {
let Some(connect_params) = integration_params() else {
return;
};
let database = format!("dbx_rust_live_{}", std::process::id());
let session_id = "tdengine-live";
let mut agent = AgentProcess::spawn();
let tested = agent.call("test_connection", connect_params.clone());
assert_eq!(tested["ok"], true);
assert_eq!(tested["databaseInfo"]["productName"], "TDengine");
assert!(tested["databaseInfo"]["productVersion"].as_str().is_some_and(|version| !version.is_empty()));
let mut open_params = connect_params.clone();
open_params["agentSessionId"] = json!(session_id);
assert_eq!(agent.call("open_session", open_params), json!({"ok": true}));
agent.call(
"execute_batch",
json!({
"agentSessionId": session_id,
"statements": [
format!("CREATE DATABASE IF NOT EXISTS {database}"),
format!("CREATE STABLE IF NOT EXISTS {database}.meters (ts TIMESTAMP, current FLOAT, voltage INT, active BOOL, note NCHAR(32)) TAGS (location NCHAR(64), group_id INT)"),
format!("CREATE TABLE IF NOT EXISTS {database}.d1001 USING {database}.meters TAGS ('California.SanFrancisco', 2)"),
format!("INSERT INTO {database}.d1001 VALUES ('2026-08-04 10:00:00.001', 10.1, 220, true, 'first') ('2026-08-04 10:00:00.002', 10.2, 221, false, 'second') ('2026-08-04 10:00:00.003', 10.3, 222, true, 'third')")
]
}),
);
let host = connect_params["host"].as_str().unwrap();
let host = if host.contains(':') { format!("[{host}]") } else { host.to_string() };
let port = connect_params["port"].as_u64().unwrap();
let mut database_connect_params = connect_params.clone();
database_connect_params["connection_string"] = json!(format!("ws://{host}:{port}/{database}"));
database_connect_params["database"] = json!("");
let database_connection = agent.call("test_connection", database_connect_params);
assert_eq!(database_connection["databaseInfo"]["currentDatabase"], database);
let databases = agent.call("list_databases", json!({"agentSessionId": session_id}));
assert!(databases.as_array().unwrap().iter().any(|item| item["name"] == database));
let tables = agent.call(
"list_tables",
json!({
"agentSessionId": session_id,
"schema": database,
"filter": "",
"limit": 100,
"offset": 0,
"object_types": []
}),
);
let tables = tables.as_array().unwrap();
assert!(tables.iter().any(|table| table["name"] == "meters" && table["table_type"] == "STABLE"));
assert!(tables.iter().any(|table| table["name"] == "d1001" && table["parent_name"] == "meters"));
let columns =
agent.call("get_columns", json!({"agentSessionId": session_id, "schema": database, "table": "meters"}));
let columns = columns.as_array().unwrap();
assert!(columns.iter().any(|column| column["name"] == "ts" && column["is_primary_key"] == true));
assert!(columns.iter().any(|column| column["name"] == "location" && column["comment"] == "TAG"));
let query = agent.call(
"execute_query",
json!({
"agentSessionId": session_id,
"schema": database,
"sql": "SELECT * FROM d1001 ORDER BY ts",
"maxRows": 2,
"fetchSize": 100,
"timeoutSecs": 10
}),
);
assert_eq!(query["rows"].as_array().unwrap().len(), 2);
assert_eq!(query["truncated"], true);
assert_eq!(query["rows"][0][0], "2026-08-04 10:00:00.001");
let connection_info = agent.call("connection_info", json!({"agentSessionId": session_id}));
assert_eq!(connection_info["databaseInfo"]["currentDatabase"], database);
let first_page = agent.call(
"execute_query_page",
json!({
"agentSessionId": session_id,
"schema": database,
"sql": "SELECT * FROM d1001 ORDER BY ts",
"maxRows": 2,
"pageSize": 1,
"timeoutSecs": 10
}),
);
assert_eq!(first_page["has_more"], true);
assert_eq!(first_page["truncated"], false);
let query_session_id = first_page["session_id"].as_str().expect("paged query session");
let final_page = agent.call(
"fetch_query_page",
json!({
"agentSessionId": session_id,
"sessionId": query_session_id,
"pageSize": 1,
"timeoutSecs": 10
}),
);
assert_eq!(final_page["rows"].as_array().unwrap().len(), 1);
assert_eq!(final_page["has_more"], false);
assert_eq!(final_page["truncated"], true);
let exact_limit = agent.call(
"execute_query",
json!({
"agentSessionId": session_id,
"schema": database,
"sql": "SELECT * FROM d1001 WHERE voltage <= 221 ORDER BY ts",
"maxRows": 2,
"timeoutSecs": 10
}),
);
assert_eq!(exact_limit["rows"].as_array().unwrap().len(), 2);
assert_eq!(exact_limit["truncated"], false);
let completion = agent.call(
"completion_assistant_search_v1",
json!({
"agentSessionId": session_id,
"schema": database,
"object_kinds": ["table"],
"mask": "met",
"match_mode": "prefix",
"max_results": 10
}),
);
assert!(completion["candidates"].as_array().unwrap().iter().any(|candidate| candidate["name"] == "meters"));
let ddl = agent.call("get_table_ddl", json!({"agentSessionId": session_id, "schema": database, "table": "meters"}));
assert!(ddl.as_str().unwrap().to_ascii_uppercase().contains("CREATE"));
let source = agent.call(
"get_object_source",
json!({
"agentSessionId": session_id,
"schema": database,
"name": "meters",
"object_type": "STABLE"
}),
);
assert!(source["source"].as_str().unwrap().to_ascii_uppercase().contains("CREATE"));
agent.call(
"execute_batch",
json!({"agentSessionId": session_id, "statements": [format!("DROP DATABASE IF EXISTS {database}")]}),
);
agent.shutdown();
}
+91
View File
@@ -0,0 +1,91 @@
use std::io::{BufRead, BufReader, Write};
use std::process::{Child, ChildStdin, ChildStdout, Command, Stdio};
use serde_json::{json, Value};
struct AgentProcess {
child: Child,
stdin: ChildStdin,
stdout: BufReader<ChildStdout>,
}
impl AgentProcess {
fn spawn() -> Self {
let mut child = Command::new(env!("CARGO_BIN_EXE_dbx-tdengine-driver"))
.stdin(Stdio::piped())
.stdout(Stdio::piped())
.stderr(Stdio::inherit())
.spawn()
.expect("start TDengine agent");
let stdin = child.stdin.take().expect("agent stdin");
let mut stdout = BufReader::new(child.stdout.take().expect("agent stdout"));
let mut ready = String::new();
stdout.read_line(&mut ready).expect("read ready line");
assert_eq!(serde_json::from_str::<Value>(&ready).unwrap(), json!({"ready": true}));
Self { child, stdin, stdout }
}
fn send(&mut self, request: Value) -> Value {
writeln!(self.stdin, "{request}").expect("write request");
self.stdin.flush().expect("flush request");
self.read_response()
}
fn send_raw(&mut self, request: &str) -> Value {
writeln!(self.stdin, "{request}").expect("write raw request");
self.stdin.flush().expect("flush raw request");
self.read_response()
}
fn read_response(&mut self) -> Value {
let mut line = String::new();
self.stdout.read_line(&mut line).expect("read response");
assert!(!line.is_empty(), "agent exited before responding");
serde_json::from_str(&line).expect("valid JSON response")
}
fn shutdown(mut self) {
let response = self.send(json!({"jsonrpc": "2.0", "id": 99, "method": "shutdown", "params": {}}));
assert_eq!(response["result"], json!({"ok": true}));
drop(self.stdin);
assert!(self.child.wait().expect("wait for agent").success());
}
}
#[test]
fn stdio_protocol_reports_ready_handshake_and_structured_errors() {
let mut agent = AgentProcess::spawn();
let handshake = agent.send(json!({"jsonrpc": "2.0", "id": 7, "method": "handshake", "params": {}}));
assert_eq!(handshake["jsonrpc"], "2.0");
assert_eq!(handshake["id"], 7);
assert_eq!(handshake["result"]["protocolVersion"], 2);
assert!(handshake["result"]["capabilities"]
.as_array()
.unwrap()
.iter()
.any(|capability| capability == "structured_error_v1"));
let unknown = agent.send(json!({"jsonrpc": "2.0", "id": 8, "method": "not_a_method", "params": {}}));
assert!(unknown["error"]["message"].as_str().unwrap().contains("unknown method"));
assert_eq!(unknown["error"]["data"]["category"], "protocol");
assert_eq!(unknown["error"]["data"]["stage"], "execute");
let malformed = agent.send_raw("{");
assert!(malformed["id"].is_null());
assert_eq!(malformed["error"]["data"]["category"], "protocol");
assert_eq!(malformed["error"]["data"]["stage"], "request");
assert_eq!(malformed["error"]["data"]["operationOutcome"], "not_started");
let invalid_connect = agent.send(json!({
"jsonrpc": "2.0",
"id": 9,
"method": "test_connection",
"params": {"connection_string": "postgres://localhost/example"}
}));
assert_eq!(invalid_connect["error"]["data"]["category"], "connection");
assert_eq!(invalid_connect["error"]["data"]["stage"], "connect");
assert_eq!(invalid_connect["error"]["data"]["operationOutcome"], "not_started");
agent.shutdown();
}
+1 -1
View File
@@ -20,6 +20,6 @@ oracle-go native-pushdown native-go Uses Oracle-compatible metadata SQL with typ
snowflake native-pushdown java-sql Uses INFORMATION_SCHEMA with type, filter, stable order, and literal LIMIT/OFFSET. snowflake native-pushdown java-sql Uses INFORMATION_SCHEMA with type, filter, stable order, and literal LIMIT/OFFSET.
spark intentional-fallback java-show-metadata Uses SHOW TABLES/SHOW DATABASES; stable server-side fuzzy paging is not portable, common constraints filter locally. spark intentional-fallback java-show-metadata Uses SHOW TABLES/SHOW DATABASES; stable server-side fuzzy paging is not portable, common constraints filter locally.
sundb native-pushdown java-sql Uses information_schema with type, filter, stable order, and LIMIT/OFFSET. sundb native-pushdown java-sql Uses information_schema with type, filter, stable order, and LIMIT/OFFSET.
tdengine intentional-fallback java-show-metadata Uses SHOW STABLES/TABLES; stable server-side fuzzy paging is not portable, common constraints filter locally. tdengine shared-fallback native-rust Uses SHOW STABLES/TABLES with information_schema parent enrichment, then applies stable filtering and paging in the native agent.
trino native-pushdown java-sql Uses information_schema.tables with type, filter, stable order, and literal LIMIT/OFFSET. trino native-pushdown java-sql Uses information_schema.tables with type, filter, stable order, and literal LIMIT/OFFSET.
xugu native-pushdown native-go Uses ALL_TABLES/ALL_VIEWS metadata with type, filter, stable order, and ROWNUM paging. xugu native-pushdown native-go Uses ALL_TABLES/ALL_VIEWS metadata with type, filter, stable order, and ROWNUM paging.
1 driver strategy scope reason
20 snowflake native-pushdown java-sql Uses INFORMATION_SCHEMA with type, filter, stable order, and literal LIMIT/OFFSET.
21 spark intentional-fallback java-show-metadata Uses SHOW TABLES/SHOW DATABASES; stable server-side fuzzy paging is not portable, common constraints filter locally.
22 sundb native-pushdown java-sql Uses information_schema with type, filter, stable order, and LIMIT/OFFSET.
23 tdengine intentional-fallback shared-fallback java-show-metadata native-rust Uses SHOW STABLES/TABLES; stable server-side fuzzy paging is not portable, common constraints filter locally. Uses SHOW STABLES/TABLES with information_schema parent enrichment, then applies stable filtering and paging in the native agent.
24 trino native-pushdown java-sql Uses information_schema.tables with type, filter, stable order, and literal LIMIT/OFFSET.
25 xugu native-pushdown native-go Uses ALL_TABLES/ALL_VIEWS metadata with type, filter, stable order, and ROWNUM paging.
+44 -2
View File
@@ -26,6 +26,8 @@ class DriverReleasePackagesTest(unittest.TestCase):
rabbitmq_source.write_bytes(b"\x7fELFtest-rabbitmq-agent") rabbitmq_source.write_bytes(b"\x7fELFtest-rabbitmq-agent")
cassandra_source = release_dir / "dbx-agent-cassandra-linux-x64" cassandra_source = release_dir / "dbx-agent-cassandra-linux-x64"
cassandra_source.write_bytes(b"\x7fELFtest-cassandra-agent") cassandra_source.write_bytes(b"\x7fELFtest-cassandra-agent")
tdengine_source = release_dir / "dbx-agent-tdengine-windows-aarch64.exe"
tdengine_source.write_bytes(b"MZtest-tdengine-agent")
java_source = release_dir / "dbx-agent-h2.jar" java_source = release_dir / "dbx-agent-h2.jar"
java_source.write_bytes(b"test-jar") java_source.write_bytes(b"test-jar")
versions = { versions = {
@@ -37,6 +39,7 @@ class DriverReleasePackagesTest(unittest.TestCase):
"duckdb": "0.1.0", "duckdb": "0.1.0",
"rabbitmq": "0.1.0", "rabbitmq": "0.1.0",
"cassandra": "0.1.37", "cassandra": "0.1.37",
"tdengine": "0.1.0",
} }
renamed = version_agent_artifacts(release_dir, versions) renamed = version_agent_artifacts(release_dir, versions)
@@ -46,7 +49,19 @@ class DriverReleasePackagesTest(unittest.TestCase):
versioned_duckdb = release_dir / "dbx-agent-duckdb-0.1.0-macos-aarch64" versioned_duckdb = release_dir / "dbx-agent-duckdb-0.1.0-macos-aarch64"
versioned_rabbitmq = release_dir / "dbx-agent-rabbitmq-0.1.0-linux-x64" versioned_rabbitmq = release_dir / "dbx-agent-rabbitmq-0.1.0-linux-x64"
versioned_cassandra = release_dir / "dbx-agent-cassandra-0.1.37-linux-x64" versioned_cassandra = release_dir / "dbx-agent-cassandra-0.1.37-linux-x64"
self.assertEqual(renamed, [versioned_java, versioned_cassandra, versioned_native, versioned_vastbase, versioned_duckdb, versioned_rabbitmq]) versioned_tdengine = release_dir / "dbx-agent-tdengine-0.1.0-windows-aarch64.exe"
self.assertEqual(
renamed,
[
versioned_java,
versioned_cassandra,
versioned_native,
versioned_vastbase,
versioned_duckdb,
versioned_rabbitmq,
versioned_tdengine,
],
)
registry = { registry = {
"jres": {"21": {"version": "21", "platforms": {}}}, "jres": {"21": {"version": "21", "platforms": {}}},
@@ -123,6 +138,19 @@ class DriverReleasePackagesTest(unittest.TestCase):
} }
}, },
}, },
"tdengine": {
"version": "0.1.0",
"label": "TDengine",
"min_app_version": "0.6.0",
"jre": "21",
"jar": {"url": "https://example.com/legacy-placeholder.jar", "size": 0},
"native": {
"windows-aarch64": {
"url": f"https://example.com/{versioned_tdengine.name}",
"size": versioned_tdengine.stat().st_size,
}
},
},
}, },
} }
(release_dir / "agent-registry.json").write_text(json.dumps(registry), encoding="utf-8") (release_dir / "agent-registry.json").write_text(json.dumps(registry), encoding="utf-8")
@@ -138,6 +166,7 @@ class DriverReleasePackagesTest(unittest.TestCase):
release_dir / "dbx-agent-vastbase-0.1.37-linux-x64.tar.zst", release_dir / "dbx-agent-vastbase-0.1.37-linux-x64.tar.zst",
release_dir / "dbx-agent-duckdb-0.1.0-macos-aarch64.tar.zst", release_dir / "dbx-agent-duckdb-0.1.0-macos-aarch64.tar.zst",
release_dir / "dbx-agent-rabbitmq-0.1.0-linux-x64.tar.zst", release_dir / "dbx-agent-rabbitmq-0.1.0-linux-x64.tar.zst",
release_dir / "dbx-agent-tdengine-0.1.0-windows-aarch64.tar.zst",
], ],
) )
package_cases = [ package_cases = [
@@ -147,6 +176,7 @@ class DriverReleasePackagesTest(unittest.TestCase):
(outputs[3], "vastbase", versioned_vastbase, "native", "linux-x64"), (outputs[3], "vastbase", versioned_vastbase, "native", "linux-x64"),
(outputs[4], "duckdb", versioned_duckdb, "native", "macos-aarch64"), (outputs[4], "duckdb", versioned_duckdb, "native", "macos-aarch64"),
(outputs[5], "rabbitmq", versioned_rabbitmq, "native", "linux-x64"), (outputs[5], "rabbitmq", versioned_rabbitmq, "native", "linux-x64"),
(outputs[6], "tdengine", versioned_tdengine, "native", "windows-aarch64"),
] ]
for output, driver_name, source, artifact_type, platform in package_cases: for output, driver_name, source, artifact_type, platform in package_cases:
tar_bytes = subprocess.run( tar_bytes = subprocess.run(
@@ -176,6 +206,7 @@ class DriverReleasePackagesTest(unittest.TestCase):
(final_registry["drivers"]["vastbase"]["native"]["linux-x64"], outputs[3]), (final_registry["drivers"]["vastbase"]["native"]["linux-x64"], outputs[3]),
(final_registry["drivers"]["duckdb"]["native"]["macos-aarch64"], outputs[4]), (final_registry["drivers"]["duckdb"]["native"]["macos-aarch64"], outputs[4]),
(final_registry["drivers"]["rabbitmq"]["native"]["linux-x64"], outputs[5]), (final_registry["drivers"]["rabbitmq"]["native"]["linux-x64"], outputs[5]),
(final_registry["drivers"]["tdengine"]["native"]["windows-aarch64"], outputs[6]),
] ]
for artifact, output in release_artifacts: for artifact, output in release_artifacts:
self.assertEqual(artifact["url"], f"https://example.com/{output.name}") self.assertEqual(artifact["url"], f"https://example.com/{output.name}")
@@ -184,7 +215,18 @@ class DriverReleasePackagesTest(unittest.TestCase):
self.assertEqual(len(artifact["sha256"]), 64) self.assertEqual(len(artifact["sha256"]), 64)
removed = remove_raw_driver_artifacts(release_dir) removed = remove_raw_driver_artifacts(release_dir)
self.assertEqual(removed, [versioned_cassandra, versioned_duckdb, versioned_java, versioned_native, versioned_rabbitmq, versioned_vastbase]) self.assertEqual(
removed,
[
versioned_cassandra,
versioned_duckdb,
versioned_java,
versioned_native,
versioned_rabbitmq,
versioned_tdengine,
versioned_vastbase,
],
)
self.assertTrue(all(output.is_file() for output in outputs)) self.assertTrue(all(output.is_file() for output in outputs))
def test_full_offline_bundle_includes_supported_windows_artifacts(self) -> None: def test_full_offline_bundle_includes_supported_windows_artifacts(self) -> None:
+1 -1
View File
@@ -18,6 +18,7 @@ NATIVE_ONLY_AGENT_MODULES = {
"oracle": "drivers/oracle-go", "oracle": "drivers/oracle-go",
"kingbase": "drivers/kingbase-go", "kingbase": "drivers/kingbase-go",
"vastbase": "drivers/vastbase-go", "vastbase": "drivers/vastbase-go",
"tdengine": "drivers/tdengine",
"xugu": "drivers/xugu", "xugu": "drivers/xugu",
"rabbitmq": "drivers/rabbitmq", "rabbitmq": "drivers/rabbitmq",
} }
@@ -27,7 +28,6 @@ JDBC_ARCHITECTURE_ALLOWLIST = {
"access": "shared lifecycle with a test-only non-creating Access URL", "access": "shared lifecycle with a test-only non-creating Access URL",
"dameng": "shared lifecycle with protocol-safe driver loading and native explain access", "dameng": "shared lifecycle with protocol-safe driver loading and native explain access",
"informix": "shared lifecycle with contextual connection error reporting", "informix": "shared lifecycle with contextual connection error reporting",
"tdengine": "shared lifecycle with WebSocket-to-REST transport fallback",
} }
APPROVED_JDBC_BASES = { APPROVED_JDBC_BASES = {
"AbstractJdbcAgent", "AbstractJdbcAgent",
+11 -2
View File
@@ -136,10 +136,19 @@ class ValidateAgentsTest(unittest.TestCase):
"include(*(infrastructureModules + driverModules))\n", "include(*(infrastructureModules + driverModules))\n",
encoding="utf-8", encoding="utf-8",
) )
for driver in ("cassandra-go", "oracle-go", "kingbase-go", "vastbase-go", "xugu", "duckdb", "rabbitmq"): for driver in (
"cassandra-go",
"oracle-go",
"kingbase-go",
"vastbase-go",
"xugu",
"duckdb",
"rabbitmq",
"tdengine",
):
(root / "drivers" / driver).mkdir(parents=True) (root / "drivers" / driver).mkdir(parents=True)
(root / "versions.json").write_text( (root / "versions.json").write_text(
json.dumps({"h2": "0.1.0", "cassandra": "0.1.0", "oracle": "0.1.0", "kingbase": "0.1.0", "vastbase": "0.1.0", "xugu": "0.1.0", "rabbitmq": "0.1.0"}), json.dumps({"h2": "0.1.0", "cassandra": "0.1.0", "oracle": "0.1.0", "kingbase": "0.1.0", "vastbase": "0.1.0", "xugu": "0.1.0", "rabbitmq": "0.1.0", "tdengine": "0.1.0"}),
encoding="utf-8", encoding="utf-8",
) )
+1 -1
View File
@@ -4,7 +4,7 @@ import json
from pathlib import Path from pathlib import Path
NATIVE_DRIVERS = ("cassandra", "oracle", "xugu", "kingbase", "vastbase", "duckdb", "rabbitmq") NATIVE_DRIVERS = ("cassandra", "oracle", "xugu", "kingbase", "vastbase", "duckdb", "rabbitmq", "tdengine")
PLATFORMS = ( PLATFORMS = (
"macos-aarch64", "macos-aarch64",
"macos-x64", "macos-x64",
+1 -1
View File
@@ -5,7 +5,7 @@ def driverModules = [
'access', 'dameng', 'goldendb', 'databend', 'databricks', 'saphana', 'access', 'dameng', 'goldendb', 'databend', 'databricks', 'saphana',
'teradata', 'vertica', 'firebird', 'exasol', 'oceanbase-oracle', 'gbase8a', 'gbase8s', 'teradata', 'vertica', 'firebird', 'exasol', 'oceanbase-oracle', 'gbase8a', 'gbase8s',
'bigquery', 'kylin', 'sundb', 'h2', 'h2-legacy', 'snowflake', 'trino', 'hive', 'spark', 'bigquery', 'kylin', 'sundb', 'h2', 'h2-legacy', 'snowflake', 'trino', 'hive', 'spark',
'db2', 'informix', 'neo4j', 'mongodb', 'highgo', 'uxdb', 'tdengine', 'yashandb', 'oscar', 'db2', 'informix', 'neo4j', 'mongodb', 'highgo', 'uxdb', 'yashandb', 'oscar',
'iris', 'iotdb', 'etcd', 'zookeeper', 'kafka', 'rocketmq', 'sqlserver-legacy' 'iris', 'iotdb', 'etcd', 'zookeeper', 'kafka', 'rocketmq', 'sqlserver-legacy'
] ]