Clarify SEA pool migration and test failed connection cleanup

Signed-off-by: Vu Anh Phung <vu.phung@databricks.com>

Author: vuanhphung

CHANGELOG.md

@@ -3,7 +3,7 @@
 # Unreleased
 - **Breaking:** Remove the deprecated pure-Python SEA backend and its options; use Thrift (default) or `use_kernel=True`.
 - **Breaking:** Kernel IDs now use `BackendType.KERNEL`, `SessionId.from_kernel_session_id`, and `CommandId.from_kernel_statement_id`. Remove `BackendType.SEA`, the `from_sea_*` / `to_sea_*` helpers, `CommandState.from_sea_state`, and `DatabricksClientType.SEA`.
-- Warn when removed SEA options are passed; replace `max_connections` with `_pool_maxsize`.
+- Warn when removed SEA options are passed. On kernel ≥ 1.1.0, use `_pool_maxsize` for the kernel HTTP pool; it does not configure the Thrift query transport.
 
 # 4.9.0 (2026-11-04)
 - Upgrade Databricks SQL Kernel to 1.4.0, which keeps Lakehouse Real-Time session affinity and flushes shared telemetry only after the final session closes.

src/databricks/sql/client.py

@@ -383,7 +383,8 @@ def read(self) -> Optional[OAuthToken]:
             kwargs.pop("max_connections")
             logger.warning(
                 "Parameter 'max_connections' was removed with the SEA backend "
-                "and is ignored. Use '_pool_maxsize' instead."
+                "and is ignored. On kernel >= 1.1.0, use '_pool_maxsize' for the "
+                "kernel HTTP pool; it does not configure the Thrift query transport."
             )
 
         logger.debug(

tests/unit/test_session.py

@@ -39,12 +39,16 @@ class TestSession:
     def test_removed_sea_backend_rejected_before_connecting(
         self, mock_session, mock_http_client, use_kernel
     ):
-        with pytest.raises(
-            ValueError, match="SEA backend has been removed.*use_kernel=True"
-        ):
-            databricks.sql.connect(
-                **self.DUMMY_CONNECTION_ARGS, use_sea=True, use_kernel=use_kernel
-            )
+        gc.collect()
+        with patch("sys.unraisablehook") as unraisable_hook:
+            with pytest.raises(
+                ValueError, match="SEA backend has been removed.*use_kernel=True"
+            ):
+                databricks.sql.connect(
+                    **self.DUMMY_CONNECTION_ARGS, use_sea=True, use_kernel=use_kernel
+                )
+            gc.collect()
+            unraisable_hook.assert_not_called()
         mock_session.assert_not_called()
         mock_http_client.assert_not_called()
 
@@ -56,12 +60,12 @@ def test_removed_sea_backend_rejected_before_connecting(
             ({"use_sea": False}, None),
             ({"use_hybrid_disposition": False}, None),
             ({"use_hybrid_disposition": True}, "use_hybrid_disposition"),
-            ({"max_connections": 10}, "Use '_pool_maxsize' instead."),
-            ({"max_connections": 0}, "Use '_pool_maxsize' instead."),
-            ({"max_connections": None}, "Use '_pool_maxsize' instead."),
+            ({"max_connections": 10}, "max_connections"),
+            ({"max_connections": 0}, "max_connections"),
+            ({"max_connections": None}, "max_connections"),
             (
                 {"max_connections": 10, "_pool_maxsize": 42},
-                "Use '_pool_maxsize' instead.",
+                "max_connections",
             ),
         ],
     )
@@ -93,6 +97,9 @@ def test_removed_backend_options_warn_and_are_not_forwarded(
         if expected_warning:
             assert len(messages) == 1
             assert expected_warning in messages[0]
+            if expected_warning == "max_connections":
+                assert "On kernel >= 1.1.0, use '_pool_maxsize'" in messages[0]
+                assert "does not configure the Thrift query transport" in messages[0]
         else:
             assert messages == []