Warn that the SEA backend is incomplete and steer users to the kernel path

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, emit
a warning at SeaDatabricksClient construction telling users to use the
supported kernel backend (use_kernel=True) and install the `[kernel]`
extra. The SEA path stays functional (RT warehouses refuse Thrift, so
it can't simply be rerouted) and is slated for eventual deprecation.

Co-authored-by: Isaac
Signed-off-by: Vikrant Puppala <vikrant.puppala@databricks.com>

Author: vikrantpuppala

src/databricks/sql/backend/sea/backend.py

@@ -151,6 +151,16 @@ def __init__(
             http_path,
         )
 
+        # The SEA backend is incomplete (e.g. it does not support positional
+        # parameter binding) and is slated for deprecation. Steer users to the
+        # Rust kernel backend, which is the supported path.
+        logger.warning(
+            "The SEA backend (use_sea=True) is incomplete and should not be "
+            "used in production; it will eventually be deprecated. 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(

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