docs: add connection parameter reference (Thrift vs SEA/Kernel)

[eric-wang-1990]

What

Adds docs/connection-parameters.md — a single reference listing every public connection / session / per-statement parameter the Node.js connector accepts, and whether each is honored on the Thrift backend (default), the SEA / Kernel backend (useKernel: true), or both.

The goal is to make protocol support gaps explicit: a parameter honored on one backend but ignored or rejected on the other is called out in a Gap column.

Format

Modeled on the databricks-sql-kernel connection-parameters reference. Grouped by concern: connection identity · authentication · HTTP/proxy/retries · TLS/SSL · results & type rendering · session defaults · telemetry · per-statement options. Each row has a ✅ / ❌ / ⚠️ / — verdict per backend plus a Gap note.

Sources of truth

• Public option shape ← lib/contracts/IDBSQLClient.ts
• Internal / kernel-only flags ← lib/contracts/InternalConnectionOptions.ts
• Thrift wiring ← lib/DBSQLClient.ts, lib/thrift-backend/ThriftBackend.ts, lib/connection/connections/HttpConnection.ts
• Kernel wiring ← lib/kernel/KernelAuth.ts, lib/kernel/KernelBackend.ts, lib/kernel/KernelSessionBackend.ts

Notable gaps documented

Thrift-only (missing/ignored on Kernel):enableMetricViewMetadata auto-injection; auth types custom / token-provider / external-token / static-token + token federation; Azure-direct OAuth; custom OAuth persistence; custom U2M oauthClientId; SOCKS proxies; per-statement useCloudFetch / useLZ4Compression / stagingAllowedLocalPath.

Kernel-only (no Thrift public equivalent):maxConnections; all TLS controls (checkServerCertificate, checkServerCertificateHostname, customCaCert, clientCertPem, clientKeyPem).

TLS caveat surfaced: the Thrift connect() path exposes no public TLS options and hardcodes rejectUnauthorized: false (HttpConnection.ts); the internal ca/cert/key fields are never populated from a public option. TLS customization is therefore kernel-only in practice.

All kernel-path behavior reflects the M0 stub (useKernel is internal/unstable) and is noted as subject to change.

Docs-only change — no code touched.

This pull request and its description were written by Isaac.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[github-actions]

Thanks for your contribution! To satisfy the DCO policy in our contributing guide every commit message must include a sign-off message. One or more of your commits is missing this message. You can reword previous commit messages with an interactive rebase (git rebase -i main).

[github-actions]

Thanks for your contribution! To satisfy the DCO policy in our contributing guide every commit message must include a sign-off message. One or more of your commits is missing this message. You can reword previous commit messages with an interactive rebase (git rebase -i main).

[msrathore-db]

Thanks!

[github-actions]

Node.js integration tests triggered. View workflow run.

[github-actions]

Integration test approval reset.

New commits were pushed to this PR. The integration-test label has been automatically removed for security.

A maintainer must re-review the changes and re-add the label to trigger tests again.

Latest commit: adcb617

[github-actions]

Thanks for your contribution! To satisfy the DCO policy in our contributing guide every commit message must include a sign-off message. One or more of your commits is missing this message. You can reword previous commit messages with an interactive rebase (git rebase -i main).

[peco-review-bot]

Verdict: 1 Nit

Looks good — docs-only change and the load-bearing Thrift claims verify against source (getConnectionOptions exposes no public TLS fields, HttpConnection.createHttpsAgent hardcodes rejectUnauthorized: false, enableMetricViewMetadata auto-injects the conf in openSession, and the OAuth flow/oauthClientId behavior matches createAuthProvider). Only a minor nit: the PR description calls the file docs/connection-parameters.md but it lands as CONNECTION_PARAMETERS.md at repo root.

Other findings

• ⚪ Nit — The PR description repeatedly refers to the file as docs/connection-parameters.md, but the diff adds CONNECTION_PARAMETERS.md at the repository root (and README links to CONNECTION_PARAMETERS.md). No code impact — just a description/filename mismatch worth reconciling so future readers aren't sent to a nonexistent docs/ path. Consider either moving the file under docs/ (to match the description and the databricks-sql-kernel layout it models) or updating the description.

[peco-review-bot]

Verdict: 1 Medium

Docs-only PR adding a Thrift-vs-Kernel connection-parameter reference. I verified the doc's claims against lib/DBSQLClient.ts, HttpConnection.ts, and the contracts files — nearly everything is accurate, but one row is wrong: oauthScopes is marked ✅ honored on Thrift, yet createAuthProvider never passes it into DatabricksOAuth, so Thrift silently ignores it. One medium finding inline.

[peco-review-bot]

Verdict: 1 Medium · 1 Low

Docs-only PR adding a Thrift-vs-Kernel connection-parameter reference. Overall accurate and well-sourced — I verified the socketTimeout:0, SOCKS/proxy, noProxy→bypassHosts, retry ms→sec, maxConnections, mTLS both-or-neither, and customHeaders claims against the code and they hold. Two rows misdescribe the implementation: enableMetricViewMetadata injection is backend-agnostic (in DBSQLClient.openSession, not Thrift-only), and the kernel OAuth U2M / oauthClientId-no-secret behavior contradicts KernelAuth.ts (which mirrors Thrift and forwards the id rather than throwing). Nit: the PR description references docs/connection-parameters.md but the file is added at repo root as CONNECTION_PARAMETERS.md (the README link correctly points at the root file, so no broken link).

[peco-review-bot]

Verdict: 1 Low

Docs-only PR adding CONNECTION_PARAMETERS.md plus comment corrections in KernelAuth.ts / KernelBackend.ts. I spot-checked the doc's high-risk claims against source (oauthScopes Thrift-ignore, oauthClientSecret-based U2M/M2M flow selection, enableMetricViewMetadata double-injection, the TLS rejectUnauthorized:false caveat, kernel sessionConf folding) — all accurate, and the comment edits correctly match the actual oauthClientSecret === undefined ? U2M : M2M logic. One row is wrong: noProxy is marked ✅ for Thrift but the Thrift path never consumes it (inline). Otherwise looks good.

[peco-review-bot]

✅ No issues identified by the review bot.