Add portable IoTDB ODBC driver with Session TLS and application compatibility tests

.github/scripts/native-linux-env.sh

@@ -0,0 +1,20 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+# Shared Linux release baseline for the C++ SDK and ODBC driver.
+NATIVE_GLIBC_BASELINE=2.28
+NATIVE_GCC_MIN_MAJOR=14
+NATIVE_LINUX_IMAGE="quay.io/pypa/manylinux_2_28_$(uname -m)"

.github/scripts/package-client-cpp-manylinux228.sh

@@ -16,6 +16,7 @@
 #
 # Build client-cpp in manylinux_2_28 and verify max required GLIBC symbol <= 2.28.
 set -euxo pipefail
+source "$(dirname "${BASH_SOURCE[0]}")/native-linux-env.sh"
 
 MACHINE=$(uname -m)
 case "${MACHINE}" in
@@ -64,7 +65,7 @@ export JAVA_HOME
 gcc --version
 c++ --version
 gcc_major=$(gcc -dumpversion | cut -d. -f1)
-if (( gcc_major < 14 )); then
+if (( gcc_major < NATIVE_GCC_MIN_MAJOR )); then
   echo "ERROR: GCC >= 14 is required; got $(gcc -dumpversion)"
   exit 1
 fi
@@ -78,9 +79,9 @@ java -version
 # modules (IPC::Cmd, Data::Dumper) that are not on the minimal image - install
 # them even when perl itself is already present.
 if command -v dnf >/dev/null 2>&1; then
-  dnf install -y perl perl-IPC-Cmd perl-Data-Dumper
+  dnf install -y perl perl-IPC-Cmd perl-Data-Dumper perl-Time-Piece
 else
-  yum install -y perl perl-IPC-Cmd perl-Data-Dumper
+  yum install -y perl perl-IPC-Cmd perl-Data-Dumper perl-Time-Piece
 fi
 
 cd "${GITHUB_WORKSPACE:?GITHUB_WORKSPACE is not set}"
@@ -106,8 +107,9 @@ if [[ -z "${max_glibc}" ]]; then
   exit 1
 fi
 
-if awk -v max="${max_glibc}" "BEGIN { exit !(max > 2.28) }"; then
-  echo "ERROR: libiotdb_session.so requires glibc > 2.28 (max=${max_glibc})"
+highest_glibc=$(printf '%s\n' "${max_glibc}" "${NATIVE_GLIBC_BASELINE}" | sort -V | tail -1)
+if [[ "${highest_glibc}" != "${NATIVE_GLIBC_BASELINE}" ]]; then
+  echo "ERROR: libiotdb_session.so requires glibc > ${NATIVE_GLIBC_BASELINE} (max=${max_glibc})"
   exit 1
 fi
 

.github/scripts/package-odbc-manylinux228.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+set -euo pipefail
+source "$(dirname "${BASH_SOURCE[0]}")/native-linux-env.sh"
+if (( $(gcc -dumpversion | cut -d. -f1) < NATIVE_GCC_MIN_MAJOR )); then
+  echo "GCC ${NATIVE_GCC_MIN_MAJOR}+ is required" >&2
+  exit 1
+fi
+dnf install -y unixODBC-devel perl-IPC-Cmd perl-Data-Dumper perl-Time-Piece
+odbc_build="${ODBC_BUILD_DIR:-iotdb-client/odbc/target/build}"
+cmake -S iotdb-client/odbc -B "${odbc_build}" \
+  -DCMAKE_BUILD_TYPE=Release -DCMAKE_SKIP_RPATH=ON \
+  -DODBC_PACKAGE_VERSION="${ODBC_PACKAGE_VERSION:-$(sed -n 's:.*<version>\([^<]*\)</version>.*:\1:p' iotdb-client/pom.xml | head -1)}" \
+  -DODBC_PACKAGE_CLASSIFIER="linux-x86_64-glibc${NATIVE_GLIBC_BASELINE}"
+cmake --build "${odbc_build}" --parallel "${CMAKE_BUILD_PARALLEL_LEVEL:-4}"
+ctest --test-dir "${odbc_build}" --output-on-failure
+cmake -DDRIVER="${odbc_build}/libapache_iotdb_odbc.so" \
+  -DGLIBC_BASELINE="${NATIVE_GLIBC_BASELINE}" -P iotdb-client/odbc/cmake/CheckLinuxPackage.cmake
+(cd "${odbc_build}" && cpack)

.github/workflows/client-cpp-package.yml

@@ -64,7 +64,7 @@ jobs:
           cpp=false
           while IFS= read -r file; do
             case "$file" in
