Deprecate the SEA backend; steer users to the kernel path (#920)

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 <vikrant.puppala@databricks.com>

Author: vikrantpuppala

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