feat(sea): expose maxConnections through ConnectionOptions to the napi binding

Surfaces the kernel's `HttpConfig::pool_max_idle_per_host` knob
through `ConnectionOptions.maxConnections` on the public client
options, forwards it through `buildSeaConnectionOptions` into the
napi `openSession` call. When omitted, the kernel's default (100)
applies.

Mirrors the Python connector's `max_connections` kwarg on the SEA
backend. The NodeJS Thrift backend does NOT currently expose this
knob — it remains a no-op on that path, documented inline. No
break to Thrift parity (Thrift never had it).

Plumbing:
- `IDBSQLClient.ConnectionOptions` gains `maxConnections?: number`
  with a doc note that the Thrift backend ignores it today.
- `SeaSessionDefaults` (already the shared base across auth-mode
  variants in `SeaNativeConnectionOptions`) gains the field so all
  three auth modes (PAT, OAuth M2M, OAuth U2M) round-trip it.
- `buildSeaConnectionOptions` validates positive-integer-ness at
  the JS boundary (rejects 0, negative, non-integer, NaN) so a
  misuse fails here with a clear `HiveDriverError` instead of
  inside the kernel with a cryptic napi error.
- `native/sea/index.d.ts` (the committed copy of the napi-rs
  generated d.ts) gets the `maxConnections?: number` field on
  `ConnectionOptions`, in step with the kernel branch
  `msrathore/krn-max-connections` (commit `0c5ca3f`).

Tests:
- `tests/unit/sea/auth-max-connections.test.ts` — 9 cases covering
  omission, valid values, boundary (1), and rejection of 0,
  negative, fractional, NaN; plus the OAuth M2M / U2M arms.

Cross-PR dependency: stacks on `msrathore/sea-auth-u2m` (current
NodeJS tip) and requires kernel branch `msrathore/krn-max-connections`
(napi binding side of the same change).

Co-authored-by: Isaac
Signed-off-by: Madhavendra Rathore <madhavendra.rathore@databricks.com>

Author: msrathore-db

lib/contracts/IDBSQLClient.ts

