ci(python): expand driver compatibility coverage (#795)

* ci(python): expand driver compatibility coverage

* ci(python): resolve latest driver dynamically

Author: youngsofun

.github/workflows/bindings.python.yml

@@ -193,6 +193,15 @@ jobs:
         with:
           python-version: "3.13"
 
+      - name: Resolve Databend version
+        id: databend-version
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          version=$(gh api repos/databendlabs/databend/releases --jq '[.[] | select(.draft | not) | select(.tag_name | endswith("-nightly"))][0].tag_name')
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+          echo "Running compatibility tests with Databend version: **$version**" >> "$GITHUB_STEP_SUMMARY"
+
       - uses: wntrblm/nox@2025.05.01
       - name: Download artifact
         uses: actions/download-artifact@v4
@@ -201,3 +210,6 @@ jobs:
           path: bindings/python/dist
       - name: Run Nox
         run: nox -f tests/nox/noxfile.py
+        env:
+          DATABEND_META_VERSION: ${{ steps.databend-version.outputs.version }}
+          DATABEND_QUERY_VERSION: ${{ steps.databend-version.outputs.version }}

AGENTS.md

@@ -29,6 +29,13 @@ This repository is a Rust workspace for BendSQL plus a separate frontend, langua
   Format: `type(scope): description` or `type: description`.
   Allowed types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert`.
 
+## Python Binding Compatibility Tests
+
+- Databend CI can run the latest Python binding tests against older driver versions, and BendSQL keeps a similar compatibility matrix so failures are caught here without blocking the main Databend repository.
+- When adding or changing tests in `bindings/python/tests/**/steps/binding.py`, guard queries, API usage, and assertions that depend on a particular driver or server version with the existing `DRIVER_VERSION` and/or `DB_VERSION` checks. Refer to the existing uses of these variables in the `binding.py` files: execute only the version-dependent portion when the tested version supports it, while leaving version-independent coverage unconditional.
+- Keep the `latest` entry in the `new_test_with_old_drivers` matrix in `tests/nox/noxfile.py`; it installs the unpinned `databend-driver` release and resolves its concrete version for test gating. Representative older versions may be rotated, but `latest` must not be omitted or replaced with a pinned version.
+- Set each version boundary to the first release that supports the behavior. Do not make the older-driver/newer-test compatibility jobs require behavior that is only available in newer driver or server releases.
+
 ## Task Routing
 
 - Rust behavior, CLI flags, REPL, output, or public Rust API changes: read `agents/rust-workspace.md`

bindings/python/tests/asyncio/steps/binding.py

@@ -24,7 +24,11 @@
 tc = unittest.TestCase()
 
 os.environ["DATABEND_DRIVER_HEARTBEAT_INTERVAL_SECONDS"] = "1"
-os.environ["RUST_LOG"] = "warn,databend_driver=debug,databend_client=debug"
+os.environ.setdefault(
+    "RUST_LOG",
+    "warn",
+)
+os.environ.setdefault("RUST_BACKTRACE", "1")
 import databend_driver
 
 NOW = int(time.time())
@@ -265,6 +269,11 @@ async def _(context):
 
 
 async def test_load_file(context, load_method):
+    # The load method argument replaced format_options/copy_options in v0.28.0.
+    if DRIVER_VERSION < (0, 28, 0):
+        print("SKIP: load_file method requires driver >= 0.28.0")
+        return
+
     if DRIVER_VERSION >= (0, 28, 3) and DB_VERSION >= (1, 2, 792):
         await context.conn.exec("CREATE OR REPLACE DATABASE db1")
         await context.conn.exec("use db1")

bindings/python/tests/blocking/steps/binding.py

@@ -25,7 +25,11 @@
 from behave import given, when, then
 
 os.environ["DATABEND_DRIVER_HEARTBEAT_INTERVAL_SECONDS"] = "1"
-os.environ["RUST_LOG"] = "warn,databend_driver=debug,databend_client=debug"
+os.environ.setdefault(
+    "RUST_LOG",
+    "warn",
+)
+os.environ.setdefault("RUST_BACKTRACE", "1")
 import databend_driver
 
 NOW = int(time.time())
@@ -115,9 +119,11 @@ def _(context):
     row = context.conn.query_row("select to_binary('xyz')")
     assert row.values() == (b"xyz",), f"Binary: {row.values()}"
 
-    # Interval
-    row = context.conn.query_row("select to_interval('1 microseconds')")
-    assert row.values() == (timedelta(microseconds=1),), f"Interval: {row.values()}"
+    # Older drivers decode a one-microsecond interval as one millisecond.
+    if DRIVER_VERSION >= (0, 28, 0):
+        # Interval
+        row = context.conn.query_row("select to_interval('1 microseconds')")
+        assert row.values() == (timedelta(microseconds=1),), f"Interval: {row.values()}"
 
     # Decimal
     row = context.conn.query_row("SELECT 15.7563::Decimal(8,4), 2.0+3.0", params=[8, 4])
@@ -310,6 +316,11 @@ def _(context):
 
 
 def test_load_file(context, load_method):
+    # The load method argument replaced format_options/copy_options in v0.28.0.
+    if DRIVER_VERSION < (0, 28, 0):
+        print("SKIP: load_file method requires driver >= 0.28.0")
+        return
+
     if DRIVER_VERSION >= (0, 28, 3) and DB_VERSION >= (1, 2, 792):
         context.conn.exec("CREATE OR REPLACE DATABASE db1")
         context.conn.exec("use db1")

bindings/python/tests/cursor/steps/binding.py

@@ -21,7 +21,11 @@
 from behave import given, when, then
 
 os.environ["DATABEND_DRIVER_HEARTBEAT_INTERVAL_SECONDS"] = "1"
-os.environ["RUST_LOG"] = "warn,databend_driver=debug,databend_client=debug"
+os.environ.setdefault(
+    "RUST_LOG",
+    "warn",
+)
+os.environ.setdefault("RUST_BACKTRACE", "1")
 import databend_driver
 
 NOW = int(time.time())

tests/nox/noxfile.py

@@ -15,6 +15,8 @@
 import nox
 import os
 
+LATEST_DRIVER = "latest"
+
 
 def generate_params1():
     for db_version in ["1.2.803", "1.2.791"]:
@@ -49,19 +51,29 @@ def new_driver_with_old_servers(session, db_version, query_result_format):
 
 
 def generate_params2():
-    for driver_version in ["0.28.2", "0.28.1"]:
+    for driver_version in ["0.27.6", "0.33.6", "0.34.0", LATEST_DRIVER]:
         for query_result_format in ["arrow", "json"]:
-            v = tuple(map(int, driver_version.split(".")))
-            if query_result_format == "arrow" and v <= (0, 30, 3):
-                continue
+            if driver_version != LATEST_DRIVER:
+                v = tuple(map(int, driver_version.split(".")))
+                if query_result_format == "arrow" and v <= (0, 30, 3):
+                    continue
             yield nox.param(driver_version, query_result_format)
 
 
 @nox.session
 @nox.parametrize(["driver_version", "query_result_format"], generate_params2())
 def new_test_with_old_drivers(session, driver_version, query_result_format):
     session.install("behave")
-    session.install(f"databend-driver=={driver_version}")
+    if driver_version == LATEST_DRIVER:
+        session.install("databend-driver")
+        driver_version = session.run(
+            "python",
+            "-c",
+            "from importlib.metadata import version; print(version('databend-driver'))",
+            silent=True,
+        ).strip()
+    else:
+        session.install(f"databend-driver=={driver_version}")
     with session.chdir(".."):
         env = {
             "DRIVER_VERSION": driver_version,