fix(kernel): gate max connections kwarg

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

Author: vuanhphung

CONNECTION_PARAMETERS.md

@@ -102,7 +102,7 @@ to change without notice.
 | ------------------------------------ | ----------- | :----: | :----: | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
 | `_socket_timeout`                    | `float` (s) |   ✅   |   ✅   | `900` (Thrift); `120` (kernel) | Thrift: socket send/recv/connect timeout. Kernel: total HTTP request deadline from connect through response-body completion. A positive value is forwarded; unset or `0` selects the kernel's 120s default. On the kernel path, `0` is neither unlimited nor an immediate timeout. |
 | `_pool_connections`                  | `int`       |   ✅   |   ⚠️   | `10`          | Number of urllib3 connection pools. Configures the connector's shared Python HTTP client; the kernel's query transport is its own Rust stack.  |
-| `_pool_maxsize`                      | `int`       |   ✅   |   ✅   | `20` (Thrift); `100` (kernel when unset) | Max idle connections retained per host. An explicit value configures both the shared Python HTTP client and the kernel's Rust HTTP pool. |
+| `_pool_maxsize`                      | `int`       |   ✅   |   ✅   | `20` (Thrift); `100` (kernel when unset) | Max idle connections retained per host. An explicit value configures the shared Python HTTP client and, when supported by the installed kernel wheel, the kernel's Rust HTTP pool. |
 | `_proxy_auth_method`                 | `str`       |   ✅   |   ⚠️   | `None`        | `basic` or `negotiate` (Kerberos). Applies to the shared Python HTTP client; not threaded to the kernel query transport. See [`docs/proxy.md`](docs/proxy.md). |
 | `_retry_stop_after_attempts_count`   | `int`       |   ✅   |   ✅   | `30`          | Max attempts in a retry sequence. Bounded to `[1, 60]` on Thrift; forwarded to the kernel's retry policy.                                       |
 | `_retry_stop_after_attempts_duration`| `float` (s) |   ✅   |   ✅   | `900`         | Max total wall-clock seconds spent retrying. Forwarded to the kernel.                                                                           |
@@ -204,7 +204,8 @@ None — the kernel's parameter surface is currently a subset of Thrift's.
 
 - **Connection pooling / proxy**: `_pool_connections` and `_proxy_auth_method`
   configure only the shared Python HTTP client. `_pool_maxsize` also configures
-  the kernel's Rust HTTP pool when explicitly set.
+  the kernel's Rust HTTP pool when explicitly set and supported by the installed
+  kernel wheel.
 - **`use_inline_params`** renders parameters inline on Thrift; the kernel uses
   native parameter binding.
 

src/databricks/sql/backend/kernel/client.py

@@ -156,7 +156,7 @@ def _kernel_session_accepts_kwarg(name: str) -> bool:
     ``**kwargs`` catch-all), so forwarding a kwarg it doesn't declare raises
     ``TypeError`` at construction, so we gate kwargs on what the installed
     wheel supports. Falls **closed** (returns ``False``) when the signature
-    can't be introspected because omitting an accepted telemetry kwarg is safer
+    can't be introspected because omitting an accepted optional kwarg is safer
     than forwarding an unsupported one.
     """
     try:
@@ -401,7 +401,9 @@ def open_session(
                 if forwarded:
                     http_headers_kwargs["http_headers"] = forwarded
             pool_kwargs: Dict[str, Any] = {}
-            if self._max_connections is not None:
+            if self._max_connections is not None and _kernel_session_accepts_kwarg(
+                "max_connections"
+            ):
                 pool_kwargs["max_connections"] = self._max_connections
             self._kernel_session = _kernel.Session(
                 host=self._server_hostname,

tests/unit/test_kernel_client.py

@@ -368,8 +368,13 @@ def fake_session(**kw):
     assert captured["request_timeout_secs"] == timeout
 
 
-@pytest.mark.parametrize("max_connections", [None, 41])
-def test_open_session_passes_max_connections_to_kernel(monkeypatch, max_connections):
+@pytest.mark.parametrize(
+    ("max_connections", "kernel_accepts_kwarg", "expected_forwarded"),
+    [(None, True, False), (41, True, True), (41, False, False)],
+)
+def test_open_session_gates_max_connections_for_kernel_compatibility(
+    monkeypatch, max_connections, kernel_accepts_kwarg, expected_forwarded
+):
     captured = {}
 
     def fake_session(**kw):
@@ -379,6 +384,11 @@ def fake_session(**kw):
         return sess
 
     monkeypatch.setattr(kernel_client._kernel, "Session", fake_session)
+    monkeypatch.setattr(
+        kernel_client,
+        "_kernel_session_accepts_kwarg",
+        lambda name: name == "max_connections" and kernel_accepts_kwarg,
+    )
     c = kernel_client.KernelDatabricksClient(
         server_hostname="example.cloud.databricks.com",
         http_path="/sql/1.0/warehouses/abc",
@@ -389,10 +399,10 @@ def fake_session(**kw):
 
     c.open_session(session_configuration=None, catalog=None, schema=None)
 
-    if max_connections is None:
-        assert "max_connections" not in captured
-    else:
+    if expected_forwarded:
         assert captured["max_connections"] == max_connections
+    else:
+        assert "max_connections" not in captured
 
 
 def test_open_session_passes_phase_7_telemetry_kwargs_to_kernel(monkeypatch):