Deprecate the SEA backend; steer users to the kernel path

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:

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.
 

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(

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.

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