From d01ddf4bda133f3afdb86ce58d371807ad520b6a Mon Sep 17 00:00:00 2001 From: Vikrant Puppala Date: Wed, 19 Aug 2026 23:22:47 +0000 Subject: [PATCH] Deprecate the SEA backend; steer users to the kernel path MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The SEA backend (use_sea=True) has feature gaps — notably it does not support positional (`?`) parameter binding, which causes HTTP 400s against RT/Lakehouse warehouses. Rather than partially patch SEA, mark it deprecated and steer users to the supported kernel backend (use_kernel=True), which is SEA-native and handles positional/named parameter binding. - Emit a warning at SeaDatabricksClient construction pointing users to use_kernel=True + the `[kernel]` extra. - Document use_sea as deprecated/incomplete in the connect() docstring, and refresh the stale use_kernel docstring (it now ships on PyPI via the `[kernel]` extra and supports parameter binding). - Flag the SEA example harness and the CONTRIBUTING backend table as deprecated. SEA stays functional (RT warehouses refuse Thrift, so it can't simply be rerouted) and is slated for eventual removal. Co-authored-by: Isaac Signed-off-by: Vikrant Puppala --- CONTRIBUTING.md | 2 +- examples/experimental/sea_connector_test.py | 5 ++++ src/databricks/sql/backend/sea/backend.py | 11 +++++++++ src/databricks/sql/client.py | 26 ++++++++++++--------- tests/unit/test_sea_backend.py | 24 +++++++++++++++++++ 5 files changed, 56 insertions(+), 12 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cf5b6210b..f744689b0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -153,7 +153,7 @@ reproduce on a SEA or kernel connection, and vice versa: | Backend | Select via (connect kwarg / `extra_params`) | Where its tests live | | --- | --- | --- | | **Thrift** (default) | *(nothing — the default path)* | the general `tests/e2e` suite (the `{}` parametrize case) and mocked `tests/unit` | -| **SEA** (Statement Execution API) | `use_sea=True` | the general `tests/e2e` suite (the `{"use_sea": True}` parametrize case, e.g. `tests/e2e/test_driver.py`) and mocked `tests/unit` | +| **SEA** (Statement Execution API) *(deprecated — use Kernel for SEA-native connections)* | `use_sea=True` | the general `tests/e2e` suite (the `{"use_sea": True}` parametrize case, e.g. `tests/e2e/test_driver.py`) and mocked `tests/unit` | | **Kernel** (Rust, optional) | `use_kernel=True` | the dedicated `tests/e2e/test_kernel_backend.py` / `test_kernel_tls.py`, plus the offline routing test `tests/unit/test_session.py -m realkernel` | Notes that matter when running the suite: diff --git a/examples/experimental/sea_connector_test.py b/examples/experimental/sea_connector_test.py index 712f033c6..d4fda6e13 100644 --- a/examples/experimental/sea_connector_test.py +++ b/examples/experimental/sea_connector_test.py @@ -1,6 +1,11 @@ """ Main script to run all SEA connector tests. +DEPRECATED: the pure-Python SEA backend (``use_sea=True``) exercised by +these examples is incomplete (e.g. no positional ``?`` parameter binding) +and slated for removal. For a SEA-native connection use ``use_kernel=True`` +instead — install it with ``pip install 'databricks-sql-connector[kernel]'``. + This script runs all the individual test modules and displays a summary of test results with visual indicators. diff --git a/src/databricks/sql/backend/sea/backend.py b/src/databricks/sql/backend/sea/backend.py index 04c79a18b..e1017c521 100644 --- a/src/databricks/sql/backend/sea/backend.py +++ b/src/databricks/sql/backend/sea/backend.py @@ -151,6 +151,17 @@ def __init__( http_path, ) + # The SEA backend is deprecated and incomplete (e.g. it does not + # support positional parameter binding) and is slated for removal. + # Steer users to the Rust kernel backend, which is the supported path. + logger.warning( + "The SEA backend (use_sea=True) is deprecated and incomplete and " + "should not be used in production; it is slated for removal. Use " + "the kernel backend instead by passing use_kernel=True and " + "installing the kernel extra: " + "pip install 'databricks-sql-connector[kernel]'." + ) + self._max_download_threads = kwargs.get("max_download_threads", 10) self._ssl_options = ssl_options self._use_arrow_native_complex_types = kwargs.get( diff --git a/src/databricks/sql/client.py b/src/databricks/sql/client.py index a8e4bab1c..44895954f 100755 --- a/src/databricks/sql/client.py +++ b/src/databricks/sql/client.py @@ -117,19 +117,23 @@ def __init__( :param use_sea: `bool`, optional (default is False) Use the native pure-Python SEA backend instead of the Thrift backend. + + Deprecated and incomplete — this backend has feature + gaps (e.g. it does not support positional ``?`` + parameter binding) and is slated for removal. For a + SEA-native connection use ``use_kernel=True`` instead, + which is the supported path. :param use_kernel: `bool`, optional (default is False) Route the connection through the Rust kernel - (``databricks-sql-kernel`` via PyO3). Requires the - kernel extension to be installed separately — the - wheel is not yet published on PyPI, so today the - only supported install path is a local - ``maturin develop --release`` build from the - ``databricks-sql-kernel`` repo into the same venv. - Raises ``ImportError`` if the extension is not - available. In active development — PAT auth only - today; OAuth / federation / external credentials - and native parameter binding land in follow-ups. - Mutually exclusive with ``use_sea``. + (``databricks-sql-kernel`` via PyO3), a SEA-native + client. Requires the kernel extension, installed via + the ``[kernel]`` extra: + ``pip install 'databricks-sql-connector[kernel]'``. + Needs Python >= 3.10; on older interpreters the extra + is a no-op and ``use_kernel=True`` raises a clear + ``ImportError``. Supports PAT, OAuth M2M, and OAuth + U2M auth, and native (positional and named) parameter + binding. Mutually exclusive with ``use_sea``. :param use_hybrid_disposition: `bool`, optional (default is False) Use the hybrid disposition instead of the inline disposition. :param server_hostname: Databricks instance host name. diff --git a/tests/unit/test_sea_backend.py b/tests/unit/test_sea_backend.py index 24a5e8242..513c83c8a 100644 --- a/tests/unit/test_sea_backend.py +++ b/tests/unit/test_sea_backend.py @@ -200,6 +200,30 @@ def test_initialization(self, mock_http_client): ) assert "Could not extract warehouse ID" in str(excinfo.value) + def test_initialization_warns_backend_incomplete(self, mock_http_client, caplog): + """Constructing a SEA client emits a warning steering users to the + kernel backend, since the SEA path is incomplete and slated for + deprecation.""" + import logging + + with caplog.at_level( + logging.WARNING, logger="databricks.sql.backend.sea.backend" + ): + SeaDatabricksClient( + server_hostname="test-server.databricks.com", + port=443, + http_path="/sql/warehouses/abc123", + http_headers=[], + auth_provider=AuthProvider(), + ssl_options=SSLOptions(), + ) + + warnings = [r.message for r in caplog.records if r.levelno == logging.WARNING] + assert any( + "incomplete" in m and "use_kernel=True" in m and "[kernel]" in m + for m in warnings + ), warnings + def test_session_management(self, sea_client, mock_http_client, thrift_session_id): """Test session management methods.""" # Test open_session with minimal parameters