@@ -54,6 +54,14 @@ export type ConnectionOptions = {
   socketTimeout?: number;
   proxy?: ProxyOptions;
   enableMetricViewMetadata?: boolean;
+  /**
+   * Maximum number of pooled HTTP connections per host. SEA backend
+   * only — Thrift backend currently ignores this. Mirrors the Python
+   * connector's `max_connections` kwarg (default 100 in the kernel's
+   * connection pool). Tune up when many statements run concurrently
+   * against the same warehouse to reduce reconnect overhead.
+   */
+  maxConnections?: number;
 } & AuthOptions;
 
 export interface OpenSessionRequest {

lib/sea/SeaAuth.ts

@@ -66,6 +66,15 @@ export interface SeaSessionDefaults {
   catalog?: string;
   schema?: string;
   sessionConf?: Record<string, string>;
+  /**
+   * Maximum pooled HTTP connections per host. Forwarded to the
+   * napi `ConnectionOptions.maxConnections` field, which the kernel
+   * threads into `HttpConfig::pool_max_idle_per_host`. Connection-
+   * level (not session-level), but grouped with the session defaults
+   * here because both flow through the same napi `openSession` call.
+   * Omitted → kernel default (100) applies.
+   */
+  maxConnections?: number;
 }
 
 export type SeaNativeConnectionOptions = SeaSessionDefaults &
@@ -158,10 +167,22 @@ export function isBlankOrReserved(s: string): boolean {
 export function buildSeaConnectionOptions(options: ConnectionOptions): SeaNativeConnectionOptions {
   const { authType } = options as { authType?: string };
 
-  const base = {
+  const base: { hostName: string; httpPath: string; maxConnections?: number } = {
     hostName: options.host,
     httpPath: prependSlash(options.path),
   };
+  // Connection-level pool size — forwarded to the napi binding,
+  // ignored when undefined so the kernel default (100) applies.
+  // Validate at the JS layer (positive integer) so a misuse fails
+  // here instead of inside the kernel with a cryptic message.
+  if (options.maxConnections !== undefined) {
+    if (!Number.isInteger(options.maxConnections) || options.maxConnections < 1) {
+      throw new HiveDriverError(
+        `SEA backend: \`maxConnections\` must be a positive integer; got ${options.maxConnections}.`,
+      );
+    }
+    base.maxConnections = options.maxConnections;
+  }
 
   const oauth = options as {
     oauthClientId?: string;

native/sea/index.d.ts

@@ -49,6 +49,19 @@ export interface ConnectionOptions {
    * `session_confs`. Unknown keys are rejected server-side.
    */
   sessionConf?: Record<string, string>
+  /**
+   * Maximum number of pooled HTTP connections per host. Routes
+   * through the kernel's `HttpConfig::pool_max_idle_per_host`.
+   * Tunes the underlying `reqwest` connection pool — higher values
+   * reduce reconnect overhead when many statements run
+   * concurrently against the same warehouse. `None` falls back to
+   * the kernel default (100). Mirrors the Python connector's
+   * `max_connections` kwarg on the SEA backend.
+   *
+   * Napi-rs serialises `u32` as JS `number`; values up to
+   * `2^32 - 1` round-trip safely (any reasonable pool size fits).
+   */
+  maxConnections?: number
 }
 /**
  * Open a Databricks SQL session over PAT auth and return an opaque

tests/unit/sea/auth-max-connections.test.ts

@@ -0,0 +1,129 @@
+// Copyright (c) 2026 Databricks, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import { expect } from 'chai';
+import { buildSeaConnectionOptions } from '../../../lib/sea/SeaAuth';
+import { ConnectionOptions } from '../../../lib/contracts/IDBSQLClient';
+import HiveDriverError from '../../../lib/errors/HiveDriverError';
+
+describe('SeaAuth — maxConnections plumbing', () => {
+  describe('buildSeaConnectionOptions forwards maxConnections', () => {
+    it('omits maxConnections when not supplied (kernel default applies)', () => {
+      const opts: ConnectionOptions = {
+        host: 'example.cloud.databricks.com',
+        path: '/sql/1.0/warehouses/abc',
+        token: 'dapi-fake-pat',
+      };
+
+      const native = buildSeaConnectionOptions(opts);
+      expect(native).to.not.have.property('maxConnections');
+    });
+
+    it('forwards maxConnections as a positive integer', () => {
+      const opts: ConnectionOptions = {
+        host: 'example.cloud.databricks.com',
+        path: '/sql/1.0/warehouses/abc',
+        token: 'dapi-fake-pat',
+        maxConnections: 200,
+      };
+
+      const native = buildSeaConnectionOptions(opts);
+      expect(native.maxConnections).to.equal(200);
+    });
+
+    it('accepts the minimum value (1)', () => {
+      const opts: ConnectionOptions = {
+        host: 'example.cloud.databricks.com',
+        path: '/sql/1.0/warehouses/abc',
+        token: 'dapi-fake-pat',
+        maxConnections: 1,
+      };
+
+      const native = buildSeaConnectionOptions(opts);
+      expect(native.maxConnections).to.equal(1);
+    });
+
+    it('rejects zero', () => {
+      const opts: ConnectionOptions = {
+        host: 'example.cloud.databricks.com',
+        path: '/sql/1.0/warehouses/abc',
+        token: 'dapi-fake-pat',
+        maxConnections: 0,
+      };
+
+      expect(() => buildSeaConnectionOptions(opts)).to.throw(HiveDriverError, /maxConnections.*positive integer/);
+    });
+
+    it('rejects negative values', () => {
+      const opts: ConnectionOptions = {
+        host: 'example.cloud.databricks.com',
+        path: '/sql/1.0/warehouses/abc',
+        token: 'dapi-fake-pat',
+        maxConnections: -5,
+      };
+
+      expect(() => buildSeaConnectionOptions(opts)).to.throw(HiveDriverError, /maxConnections.*positive integer/);
+    });
+
+    it('rejects non-integer values', () => {
+      const opts: ConnectionOptions = {
+        host: 'example.cloud.databricks.com',
+        path: '/sql/1.0/warehouses/abc',
+        token: 'dapi-fake-pat',
+        maxConnections: 1.5,
+      };
+
+      expect(() => buildSeaConnectionOptions(opts)).to.throw(HiveDriverError, /maxConnections.*positive integer/);
+    });
+
+    it('rejects NaN', () => {
+      const opts: ConnectionOptions = {
+        host: 'example.cloud.databricks.com',
+        path: '/sql/1.0/warehouses/abc',
+        token: 'dapi-fake-pat',
+        maxConnections: NaN,
+      };
+
+      expect(() => buildSeaConnectionOptions(opts)).to.throw(HiveDriverError, /maxConnections.*positive integer/);
+    });
+
+    it('forwards maxConnections through the OAuth M2M arm', () => {
+      const opts: ConnectionOptions = {
+        host: 'example.cloud.databricks.com',
+        path: '/sql/1.0/warehouses/abc',
+        authType: 'databricks-oauth',
+        oauthClientId: 'client-id',
+        oauthClientSecret: 'client-secret',
+        maxConnections: 50,
+      };
+
+      const native = buildSeaConnectionOptions(opts);
+      expect(native.authMode).to.equal('OAuthM2m');
+      expect(native.maxConnections).to.equal(50);
+    });
+
+    it('forwards maxConnections through the OAuth U2M arm', () => {
+      const opts: ConnectionOptions = {
+        host: 'example.cloud.databricks.com',
+        path: '/sql/1.0/warehouses/abc',
+        authType: 'databricks-oauth',
+        maxConnections: 25,
+      };
+
+      const native = buildSeaConnectionOptions(opts);
+      expect(native.authMode).to.equal('OAuthU2m');
+      expect(native.maxConnections).to.equal(25);
+    });
+  });
+});