fix(kernel): normalize zero pool maxsize

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 always configures the shared Python HTTP client and also configures the kernel's Rust HTTP pool with kernel ≥ 1.1.0. |
+| `_pool_maxsize`                      | `int`       |   ✅   |   ⚠️   | `20` (Thrift); `100` (kernel when unset) | Max idle connections retained per host. A positive value always configures the shared Python HTTP client and also configures the kernel's Rust HTTP pool with kernel ≥ 1.1.0. Unset or `0` keeps each client's default. |
 | `_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 and using kernel ≥ 1.1.0.
+  the kernel's Rust HTTP pool when positive and using kernel ≥ 1.1.0. A value of
+  `0` is treated as unset: the shared client keeps 20 and the kernel keeps 100.
 - **`use_inline_params`** renders parameters inline on Thrift; the kernel uses
   native parameter binding.
 

src/databricks/sql/session.py

@@ -313,7 +313,7 @@ def _create_backend(
                 auth_options=kernel_auth_options,
                 retry_options=kernel_retry_options,
                 request_timeout_secs=kwargs.get("_socket_timeout"),
-                max_connections=kwargs.get("_pool_maxsize"),
+                max_connections=kwargs.get("_pool_maxsize") or None,
                 telemetry_options=kernel_telemetry_options,
             )
 

tests/unit/test_session.py

@@ -480,6 +480,20 @@ def test_retry_and_socket_timeout_threaded_into_kernel_client(self):
             finally:
                 conn.close()
 
+            conn = databricks.sql.connect(
+                server_hostname="foo",
+                http_path="/sql/1.0/warehouses/abc",
+                use_kernel=True,
+                access_token="dapi-xyz",
+                enable_telemetry=False,
+                _pool_maxsize=0,
+            )
+            try:
+                _, kwargs = mock_kernel_client.call_args
+                assert kwargs["max_connections"] is None
+            finally:
+                conn.close()
+
     def test_azure_sp_m2m_kwargs_threaded_into_kernel_auth_options(self):
         # The Azure SP credentials a user passes to connect() must reach the
         # kernel auth bridge via auth_options; without this threading the