databricks-sql-connector 4.2.6__tar.gz → 4.3.0__tar.gz

{databricks_sql_connector-4.2.6 → databricks_sql_connector-4.3.0}/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Release History
 
+# 4.3.0 (2026-06-12)
+- **New: optional Rust kernel backend (`use_kernel=True`).** Adds an alternative connection path backed by the native [`databricks-sql-kernel`](https://pypi.org/project/databricks-sql-kernel/) client (a Rust core exposed via PyO3), installable with the new `databricks-sql-connector[kernel]` extra. The kernel talks to Databricks over the **SEA (Statement Execution API) HTTP transport** — not Thrift — with CloudFetch and inline-Arrow result fetching, so `use_kernel=True` gives you a modern SEA-native client through the same DB-API surface. Supports PAT, OAuth M2M, and OAuth U2M auth. Requires Python >= 3.10 (the kernel wheel is `cp310-abi3`); on older interpreters the extra is a no-op and `use_kernel=True` raises a clear `ImportError`. The default backend remains Thrift — opt in per connection.
+- Kernel backend behavior is aligned with the Thrift backend so application code works the same either way: consistent cursor-state tracking (`query_id` / `get_query_state`), metadata (catalogs/schemas/tables/columns with JDBC-style filter semantics and case-insensitive `table_types`), DML `rowcount`, server-sourced async execution state, sync `cancel()`, fail-loud staging/volume operations, and structured error context (SQLSTATE, diagnostic info). Kernel logs surface through Python `logging` under the `databricks.sql.kernel` logger (databricks/databricks-sql-python#824, #825, #830, #838, #839 by @vikrantpuppala)
+- Revert the thrift 0.23.0 bump that broke installation on DBR LTS (ES-1960554) (databricks/databricks-sql-python#840 by @vikrantpuppala)
+
+# 4.2.7 (2026-06-02)
+- Extract SPOG org-id from cluster http_path for non-Thrift requests (databricks/databricks-sql-python#817 by @msrathore-db)
+- Remove empty chunks in CloudFetch concatenation (databricks/databricks-sql-python#814 by @jprakash-db)
+- Add `_retry_server_directed_only` mode for Retry-After header compliance (databricks/databricks-sql-python#756 by @sd-db)
+- Bump thrift to 0.23.0 (databricks/databricks-sql-python#796 by @leoromanovsky)
+- Allow pandas 3.x in dependency constraints (databricks/databricks-sql-python#768 by @moomindani)
+- Telemetry: unwrap TokenFederationProvider to report inner auth mechanism/flow (databricks/databricks-sql-python#781 by @samikshya-db)
+
 # 4.2.6 (2026-04-22)
 - Add SPOG routing support for account-level vanity URLs (databricks/databricks-sql-python#767 by @msrathore-db)
 - Fix dependency_manager: handle PEP 440 ~= compatible release syntax (databricks/databricks-sql-python#776 by @vikrantpuppala)

{databricks_sql_connector-4.2.6 → databricks_sql_connector-4.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: databricks-sql-connector
-Version: 4.2.6
+Version: 4.3.0
 Summary: Databricks SQL Connector for Python
 License: Apache-2.0
 License-File: LICENSE
@@ -16,14 +16,17 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Provides-Extra: kernel
 Provides-Extra: pyarrow
+Requires-Dist: databricks-sql-kernel (>=0.2.0,<0.3.0) ; (python_version >= "3.10") and (extra == "kernel")
 Requires-Dist: lz4 (>=4.0.2,<5.0.0) ; python_version >= "3.8" and python_version < "3.14"
 Requires-Dist: lz4 (>=4.4.5,<5.0.0) ; python_version >= "3.14"
 Requires-Dist: oauthlib (>=3.1.0,<4.0.0)
 Requires-Dist: openpyxl (>=3.0.10,<4.0.0)
-Requires-Dist: pandas (>=1.2.5,<2.4.0) ; python_version >= "3.8" and python_version < "3.13"
-Requires-Dist: pandas (>=2.2.3,<2.4.0) ; python_version >= "3.13"
-Requires-Dist: pyarrow (>=14.0.1) ; (python_version >= "3.8" and python_version < "3.13") and (extra == "pyarrow")
+Requires-Dist: pandas (>=1.2.5,<4.0.0) ; python_version >= "3.8" and python_version < "3.13"
+Requires-Dist: pandas (>=2.2.3,<4.0.0) ; python_version >= "3.13"
+Requires-Dist: pyarrow (>=14.0.1) ; (python_version >= "3.10" and python_version < "3.13") and (extra == "pyarrow")
+Requires-Dist: pyarrow (>=14.0.1,<23) ; (python_version >= "3.8" and python_version < "3.10") and (extra == "pyarrow")
 Requires-Dist: pyarrow (>=18.0.0) ; (python_version == "3.13") and (extra == "pyarrow")
 Requires-Dist: pyarrow (>=22.0.0) ; (python_version >= "3.14") and (extra == "pyarrow")
 Requires-Dist: pybreaker (>=1.0.0,<2.0.0)
@@ -68,6 +71,30 @@ Install using `pip install databricks-sql-connector`
 ### Installing the core library with PyArrow
 Install using `pip install databricks-sql-connector[pyarrow]`
 
+### Installing with the Rust kernel backend (`use_kernel=True`)
+Install using `pip install databricks-sql-connector[kernel]`
+
+This adds the optional [`databricks-sql-kernel`](https://pypi.org/project/databricks-sql-kernel/)
+extension (a native Rust client core, exposed via PyO3). Pass
+`use_kernel=True` to `sql.connect(...)` to route the connection through it
+instead of the default Thrift backend:
+
+```python
+connection = sql.connect(
+  server_hostname=host,
+  http_path=http_path,
+  access_token=token,
+  use_kernel=True,
+)
+```
+
+Notes:
+- Requires **Python >= 3.10** (the kernel wheel is published as
+  `cp310-abi3`). On older interpreters the `[kernel]` extra installs
+  nothing and `use_kernel=True` raises an `ImportError`.
+- The extra also pulls in PyArrow, which the kernel result path requires.
+- Authentication supports PAT (`access_token`), OAuth M2M, and OAuth U2M.
+
 
 ```bash
 export DATABRICKS_HOST=********.databricks.com

{databricks_sql_connector-4.2.6 → databricks_sql_connector-4.3.0}/README.md

@@ -30,6 +30,30 @@ Install using `pip install databricks-sql-connector`
 ### Installing the core library with PyArrow
 Install using `pip install databricks-sql-connector[pyarrow]`
 
+### Installing with the Rust kernel backend (`use_kernel=True`)
+Install using `pip install databricks-sql-connector[kernel]`
+
+This adds the optional [`databricks-sql-kernel`](https://pypi.org/project/databricks-sql-kernel/)
+extension (a native Rust client core, exposed via PyO3). Pass
+`use_kernel=True` to `sql.connect(...)` to route the connection through it
+instead of the default Thrift backend:
+
+```python
+connection = sql.connect(
+  server_hostname=host,
+  http_path=http_path,
+  access_token=token,
+  use_kernel=True,
+)
+```
+
+Notes:
+- Requires **Python >= 3.10** (the kernel wheel is published as
+  `cp310-abi3`). On older interpreters the `[kernel]` extra installs
+  nothing and `use_kernel=True` raises an `ImportError`.
+- The extra also pulls in PyArrow, which the kernel result path requires.
+- Authentication supports PAT (`access_token`), OAuth M2M, and OAuth U2M.
+
 
 ```bash
 export DATABRICKS_HOST=********.databricks.com

databricks_sql_connector-4.3.0/pyproject.toml

@@ -0,0 +1,135 @@
+[tool.poetry]
+name = "databricks-sql-connector"
+version = "4.3.0"
+description = "Databricks SQL Connector for Python"
+authors = ["Databricks <databricks-sql-connector-maintainers@databricks.com>"]
+license = "Apache-2.0"
+readme = "README.md"
+packages = [{ include = "databricks", from = "src" }]
+include = ["CHANGELOG.md"]
+
+[tool.poetry.dependencies]
+python = "^3.8.0"
+thrift = "~=0.22.0"
+pandas = [
+    { version = ">=1.2.5,<4.0.0", python = ">=3.8,<3.13" },
+    { version = ">=2.2.3,<4.0.0", python = ">=3.13" }
+]
+lz4 = [
+    { version = "^4.0.2", python = ">=3.8,<3.14" },
+    { version = "^4.4.5", python = ">=3.14" }
+]
+requests = "^2.18.1"
+oauthlib = "^3.1.0"
+openpyxl = "^3.0.10"
+urllib3 = ">=1.26"
+python-dateutil = "^2.8.0"
+pyarrow = [
+    # The <3.10 band is capped at <23 because pyarrow>=23 dropped
+    # Python 3.9 (it requires >=3.10). Without the cap, poetry tries to
+    # unify this entry with the kernel's transitive pyarrow>=23.0.1,<24
+    # across the 3.8–3.10 slice and `poetry lock` fails ("pyarrow is
+    # forbidden"). The cap removes no installable version — the newest
+    # pyarrow with a 3.9 wheel is 21.x — it just makes that explicit to
+    # the solver so the optional [kernel] extra (python>=3.10) can
+    # coexist. See the kernel dep + [kernel] extra below.
+    { version = ">=14.0.1,<23", python = ">=3.8,<3.10", optional=true },
+    { version = ">=14.0.1", python = ">=3.10,<3.13", optional=true },
+    { version = ">=18.0.0", python = ">=3.13,<3.14", optional=true },
+    { version = ">=22.0.0", python = ">=3.14", optional=true }
+]
+pyjwt = "^2.0.0"
+pybreaker = "^1.0.0"
+requests-kerberos = {version = "^0.15.0", optional = true}
+# Optional Rust kernel backend for ``use_kernel=True`` (PyO3 wheel).
+# Pulled in only via the ``[kernel]`` extra below. The published wheel
+# is ``abi3`` with ``Requires-Python: >=3.10`` (built ``abi3-py310``),
+# so the dependency is gated to Python >= 3.10: on 3.8/3.9 the
+# ``[kernel]`` extra resolves to nothing and ``use_kernel=True`` raises
+# a clear ImportError at runtime (see backend/kernel/_errors.py).
+#
+# Floor is 0.2.0 (``^0.2.0`` == ``>=0.2.0,<0.3.0``). The kernel is
+# pre-1.0, so each 0.x minor may carry breaking changes — the ``<0.3.0``
+# cap means we bump this deliberately when the kernel ships 0.3.0 rather
+# than letting a potentially-breaking minor flow in automatically. 0.2.0
+# keeps the same Requires-Python (>=3.10) and pyarrow (>=23.0.1,<24) pin
+# as 0.1.x, so the gating below is unchanged.
+databricks-sql-kernel = {version = "^0.2.0", optional = true, python = ">=3.10"}
+
+
+[tool.poetry.extras]
+pyarrow = ["pyarrow"]
+# ``pip install databricks-sql-connector[kernel]`` adds the Rust kernel
+# backend so ``use_kernel=True`` works. No-op on Python < 3.10 (the
+# wheel's floor) — those users get a runtime ImportError if they pass
+# ``use_kernel=True``.
+#
+# The kernel result path (``backend/kernel/result_set.py``) needs
+# pyarrow, but it is NOT listed in this extra on purpose: the published
+# kernel wheel declares ``pyarrow>=23.0.1,<24`` as a hard runtime
+# dependency, so ``pip install ...[kernel]`` already pulls a compatible
+# pyarrow transitively. Listing bare ``pyarrow`` here additionally
+# forces poetry to co-resolve an unconstrained pyarrow against the
+# kernel's ``>=23.0.1,<24`` (which itself requires Python >=3.10) across
+# the connector's full 3.8–3.14 support matrix, which is unsatisfiable
+# on 3.8/3.9 and breaks ``poetry lock``. The kernel's own dependency
+# metadata is the single source of truth for the pyarrow floor.
+kernel = ["databricks-sql-kernel"]
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^7.1.2"
+mypy = "^1.10.1"
+pylint = ">=2.12.0"
+black = "^22.3.0"
+pytest-dotenv = "^0.5.2"
+pytest-cov = "^4.0.0"
+pytest-xdist = "^3.0.0"
+numpy = [
+    { version = ">=1.16.6", python = ">=3.8,<3.11" },
+    { version = ">=1.23.4", python = ">=3.11" },
+]
+
+[tool.poetry.urls]
+"Homepage" = "https://github.com/databricks/databricks-sql-python"
+"Bug Tracker" = "https://github.com/databricks/databricks-sql-python/issues"
+
+[build-system]
+requires = ["poetry-core>=1.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.mypy]
+ignore_missing_imports = "true"
+exclude = ['ttypes\.py$', 'TCLIService\.py$']
+
+[tool.black]
+exclude = '/(\.eggs|\.git|\.hg|\.mypy_cache|\.nox|\.tox|\.venv|\.svn|_build|buck-out|build|dist|thrift_api)/'
+
+[tool.pytest.ini_options]
+markers = [
+    "reviewed: Test case has been reviewed by Databricks",
+    "serial: Tests that must run serially (not parallelized)",
+    "realkernel: Requires the real databricks-sql-kernel wheel and an unpolluted sys.modules (no fake kernel stub); must run in a separate pytest invocation from tests that fake databricks_sql_kernel (deselect with -m 'not realkernel', run alone with -m realkernel).",
+]
+minversion = "6.0"
+log_cli = "false"
+log_cli_level = "INFO"
+testpaths = ["tests"]
+env_files = ["test.env"]
+
+[tool.coverage.run]
+source = ["src"]
+branch = true
+omit = [
+    "*/tests/*",
+    "*/test_*",
+    "*/__pycache__/*",
+    "*/thrift_api/*",  
+]
+
+[tool.coverage.report]
+precision = 2
+show_missing = true
+skip_covered = false
+
+[tool.coverage.xml]
+output = "coverage.xml"

{databricks_sql_connector-4.2.6 → databricks_sql_connector-4.3.0}/src/databricks/sql/__init__.py

@@ -71,7 +71,7 @@ DATETIME = DBAPITypeObject("timestamp")
 DATE = DBAPITypeObject("date")
 ROWID = DBAPITypeObject()
 
-__version__ = "4.2.6"
+__version__ = "4.3.0"
 USER_AGENT_NAME = "PyDatabricksSqlConnector"
 
 # These two functions are pyhive legacy

{databricks_sql_connector-4.2.6 → databricks_sql_connector-4.3.0}/src/databricks/sql/auth/common.py

@@ -47,6 +47,7 @@ class ClientContext:
         retry_stop_after_attempts_duration: Optional[float] = None,
         retry_delay_default: Optional[float] = None,
         retry_dangerous_codes: Optional[List[int]] = None,
+        respect_server_retry_after_header: Optional[bool] = None,
         proxy_auth_method: Optional[str] = None,
         pool_connections: Optional[int] = None,
         pool_maxsize: Optional[int] = None,
@@ -80,6 +81,7 @@ class ClientContext:
         )
         self.retry_delay_default = retry_delay_default or 5.0
         self.retry_dangerous_codes = retry_dangerous_codes or []
+        self.respect_server_retry_after_header = bool(respect_server_retry_after_header)
         self.proxy_auth_method = proxy_auth_method
         self.pool_connections = pool_connections or 10
         self.pool_maxsize = pool_maxsize or 20

{databricks_sql_connector-4.2.6 → databricks_sql_connector-4.3.0}/src/databricks/sql/auth/retry.py

@@ -94,6 +94,7 @@ class DatabricksRetryPolicy(Retry):
         stop_after_attempts_duration: float,
         delay_default: float,
         force_dangerous_codes: List[int],
+        respect_server_retry_after_header: bool = False,
         urllib3_kwargs: dict = {},
     ):
         # These values do not change from one command to the next
@@ -103,6 +104,7 @@ class DatabricksRetryPolicy(Retry):
         self.stop_after_attempts_duration = stop_after_attempts_duration
         self._delay_default = delay_default
         self.force_dangerous_codes = force_dangerous_codes
+        self.respect_server_retry_after_header = respect_server_retry_after_header
 
         # the urllib3 kwargs are a mix of configuration (some of which we override)
         # and counters like `total` or `connect` which may change between successive retries
@@ -202,6 +204,7 @@ class DatabricksRetryPolicy(Retry):
             stop_after_attempts_duration=self.stop_after_attempts_duration,
             delay_default=self.delay_default,
             force_dangerous_codes=self.force_dangerous_codes,
+            respect_server_retry_after_header=self.respect_server_retry_after_header,
             urllib3_kwargs={},
         )
 
@@ -323,7 +326,9 @@ class DatabricksRetryPolicy(Retry):
 
         return proposed_backoff
 
-    def should_retry(self, method: str, status_code: int) -> Tuple[bool, str]:
+    def should_retry(
+        self, method: str, status_code: int, has_retry_after: bool = False
+    ) -> Tuple[bool, str]:
         """This method encapsulates the connector's approach to retries.
 
         We always retry a request unless one of these conditions is met:
@@ -388,6 +393,15 @@ class DatabricksRetryPolicy(Retry):
         if not self._is_method_retryable(method):
             return False, "Only POST requests are retried"
 
+        # When respect_server_retry_after_header is enabled, only retry when the
+        # server explicitly signals it's safe via a Retry-After header. This prevents
+        # duplicate side effects for non-idempotent operations.
+        if self.respect_server_retry_after_header and not has_retry_after:
+            return (
+                False,
+                "respect_server_retry_after_header mode: no Retry-After header present",
+            )
+
         # Request failed, was an ExecuteStatement and the command may have reached the server
         if (
             self.command_type == CommandType.EXECUTE_STATEMENT
@@ -430,7 +444,7 @@ class DatabricksRetryPolicy(Retry):
         Logs a debug message if the request will be retried
         """
 
-        should_retry, msg = self.should_retry(method, status_code)
+        should_retry, msg = self.should_retry(method, status_code, has_retry_after)
 
         if should_retry:
             logger.debug(msg)

databricks_sql_connector-4.3.0/src/databricks/sql/backend/kernel/__init__.py

@@ -0,0 +1,25 @@
+"""Backend that delegates to the Databricks SQL Kernel (Rust) via PyO3.
+
+Routed when ``use_kernel=True`` is passed to ``databricks.sql.connect``.
+The module's identity is "delegates to the kernel" — not the wire
+protocol the kernel happens to use today (SEA REST). The kernel may
+switch its default transport (SEA REST → SEA gRPC → …) without
+renaming this module.
+
+This ``__init__`` deliberately does **not** re-export
+``KernelDatabricksClient`` from ``.client``. Importing ``.client``
+loads the ``databricks_sql_kernel`` PyO3 extension at module-import
+time; doing that eagerly here would make ``import
+databricks.sql.backend.kernel.type_mapping`` (used by tests / by
+``KernelResultSet`` consumers) require the kernel wheel even when
+the caller never plans to open a kernel-backed session. Callers
+that need the client import it directly:
+
+    from databricks.sql.backend.kernel.client import KernelDatabricksClient
+
+``session.py::_create_backend`` already does this lazy import under
+the ``use_kernel=True`` branch.
+
+See ``docs/designs/pysql-kernel-integration.md`` in
+``databricks-sql-kernel`` for the full integration design.
+"""

databricks_sql_connector-4.3.0/src/databricks/sql/backend/kernel/_errors.py

@@ -0,0 +1,185 @@
+"""Shared error-mapping primitives for the kernel backend.
+
+The PyO3 boundary can produce two flavours of exception:
+
+- ``databricks_sql_kernel.KernelError`` — the kernel's own
+  structured error type. Carries ``code`` / ``message`` /
+  ``sql_state`` / ``query_id`` / ``http_status`` / ``retryable`` /
+  ``vendor_code`` / ``error_code`` as attributes; mapped to a PEP
+  249 exception class via ``_CODE_TO_EXCEPTION`` with the
+  attributes forwarded onto the re-raised exception so callers can
+  branch on ``err.code`` / ``err.sql_state`` without reaching
+  through ``__cause__``.
+- Anything else — ``TypeError`` / ``OverflowError`` /
+  ``ValueError`` from PyO3 argument conversion, or arbitrary
+  extension-internal Python errors. These would otherwise propagate
+  raw to connector callers, breaking the DB-API contract that says
+  "only PEP 249 exception types cross the boundary". Wrapped in
+  ``OperationalError`` here.
+
+These primitives live in their own module so both ``client.py``
+(which orchestrates PyO3 calls) and ``result_set.py`` (which calls
+``fetch_next_batch`` on the same kernel handles) can share them
+without ``result_set.py`` importing from ``client.py``.
+
+Usage at every PyO3 call site is a plain try/except:
+
+    try:
+        stmt.execute()
+    except Exception as exc:
+        raise wrap_kernel_exception("execute_command", exc) from exc
+
+The helper returns the mapped exception; callers raise it. Plain
+``try/except`` is preferred over a context manager: the control
+flow is visible at the call site, the helper is a pure function
+(trivial to test), and tracebacks don't carry an extra
+``__exit__`` frame.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from databricks.sql.exc import (
+    DatabaseError,
+    Error,
+    OperationalError,
+    ProgrammingError,
+    ServerOperationError,
+)
+
+try:
+    import databricks_sql_kernel as _kernel  # type: ignore[import-not-found]
+except ImportError as exc:  # pragma: no cover - same hint as client.py
+    raise ImportError(
+        "use_kernel=True requires the optional databricks-sql-kernel "
+        "extension, which is not installed. Install it with:\n"
+        '  pip install "databricks-sql-connector[kernel]"\n'
+        "The kernel wheel requires Python >= 3.10; on older interpreters "
+        "use_kernel is unavailable. For local kernel development you can "
+        "instead build it from the databricks-sql-kernel repo:\n"
+        "  cd databricks-sql-kernel/pyo3 && maturin develop --release"
+    ) from exc
+
+# Route the kernel's Rust-side logs into Python's ``logging`` as soon as
+# the extension loads. The kernel emits under the ``databricks.sql.kernel``
+# logger (a child of the connector's ``databricks.sql`` namespace), so a
+# customer who configures ``databricks.sql`` logging gets kernel logs for
+# free with no extra setup.
+#
+# This is a best-effort, non-essential feature: it must never take down
+# ``use_kernel=True`` for a process. ``getattr`` guards against an older
+# kernel wheel that predates the function. The ``try`` guards against the
+# call itself throwing — note ``except BaseException`` is deliberate: a
+# panic raised across the PyO3 boundary surfaces as
+# ``pyo3_runtime.PanicException``, which derives from ``BaseException``
+# (not ``Exception``), so a narrower clause would let it escape module
+# import and fail every kernel-backed connection. The kernel side is
+# idempotent and returns rather than panics on a double install, but we
+# do not rely on that here — the guard holds regardless of the Rust impl.
+_kernel_init_logging = getattr(_kernel, "init_logging", None)
+if _kernel_init_logging is not None:
+    try:
+        _kernel_init_logging()
+    except BaseException as exc:  # noqa: BLE001 - see comment above re: PanicException
+        logging.getLogger(__name__).debug(
+            "kernel log bridge init failed; continuing without it: %r", exc
+        )
+
+
+# Map a kernel `code` slug to the PEP 249 exception class that best
+# captures it. The match isn't a perfect 1:1 — PEP 249 has a
+# narrower taxonomy than the kernel — so several kernel codes
+# collapse onto the same Python exception. This table is the only
+# place that mapping lives.
+_CODE_TO_EXCEPTION = {
+    "InvalidArgument": ProgrammingError,
+    "Unauthenticated": OperationalError,
+    "PermissionDenied": OperationalError,
+    "NotFound": ProgrammingError,
+    "ResourceExhausted": OperationalError,
+    "Unavailable": OperationalError,
+    "Timeout": OperationalError,
+    "Cancelled": OperationalError,
+    "DataLoss": DatabaseError,
+    "Internal": DatabaseError,
+    "InvalidStatementHandle": ProgrammingError,
+    "NetworkError": OperationalError,
+    # `SqlError` is a server-side query failure (syntax error, missing
+    # object, etc.) — exactly what the Thrift backend surfaces as
+    # `ServerOperationError`. Match Thrift's contract so user code that
+    # catches `ServerOperationError` (a subclass of `DatabaseError`)
+    # works equivalently with `use_kernel=True`.
+    "SqlError": ServerOperationError,
+    "Unknown": DatabaseError,
+}
+
+
+def reraise_kernel_error(exc: "_kernel.KernelError") -> "Error":
+    """Convert a ``databricks_sql_kernel.KernelError`` to a PEP 249
+    exception with the kernel's structured attributes forwarded onto
+    the new instance.
+
+    The returned exception is raised by callers with ``raise ... from
+    exc``; the ``from`` clause is what sets ``__cause__``, so we don't
+    touch it here.
+    """
+    code = getattr(exc, "code", "Unknown")
+    cls = _CODE_TO_EXCEPTION.get(code, DatabaseError)
+
+    # For ServerOperationError, reproduce the Thrift backend's
+    # ``context`` dict so callers that read
+    # ``err.context["diagnostic-info"]`` (the Spark stack trace) /
+    # ``err.context["operation-id"]`` get the same shape on the kernel
+    # path. ``diagnostic_info`` is forwarded from the kernel error (it
+    # now crosses the PyO3 boundary; older wheels return ``None`` via
+    # ``getattr``, so this degrades gracefully). Matches
+    # thrift_backend.py's ServerOperationError construction.
+    context = None
+    if cls is ServerOperationError:
+        context = {
+            "operation-id": getattr(exc, "query_id", None),
+            "diagnostic-info": getattr(exc, "diagnostic_info", None),
+        }
+    new = cls(getattr(exc, "message", str(exc)), context)
+
+    for attr in (
+        "code",
+        "sql_state",
+        "error_code",
+        "vendor_code",
+        "http_status",
+        "retryable",
+        "query_id",
+        # Extended server status now forwarded across the PyO3 boundary
+        # (kernel #121). ``getattr(..., None)`` keeps this forward-safe
+        # against an older wheel that doesn't set these attrs.
+        "display_message",
+        "diagnostic_info",
+        "error_details_json",
+    ):
+        setattr(new, attr, getattr(exc, attr, None))
+    return new
+
+
+def wrap_kernel_exception(what: str, exc: BaseException) -> "Error":
+    """Map any exception from a PyO3 call site to a PEP 249 exception.
+
+    - ``KernelError`` → mapped class with structured attrs forwarded.
+    - Already-PEP-249 ``Error`` (e.g. raised by an inner caller that
+      already mapped) → passed through unchanged.
+    - Anything else (``TypeError`` / ``ValueError`` / etc. from PyO3
+      argument conversion, extension-internal errors) → wrapped in
+      ``OperationalError``.
+
+    Returned, not raised — the caller decides whether to ``raise``
+    or ``raise ... from exc``. ``what`` is a short tag (the calling
+    method name) used only in the ``OperationalError`` message.
+    """
+    if isinstance(exc, _kernel.KernelError):
+        return reraise_kernel_error(exc)
+    if isinstance(exc, Error):
+        return exc
+    return OperationalError(
+        f"Unexpected error from databricks_sql_kernel during {what}: {exc!r}"
+    )