fix: support current seekdb embedded binding

.github/embedded-source.json

@@ -0,0 +1,8 @@
+{
+  "seekdb_repository": "https://github.com/cms-cms/seekdb.git",
+  "seekdb_sha": "b255464c3df78d1b8f769bcb71448e5737940fcc",
+  "bindings_sha": "5e8eece63205dccfa9500f98893c91d1f50eb4f1",
+  "fix_commit": "48b80f5193bcac0afafba4d4820aebdf1103bc69",
+  "platform": "linux-x86_64",
+  "python": "3.11"
+}

.github/scripts/build-embedded-wheel.sh

@@ -0,0 +1,83 @@
+#!/usr/bin/env bash
+# CI-local Linux wheel: not a portable manylinux release or a PyPI publication.
+set -Eeuo pipefail
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+: "${RUNNER_TEMP:?use an isolated GitHub runner temporary directory}"
+: "${EMBEDDED_WHEEL_DIR:?wheel output/cache directory is required}"
+[[ "$(uname -s)/$(uname -m)" == Linux/x86_64 ]]
+PYTHON="$(command -v python3)"
+"$PYTHON" -c 'import sys; assert sys.version_info[:2] == (3, 11)'
+read -r SEEKDB_REPOSITORY SEEKDB_SHA BINDINGS_SHA FIX_COMMIT < <(
+  "$PYTHON" -c 'import json, sys; p=json.load(open(sys.argv[1])); print(p["seekdb_repository"], p["seekdb_sha"], p["bindings_sha"], p["fix_commit"])' \
+    "$REPO_ROOT/.github/embedded-source.json"
+)
+[[ "$SEEKDB_REPOSITORY" == "https://github.com/cms-cms/seekdb.git" ]]
+[[ "$SEEKDB_SHA" =~ ^[0-9a-f]{40}$ && "$BINDINGS_SHA" =~ ^[0-9a-f]{40}$ && "$FIX_COMMIT" =~ ^[0-9a-f]{40}$ ]]
+BUILD_ROOT="$(mktemp -d "$RUNNER_TEMP/embedded-source.XXXXXX")"
+mkdir -p "$EMBEDDED_WHEEL_DIR"
+[[ -z "$(ls -A "$EMBEDDED_WHEEL_DIR")" ]] || { echo 'refusing to overwrite wheel evidence' >&2; exit 1; }
+
+checkout_exact() {
+  local repository="$1" revision="$2" target="$3"
+  git init -q "$target"
+  git -C "$target" remote add origin "$repository"
+  git -C "$target" config remote.origin.promisor true
+  git -C "$target" config remote.origin.partialclonefilter blob:none
+  # Full ancestry is needed to prove the kernel contains the required fix.
+  # Historical source blobs are not: fetch them lazily for the exact checkout.
+  git -C "$target" fetch --filter=blob:none --no-tags origin "$revision"
+  git -C "$target" checkout --detach FETCH_HEAD
+  [[ "$(git -C "$target" rev-parse HEAD)" == "$revision" ]]
+}
+checkout_exact "$SEEKDB_REPOSITORY" "$SEEKDB_SHA" "$BUILD_ROOT/seekdb"
+git -C "$BUILD_ROOT/seekdb" merge-base --is-ancestor "$FIX_COMMIT" HEAD
+checkout_exact https://github.com/oceanbase/seekdb-bindings.git "$BINDINGS_SHA" "$BUILD_ROOT/bindings"
+git -C "$BUILD_ROOT/bindings" submodule update --init --depth=1 deps/mariadb-connector-c
+
+# Match the upstream seekdb-bindings Ubuntu source-build recipe. These are
+# packaging/client tools, not dependencies of the seekdb compilation target.
+DEP_PROFILE="$BUILD_ROOT/seekdb/deps/init/oceanbase.el9.x86_64.deps"
+sed -i -E '/^[^#]*(target=(obshell|obdeploy)|(lib)?obclient-)/d' "$DEP_PROFILE"
+
+# Install the source's exact Rust toolchain once, before parallel compilation;
+# never let two Rust targets race while auto-installing the same components.
+RUST_TOOLCHAIN="$("$PYTHON" -c 'import sys,tomllib; print(tomllib.load(open(sys.argv[1],"rb"))["toolchain"]["channel"])' \
+  "$BUILD_ROOT/seekdb/rust/rust-toolchain.toml")"
+[[ "$RUST_TOOLCHAIN" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]
+export RUSTUP_HOME="$BUILD_ROOT/rustup" CARGO_HOME="$BUILD_ROOT/cargo"
+rustup toolchain install "$RUST_TOOLCHAIN" --profile minimal --no-self-update
+export RUSTUP_TOOLCHAIN="$RUST_TOOLCHAIN" RUSTUP_AUTO_INSTALL=0
+rustup run "$RUST_TOOLCHAIN" cargo --version
+BUILD_JOBS="$(nproc)"
+(( BUILD_JOBS <= 3 )) || BUILD_JOBS=3
+MEMORY_JOBS="$(awk '/MemTotal:/ {n=int(($2/1024-3072)/4096); print (n>0?n:1)}' /proc/meminfo)"
+(( BUILD_JOBS <= MEMORY_JOBS )) || BUILD_JOBS="$MEMORY_JOBS"
+export CMAKE_BUILD_PARALLEL_LEVEL="$BUILD_JOBS" CARGO_BUILD_JOBS="$BUILD_JOBS"
+(
+  cd "$BUILD_ROOT/seekdb"
+  ./build.sh release --init -DBUILD_EMBED_MODE=ON --make -j"$BUILD_JOBS"
+)
+mapfile -t binaries < <(find "$BUILD_ROOT/seekdb/build_release" -type f -name seekdb -executable)
+[[ "${#binaries[@]}" == 1 ]]
+SEEKDB_BIN="${binaries[0]}"
+strip --strip-debug --strip-unneeded "$SEEKDB_BIN"
+"$SEEKDB_BIN" -V 2>&1 | tee "$EMBEDDED_WHEEL_DIR/seekdb-version.txt"
+grep -F "$SEEKDB_SHA" "$EMBEDDED_WHEEL_DIR/seekdb-version.txt"
+
+# Do not call the upstream wheel target (it selects an unqualified `python`).
+# Build only the driver, then build a CPython 3.11 wheel with this exact venv.
+"$PYTHON" -m venv "$BUILD_ROOT/venv"
+BUILD_PYTHON="$BUILD_ROOT/venv/bin/python"
+"$BUILD_PYTHON" -m pip install --disable-pip-version-check \
+  'pip==25.3' 'build==1.3.0' 'cmake==3.31.6' 'nanobind==3.0.0' 'scikit-build-core==0.11.6' 'ninja==1.11.1.4'
+export PATH="$BUILD_ROOT/venv/bin:$PATH"
+cmake -S "$BUILD_ROOT/bindings" -B "$BUILD_ROOT/bindings/build" \
+  -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTING=OFF -DSEEKDB_BUILD_PYTHON=OFF \
+  -DSEEKDB_BIN="$SEEKDB_BIN"
+cmake --build "$BUILD_ROOT/bindings/build" --target seekdb --parallel "$BUILD_JOBS"
+"$BUILD_PYTHON" -m pip wheel --no-deps --no-build-isolation \
+  --config-settings="cmake.define.Python_EXECUTABLE=$BUILD_PYTHON" \
+  --config-settings="cmake.define.Python_FIND_VIRTUALENV=ONLY" \
+  --wheel-dir "$EMBEDDED_WHEEL_DIR" "$BUILD_ROOT/bindings/python"
+"$PYTHON" "$REPO_ROOT/.github/scripts/embedded_wheel_manifest.py" create \
+  "$REPO_ROOT/.github/embedded-source.json" "$EMBEDDED_WHEEL_DIR" "$SEEKDB_BIN"

.github/scripts/embedded_wheel_manifest.py

@@ -0,0 +1,75 @@
+"""Bind a CI-local wheel to pinned sources and verify the installed payload."""
+
+import hashlib
+import importlib.metadata
+import json
+import platform
+import subprocess
+import sys
+import zipfile
+from pathlib import Path
+
+
+def digest(path):
+    with path.open("rb") as stream:
+        return hashlib.file_digest(stream, "sha256").hexdigest()
+
+
+def wheel_payload(wheel):
+    with zipfile.ZipFile(wheel) as archive, archive.open("pylibseekdb/seekdb") as stream:
+        return hashlib.file_digest(stream, "sha256").hexdigest()
+
+
+def verify(pin, directory):
+    manifest = json.loads((directory / "manifest.json").read_text())
+    if manifest["source"] != pin:
+        raise ValueError("cached wheel source identity mismatch")
+    if platform.system() != "Linux" or platform.machine() != "x86_64" or sys.version_info[:2] != (3, 11):
+        raise ValueError("wheel requires Linux x86_64 CPython 3.11")
+    wheels = list(directory.glob("*.whl"))
+    if len(wheels) != 1 or wheels[0].name != manifest["wheel"]:
+        raise ValueError("expected exactly the manifest wheel")
+    if digest(wheels[0]) != manifest["wheel_sha256"]:
+        raise ValueError("wheel checksum mismatch")
+    if wheel_payload(wheels[0]) != manifest["binary_sha256"]:
+        raise ValueError("wheel contains a different SeekDB binary")
+    version = (directory / "seekdb-version.txt").read_text()
+    if pin["seekdb_sha"] not in version or version != manifest["revision_output"]:
+        raise ValueError("SeekDB full REVISION mismatch")
+    return manifest
+
+
+def main():
+    mode, pin_path, directory_name, *rest = sys.argv[1:]
+    pin = json.loads(Path(pin_path).read_text())
+    directory = Path(directory_name)
+    if mode == "create":
+        (binary_name,) = rest
+        (wheel,) = directory.glob("*.whl")
+        manifest = {
+            "source": pin,
+            "wheel": wheel.name,
+            "wheel_sha256": digest(wheel),
+            "binary_sha256": digest(Path(binary_name)),
+            "revision_output": (directory / "seekdb-version.txt").read_text(),
+        }
+        (directory / "manifest.json").write_text(json.dumps(manifest, indent=2) + "\n")
+    elif mode not in {"verify", "installed"}:
+        raise ValueError(f"unknown verification mode: {mode}")
+    manifest = verify(pin, directory)
+    if mode == "installed":
+        binary = Path(importlib.metadata.distribution("pylibseekdb").locate_file("pylibseekdb/seekdb"))
+        if digest(binary) != manifest["binary_sha256"]:
+            raise ValueError("installed SeekDB differs from source-built wheel (dependency resync?)")
+        # The executable is the verified local wheel payload, never shell input.
+        version = subprocess.check_output(  # noqa: S603
+            [str(binary), "-V"], text=True, stderr=subprocess.STDOUT
+        )
+        if pin["seekdb_sha"] not in version:
+            raise ValueError("installed SeekDB does not report pinned full REVISION")
+        print(f"[EMBEDDED_WHEEL] installed={binary}")
+    print(json.dumps(manifest, indent=2))
+
+
+if __name__ == "__main__":
+    main()

.github/workflows/ci.yml

@@ -100,7 +100,11 @@ jobs:
           bash .github/scripts/check-pytest-summary.sh pytest.log
 
   integration-test:
-    runs-on: ubuntu-latest
+    # Build and test the CI-local embedded wheel on the same native image.
+    runs-on: ${{ matrix.test_mode == 'embedded' && 'ubuntu-22.04' || 'ubuntu-latest' }}
+    timeout-minutes: 180
+    env:
+      EMBEDDED_WHEEL_DIR: ${{ github.workspace }}/.embedded-wheel
     strategy:
       fail-fast: false  # Allow other jobs to continue if one fails
       matrix:
@@ -137,6 +141,53 @@ jobs:
         with:
           python-version: '3.11'
 
+      - name: Restore exact embedded source wheel
+        if: matrix.test_mode == 'embedded'
+        id: embedded-wheel
+        uses: actions/cache/restore@v4
+        with:
+          path: .embedded-wheel
+          # Never reuse a wheel built from another source or build recipe.
+          key: embedded-source-ubuntu22-x86_64-cp311-${{ hashFiles('.github/embedded-source.json', '.github/scripts/build-embedded-wheel.sh', '.github/scripts/embedded_wheel_manifest.py') }}
+
+      - name: Install embedded source build dependencies
+        if: matrix.test_mode == 'embedded' && steps.embedded-wheel.outputs.cache-hit != 'true'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y git wget rpm rpm2cpio cpio make build-essential binutils m4 libtool-bin libncurses5 libaio1 libssl-dev zlib1g-dev
+
+      - name: Build embedded wheel from pinned fixed sources
+        if: matrix.test_mode == 'embedded' && steps.embedded-wheel.outputs.cache-hit != 'true'
+        run: bash .github/scripts/build-embedded-wheel.sh
+
+      - name: Verify and install the exact embedded source wheel
+        if: matrix.test_mode == 'embedded'
+        run: |
+          set -euo pipefail
+          sudo apt-get update
+          sudo apt-get install -y libaio1
+          python .github/scripts/embedded_wheel_manifest.py verify .github/embedded-source.json "$EMBEDDED_WHEEL_DIR"
+          uv pip install --python .venv/bin/python --no-deps --reinstall "$EMBEDDED_WHEEL_DIR"/*.whl
+          .venv/bin/python .github/scripts/embedded_wheel_manifest.py installed .github/embedded-source.json "$EMBEDDED_WHEEL_DIR"
+
+      - name: Save verified embedded source wheel
+        if: matrix.test_mode == 'embedded' && steps.embedded-wheel.outputs.cache-hit != 'true'
+        uses: actions/cache/save@v4
+        with:
+          path: .embedded-wheel
+          key: ${{ steps.embedded-wheel.outputs.cache-primary-key }}
+
+      - name: Record embedded wheel provenance
+        if: matrix.test_mode == 'embedded'
+        uses: actions/upload-artifact@v4
+        with:
+          name: embedded-wheel-provenance
+          include-hidden-files: true
+          path: |
+            .embedded-wheel/manifest.json
+            .embedded-wheel/seekdb-version.txt
+          if-no-files-found: error
+
       - name: Start OceanBase container
         if: matrix.test_mode == 'oceanbase'
         uses: oceanbase/setup-oceanbase-ce@v1
@@ -171,10 +222,23 @@ jobs:
             log_level=INFO
           fi
           set -o pipefail
-          uv run pytest tests/integration_tests/ -v --log-cli-level=${log_level} \
+          # Keep the verified source wheel; a normal uv sync would reinstall
+          # the released pylibseekdb from uv.lock.
+          uv run --no-sync pytest tests/integration_tests/ -v --log-cli-level=${log_level} \
             -k "${{ matrix.test_mode }}" | tee pytest.log
           bash .github/scripts/check-pytest-summary.sh pytest.log
 
+      - name: Upload embedded database diagnostics
+        if: always() && matrix.test_mode == 'embedded'
+        uses: actions/upload-artifact@v4
+        with:
+          name: embedded-database-diagnostics
+          include-hidden-files: true
+          path: |
+            .seekdb-test-data/
+            pytest.log
+          if-no-files-found: warn
+
       - name: Run examples for ${{ matrix.test_mode }}
         env:
           MODE: ${{ matrix.test_mode }}

src/pyseekdb/client/__init__.py

@@ -12,7 +12,7 @@
 - Returns: _AdminClientProxy (database operations only)
 
 All factories use the underlying ServerAPI implementations:
-- SeekdbEmbeddedClient - Local seekdb (requires pylibseekdb, Linux only)
+- SeekdbEmbeddedClient - Local seekdb (requires seekdb or legacy pylibseekdb)
 - RemoteServerClient - Remote server via pymysql (supports both seekdb Server and OceanBase Server)
 """
 
@@ -136,7 +136,7 @@ def _create_server_client(
         return SeekdbEmbeddedClient(path=default_path, database=database, **kwargs)
 
     raise ValueError(
-        "Default embedded mode is not available because pylibseekdb could not be imported. "
+        "Default embedded mode is not available because a SeekDB Python binding could not be imported. "
         "Please provide host/port parameters to use RemoteServerClient."
     )
 
@@ -145,7 +145,7 @@ def __getattr__(name: str) -> Any:
     """
     Lazily expose optional embedded client symbols.
 
-    This avoids importing pylibseekdb during `import pyseekdb`, which can crash
+    This avoids importing a native embedded binding during `import pyseekdb`, which can crash
     on unsupported interpreter/platform combinations (e.g. some Python 3.14 CI environments).
     """
     if name == "SeekdbEmbeddedClient":

src/pyseekdb/client/client_seekdb_embedded.py

@@ -1,8 +1,9 @@
 """
 Embedded mode client - based on seekdb
-Note: Only available when pylibseekdb is installed (Linux only)
+Available when the current ``seekdb`` binding or legacy ``pylibseekdb`` is installed.
 """
 
+import importlib
 import logging
 import os
 import threading
@@ -12,25 +13,30 @@
 import pymysql
 from pymysql.cursors import DictCursor
 
-# Try to import pylibseekdb - it may not be available on all platforms
-try:
-    import pylibseekdb as seekdb  # type: ignore[import-not-found]
-
-    _PYLIBSEEKDB_AVAILABLE = True
-except ImportError:
-    seekdb = None  # type: ignore[assignment]
-    _PYLIBSEEKDB_AVAILABLE = False
-
 from .admin_client import DEFAULT_TENANT
 from .client_base import BaseClient
 from .database import Database
 from .sql_utils import render_sql_with_params
 
+
+def _load_embedded_runtime() -> tuple[Any | None, str | None]:
+    """Prefer the current ``seekdb`` binding, with legacy compatibility."""
+    for distribution in ("seekdb", "pylibseekdb"):
+        try:
+            return importlib.import_module(distribution), distribution
+        except ImportError:
+            pass
+    return None, None
+
+
+seekdb, _EMBEDDED_RUNTIME_DISTRIBUTION = _load_embedded_runtime()
+_PYLIBSEEKDB_AVAILABLE = seekdb is not None
+
 logger = logging.getLogger(__name__)
 
 
 class _NativeEmbeddedBackend:
-    """Connect through pylibseekdb's native Python connection wrapper."""
+    """Connect through the embedded binding's native connection wrapper."""
 
     supports_dbapi_cursor = False
 
@@ -54,7 +60,7 @@ class _PyMySQLEmbeddedBackend:
     @staticmethod
     def connect(instance: Any, database: str, connection_kwargs: dict[str, Any]) -> pymysql.Connection:
         if instance is None:
-            raise RuntimeError("pylibseekdb returned no SeekdbInstance for a PyMySQL embedded connection")
+            raise RuntimeError("the embedded binding returned no SeekdbInstance for a PyMySQL connection")
 
         options = dict(instance.connection_options())
         kwargs = dict(connection_kwargs)
@@ -80,7 +86,7 @@ def is_connection_open(connection: Any) -> bool:
 
 
 def _create_embedded_backend() -> _NativeEmbeddedBackend | _PyMySQLEmbeddedBackend:
-    """Select the safest connection backend from pylibseekdb's capabilities."""
+    """Select the safest connection backend exposed by the installed binding."""
     instance_type = getattr(seekdb, "SeekdbInstance", None)
     if instance_type is not None and callable(getattr(instance_type, "connection_options", None)):
         return _PyMySQLEmbeddedBackend()
@@ -90,7 +96,7 @@ def _create_embedded_backend() -> _NativeEmbeddedBackend | _PyMySQLEmbeddedBacke
 class SeekdbEmbeddedClient(BaseClient):
     """Embedded seekdb client (lazy connection)
 
-    Note: Only available on Linux platforms. pylibseekdb dependency is Linux-only.
+    Availability follows the installed embedded binding and its supported platform.
     """
 
     def __init__(self, path: str = "./seekdb.db", database: str = "test", **kwargs):
@@ -102,13 +108,13 @@ def __init__(self, path: str = "./seekdb.db", database: str = "test", **kwargs):
             database: database name
 
         Raises:
-            RuntimeError: If pylibseekdb is not available
+            RuntimeError: If no embedded binding is available
         """
-        # Check if pylibseekdb is available
+        # Check if an embedded binding is available.
         if not _PYLIBSEEKDB_AVAILABLE or seekdb is None:
             raise RuntimeError(
-                "Embedded Client is not available because pylibseekdb is not available. "
-                "Please install pylibseekdb (Linux only) or use RemoteServerClient (host/port) instead."
+                "Embedded Client is not available because no SeekDB Python binding was found. "
+                "Please install seekdb (or legacy pylibseekdb), or use RemoteServerClient (host/port) instead."
             )
 
         self.path = os.path.abspath(path)
@@ -169,7 +175,7 @@ def _ensure_connection(self) -> Any:
             return self._connection
 
     def _cleanup(self) -> None:
-        """Close the connection and its owning pylibseekdb instance."""
+        """Close the connection and its owning embedded runtime instance."""
         with self._connection_lock:
             connection = self._connection
             instance = self._instance