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