-              iotdb-client/client-cpp/*|iotdb-client/pom.xml|iotdb-protocol/thrift-datanode/src/main/thrift/client.thrift|iotdb-protocol/thrift-commons/src/main/thrift/common.thrift|.github/workflows/client-cpp-package.yml|.github/scripts/package-client-cpp-*.sh)
+              iotdb-client/client-cpp/*|iotdb-client/pom.xml|iotdb-protocol/thrift-datanode/src/main/thrift/client.thrift|iotdb-protocol/thrift-commons/src/main/thrift/common.thrift|.github/workflows/client-cpp-package.yml|.github/scripts/package-client-cpp-*.sh|.github/scripts/native-linux-env.sh)
                 cpp=true
                 break
                 ;;
@@ -140,7 +140,7 @@ jobs:
           echo "run_windows=${run_windows}" >> "$GITHUB_OUTPUT"
 
           # Compact JSON (no leading whitespace); required for GITHUB_OUTPUT + fromJSON().
-          WINDOWS_MATRIX='[{"name":"windows-vs2026","runs-on":"windows-2025-vs2026","boost_choco":"boost-msvc-14.3","boost_choco_version":"","cmake_generator":"Visual Studio 18 2026","package_classifier":"windows-x86_64-msvc14.4","vs_choco":"","vs_choco_params":""},{"name":"windows-vs2022","runs-on":"windows-2022","boost_choco":"boost-msvc-14.3","boost_choco_version":"","cmake_generator":"","package_classifier":"windows-x86_64-msvc14.3","vs_choco":"","vs_choco_params":""},{"name":"windows-vs2019","runs-on":"windows-2022","boost_choco":"boost-msvc-14.2","boost_choco_version":"","cmake_generator":"Visual Studio 16 2019","package_classifier":"windows-x86_64-msvc14.2","vs_choco":"visualstudio2019buildtools","vs_choco_params":"--add Microsoft.VisualStudio.Workload.VCTools --includeRecommended"},{"name":"windows-vs2017","runs-on":"windows-2022","boost_choco":"boost-msvc-14.1","boost_choco_version":"1.74.0","cmake_generator":"Visual Studio 15 2017","package_classifier":"windows-x86_64-msvc14.1","vs_choco":"visualstudio2017buildtools","vs_choco_params":"--add Microsoft.VisualStudio.Workload.VCTools --includeRecommended"}]'
+          WINDOWS_MATRIX='[{"name":"windows-vs2026","runs-on":"windows-2025-vs2026","cmake_generator":"Visual Studio 18 2026","package_classifier":"windows-x86_64-msvc14.4","vs_choco":"","vs_choco_params":""},{"name":"windows-vs2022","runs-on":"windows-2022","cmake_generator":"","package_classifier":"windows-x86_64-msvc14.3","vs_choco":"","vs_choco_params":""},{"name":"windows-vs2019","runs-on":"windows-2022","cmake_generator":"Visual Studio 16 2019","package_classifier":"windows-x86_64-msvc14.2","vs_choco":"visualstudio2019buildtools","vs_choco_params":"--add Microsoft.VisualStudio.Workload.VCTools --includeRecommended"},{"name":"windows-vs2017","runs-on":"windows-2022","cmake_generator":"Visual Studio 15 2017","package_classifier":"windows-x86_64-msvc14.1","vs_choco":"visualstudio2017buildtools","vs_choco_params":"--add Microsoft.VisualStudio.Workload.VCTools --includeRecommended"}]'
 
           write_windows_matrix_output() {
             local matrix_json="$1"
@@ -189,12 +189,13 @@ jobs:
         run: |
           set -euxo pipefail
           chmod +x .github/scripts/package-client-cpp-manylinux228.sh
+          source .github/scripts/native-linux-env.sh
           docker run --rm \
             -v "${{ github.workspace }}:/workspace" \
             -v "${HOME}/.m2:/root/.m2" \
             -w /workspace \
             -e GITHUB_WORKSPACE=/workspace \
-            quay.io/pypa/manylinux_2_28_x86_64 \
+            "${NATIVE_LINUX_IMAGE}" \
             bash .github/scripts/package-client-cpp-manylinux228.sh
       - name: Restore workspace ownership after container build
         if: always()
@@ -247,12 +248,13 @@ jobs:
         run: |
           set -euxo pipefail
           chmod +x .github/scripts/package-client-cpp-manylinux228.sh
+          source .github/scripts/native-linux-env.sh
           docker run --rm \
             -v "${{ github.workspace }}:/workspace" \
             -v "${HOME}/.m2:/root/.m2" \
             -w /workspace \
             -e GITHUB_WORKSPACE=/workspace \
-            quay.io/pypa/manylinux_2_28_aarch64 \
+            "${NATIVE_LINUX_IMAGE}" \
             bash .github/scripts/package-client-cpp-manylinux228.sh
       - name: Restore workspace ownership after container build
         if: always()
@@ -432,20 +434,11 @@ jobs:
         shell: pwsh
         run: |
           choco install winflexbison3 strawberryperl -y --no-progress
+          if ($LASTEXITCODE) { exit $LASTEXITCODE }
           echo 'C:\Strawberry\perl\bin' >> $env:GITHUB_PATH
-          $boostArgs = @('install', '${{ matrix.boost_choco }}', '-y', '--no-progress')
-          if ('${{ matrix.boost_choco_version }}' -ne '') {
-            $boostArgs += @("--version=${{ matrix.boost_choco_version }}")
-          }
-          & choco @boostArgs
-          if (-not (Test-Path 'C:\local')) {
-            New-Item -ItemType Directory -Path 'C:\local' -Force | Out-Null
-          }
-          $boostDir = Get-ChildItem -Path 'C:\local\' -Filter 'boost_*' -ErrorAction SilentlyContinue | Select-Object -First 1
-          if (-not $boostDir) {
-            throw "Boost not found under C:\local after installing ${{ matrix.boost_choco }}"
-          }
-          echo $boostDir.FullName >> $env:GITHUB_PATH
+          # Thrift only needs Boost headers. FetchBoost.cmake provides the same
+          # source headers for every toolchain; precompiled Chocolatey Boost
+          # installers add an unnecessary download and can fail checksum checks.
       - name: Cache Maven packages
         uses: actions/cache@v5
         with:

.github/workflows/multi-language-client.yml

@@ -15,6 +15,7 @@ on:
       - '.github/workflows/multi-language-client.yml'
       - '.github/workflows/client-cpp-package.yml'
       - '.github/scripts/package-client-cpp-*.sh'
+      - '.github/scripts/native-linux-env.sh'
   pull_request:
     branches:
       - master
@@ -30,6 +31,7 @@ on:
       - '.github/workflows/multi-language-client.yml'
       - '.github/workflows/client-cpp-package.yml'
       - '.github/scripts/package-client-cpp-*.sh'
+      - '.github/scripts/native-linux-env.sh'
   # allow manually run the action:
   workflow_dispatch:
 
@@ -82,7 +84,7 @@ jobs:
           go=false
           while IFS= read -r file; do
             case "$file" in
-              pom.xml|iotdb-client/pom.xml|iotdb-client/client-cpp/*|iotdb-protocol/thrift-datanode/src/main/thrift/client.thrift|iotdb-protocol/thrift-commons/src/main/thrift/common.thrift|.github/workflows/multi-language-client.yml|.github/workflows/client-cpp-package.yml|.github/scripts/package-client-cpp-*.sh)
+              pom.xml|iotdb-client/pom.xml|iotdb-client/client-cpp/*|iotdb-protocol/thrift-datanode/src/main/thrift/client.thrift|iotdb-protocol/thrift-commons/src/main/thrift/common.thrift|.github/workflows/multi-language-client.yml|.github/workflows/client-cpp-package.yml|.github/scripts/package-client-cpp-*.sh|.github/scripts/native-linux-env.sh)
                 cpp=true
                 ;;
             esac

.github/workflows/odbc-package.yml

@@ -0,0 +1,180 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+name: ODBC package
+on:
+  workflow_dispatch:
+  push:
+    paths:
+      - 'iotdb-client/odbc/**'
+      - 'iotdb-client/client-cpp/**'
+      - 'iotdb-protocol/**/thrift/**'
+      - '.github/scripts/*odbc*'
+      - '.github/scripts/native-linux-env.sh'
+      - '.github/workflows/odbc-package.yml'
+  pull_request:
+    paths:
+      - 'iotdb-client/odbc/**'
+      - 'iotdb-client/client-cpp/**'
+      - 'iotdb-protocol/**/thrift/**'
+      - '.github/scripts/*odbc*'
+      - '.github/scripts/native-linux-env.sh'
+      - '.github/workflows/odbc-package.yml'
+jobs:
+  linux:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - name: Build and check glibc baseline
+        run: |
+          source .github/scripts/native-linux-env.sh
+          docker run --rm -v "$PWD:/workspace" -w /workspace "${NATIVE_LINUX_IMAGE}" \
+            bash .github/scripts/package-odbc-manylinux228.sh
+      - name: Restore ownership
+        if: always()
+        run: sudo chown -R "$(id -u):$(id -g)" iotdb-client/odbc/target iotdb-client/client-cpp/third-party
+      - uses: actions/upload-artifact@v7
+        with:
+          name: odbc-linux-x86_64-glibc2.28
+          path: iotdb-client/odbc/target/build/iotdb-odbc-*.zip*
+          if-no-files-found: error
+  windows:
+    runs-on: windows-2022
+    steps:
+      - uses: actions/checkout@v7
+      - name: Install build prerequisites
+        shell: pwsh
+        run: |
+          choco install winflexbison3 strawberryperl -y --no-progress
+          'C:\Strawberry\perl\bin' >> $env:GITHUB_PATH
+      - name: Build, test and package
+        shell: pwsh
+        run: |
+          $version = ([xml](Get-Content iotdb-client/pom.xml)).project.parent.version
+          cmake -S iotdb-client/odbc -B iotdb-client/odbc/target/build -A x64 "-DODBC_PACKAGE_VERSION=$version" -DODBC_PACKAGE_CLASSIFIER=windows-x86_64
+          if ($LASTEXITCODE) { exit $LASTEXITCODE }
+          cmake --build iotdb-client/odbc/target/build --config Release --parallel 4
+          if ($LASTEXITCODE) { exit $LASTEXITCODE }
+          ctest --test-dir iotdb-client/odbc/target/build -C Release --output-on-failure
+          if ($LASTEXITCODE) { exit $LASTEXITCODE }
+          & iotdb-client/odbc/test/check-windows-dependencies.ps1 iotdb-client/odbc/target/build/Release/apache_iotdb_odbc.dll
+          Push-Location iotdb-client/odbc/target/build
+          cpack -C Release
+          if ($LASTEXITCODE) { exit $LASTEXITCODE }
+          Pop-Location
+      - uses: actions/upload-artifact@v7
+        with:
+          name: odbc-windows-x86_64
+          path: iotdb-client/odbc/target/build/iotdb-odbc-*.zip*
+          if-no-files-found: error
+  linux-runtime:
+    needs: linux
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        image: ['almalinux:8', 'ubuntu:22.04', 'ubuntu:24.04']
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: odbc-linux-x86_64-glibc2.28
+          path: artifacts
+      - name: Extract release
+        run: unzip -q artifacts/*.zip -d package
+      - name: Load with system ODBC manager in a clean runtime
+        run: |
+          docker run --rm -v "$PWD/package:/package:ro" '${{ matrix.image }}' sh -ec '
+            if command -v dnf >/dev/null; then
+              dnf install -y unixODBC
+            else
+              apt-get update && apt-get install -y --no-install-recommends unixodbc
+            fi
+            pkg=$(find /package -mindepth 1 -maxdepth 1 -type d)
+            "$pkg/test/odbc_manager" "$pkg/lib/libapache_iotdb_odbc.so"
+          '
+  server:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-java@v5
+        with:
+          distribution: corretto
+          java-version: 17
+          cache: maven
+      - name: Check ODBC source formatting
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y clang-format-17
+          sudo update-alternatives --install /usr/bin/clang-format clang-format /usr/bin/clang-format-17 100
+          sudo update-alternatives --set clang-format /usr/bin/clang-format-17
+          ./mvnw -B -P with-odbc -pl iotdb-client/odbc spotless:check
+      - name: Build disposable test server
+        run: ./mvnw -B clean package -pl distribution -am -DskipTests
+      - uses: actions/upload-artifact@v7
+        with:
+          name: odbc-test-server
+          path: distribution/target/apache-iotdb-*-all-bin.zip
+          if-no-files-found: error
+  server-runtime:
+    needs: [linux, windows, server]
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            artifact: odbc-linux-x86_64-glibc2.28
+          - os: windows-2022
+            artifact: odbc-windows-x86_64
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-java@v5
+        with:
+          distribution: corretto
+          java-version: 17
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.13'
+      - uses: actions/download-artifact@v8
+        with:
+          name: ${{ matrix.artifact }}
+          path: artifacts/driver
+      - uses: actions/download-artifact@v8
+        with:
+          name: odbc-test-server
+          path: artifacts/server
+      - name: Install runtime ODBC manager
+        if: runner.os == 'Linux'
+        run: sudo apt-get update && sudo apt-get install -y unixodbc lsof
+      - name: Extract packages
+        shell: pwsh
+        run: |
+          Expand-Archive (Get-ChildItem artifacts/driver/*.zip).FullName package/driver
+          Expand-Archive (Get-ChildItem artifacts/server/*.zip).FullName package/server
+      - name: Test real server and application consumers
+        shell: pwsh
+        env:
+          IOTDB_TEST_PASSWORD: root
+        run: |
+          $package = (Get-ChildItem package/driver -Directory).FullName
+          $server = (Get-ChildItem package/server -Directory).FullName
+          if ($IsWindows) {
+            python iotdb-client/odbc/test/run_e2e.py "$package/test/odbc_manager.exe" "$package/bin/apache_iotdb_odbc.dll" $server --windows-consumers
+          } else {
+            chmod +x "$package/test/odbc_manager"
+            Get-ChildItem "$server/sbin/*.sh" | ForEach-Object { chmod +x $_.FullName }
+            python iotdb-client/odbc/test/run_e2e.py "$package/test/odbc_manager" "$package/lib/libapache_iotdb_odbc.so" $server
+          }
+          if ($LASTEXITCODE) { exit $LASTEXITCODE }