docs: add connection parameter reference (Thrift vs SEA/Kernel) by eric-wang-1990 · Pull Request #457 · databricks/databricks-sql-nodejs

eric-wang-1990 · 2026-07-23T02:17:32Z

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 · 2026-07-23T02:18:59Z

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 · 2026-07-23T02:24:09Z

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 · 2026-07-24T07:08:19Z

Node.js integration tests triggered. View workflow run.

github-actions · 2026-07-28T05:31:15Z

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 · 2026-07-28T05:31:18Z

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).

Documents every public ConnectionOptions / OpenSessionRequest / per-statement parameter and whether it is honored on the Thrift backend, the SEA/Kernel backend (useKernel), or both — making protocol support gaps explicit. Mirrors the databricks-sql-kernel connection-parameters reference format. Co-authored-by: Isaac Signed-off-by: eric-wang-1990 <e.wang@databricks.com>

Relocate docs/connection-parameters.md → CONNECTION_PARAMETERS.md at the repo root and add a README "Configuration" section linking to it, mirroring the existing Telemetry section's summary+link pattern. Co-authored-by: Isaac Signed-off-by: eric-wang-1990 <e.wang@databricks.com>

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.

github-actions · 2026-08-17T22:35:12Z

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

✅ No issues identified by the review bot.

eric-wang-1990 · 2026-08-17T22:39:40Z

+
+| Option                                                                       | Type                 |  Thrift  |  Kernel  | Default Value                                      | Note                                                                                                                                                                                                                                                                                                                                                  |
+| ---------------------------------------------------------------------------- | -------------------- | :------: | :------: | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `authType: 'access-token'` + `token` (PAT)                                   | `token: string`      |    ✅    |    ✅    | `authType` ⇒ `'access-token'`                      | Default auth mode when `authType` is omitted.                                                                                                                                                                                                                                                                                                         |


This is weird, the option name is authType. If it only allow several possible values you should put in the Note Column

Made the docs-only edit: the access-token row's Note column now enumerates the allowed authType values ('access-token', 'databricks-oauth', 'custom', 'token-provider', 'external-token', 'static-token'), sourced from the union in lib/contracts/IDBSQLClient.ts. This directly answers the reviewer's request to call out that authType only accepts a fixed set of values.

Pushed a2282f5.

Addresses: - #3799315347 at CONNECTION_PARAMETERS.md:60 Signed-off-by: peco-engineer-bot[bot] <peco-engineer-bot[bot]@users.noreply.github.com>

github-actions · 2026-08-17T22:42:54Z

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

✅ No issues identified by the review bot.

Signed-off-by: eric-wang-1990 <115501094+eric-wang-1990@users.noreply.github.com>

Addresses: - #3799169490 at CONNECTION_PARAMETERS.md:88 Signed-off-by: peco-engineer-bot[bot] <peco-engineer-bot[bot]@users.noreply.github.com> Signed-off-by: eric-wang-1990 <e.wang@databricks.com>

…ernel/Default/Note Add `Type` and `Default Value` columns to every parameter table and rename the `Gap` column to `Note`. Types come from the public `ConnectionOptions` / `ExecuteStatementOptions` shapes (`IDBSQLClient.ts`, `IDBSQLSession.ts`); defaults come from `DBSQLClientDefaults` (`DBSQLClient.ts`) and `DEFAULT_TELEMETRY_CONFIG` (`telemetry/types.ts`). The telemetry section's prose "Aspect" table is replaced with a full per-option table (one row per `telemetry*` knob with its default), and the events caveat is kept as a note. Formatted with `prettier --write` so `prettier . --check` passes (the file previously failed the check). Co-authored-by: Isaac Signed-off-by: eric-wang-1990 <e.wang@databricks.com>

The `runAsync` row said "not threaded on the kernel path", but `IDBSQLSession.ts` documents the reverse: on Thrift `runAsync` is a no-op (the path always submits async and polls; the option is not read), while the kernel reads it to select sync direct-results (default) vs. submit-and-poll. Flip the verdicts (Thrift ⚠️, kernel ✅) and rewrite the note to match. Co-authored-by: Isaac Signed-off-by: eric-wang-1990 <e.wang@databricks.com>

Addresses: - #3799315347 at CONNECTION_PARAMETERS.md:60 Signed-off-by: peco-engineer-bot[bot] <peco-engineer-bot[bot]@users.noreply.github.com> Signed-off-by: eric-wang-1990 <e.wang@databricks.com>

Per review feedback (PR #457 discussion r3799323450): collapse the seven per-authType rows into two — one for the modes both backends accept (`access-token`, `databricks-oauth`) and one for the Thrift-only modes (`custom`, `token-provider`, `external-token`, `static-token`). OAuth sub-option rows are unchanged. Co-authored-by: Isaac Signed-off-by: eric-wang-1990 <e.wang@databricks.com>

peco-review-bot

Verdict: 1 Medium

Docs-only PR adding a connection-parameter reference; the accompanying comment edits in KernelAuth.ts/KernelBackend.ts accurately match the code (flow selection now keys off oauthClientSecret, mirroring Thrift). One medium inaccuracy: the customHeaders row marks Thrift ✅ but the option is not applied to the primary Thrift transport. Nit: the PR description says the file is docs/connection-parameters.md while it's actually created as CONNECTION_PARAMETERS.md at repo root (the README link is correct, so no functional issue).

Addresses: - #3799637110 at CONNECTION_PARAMETERS.md:76 Signed-off-by: peco-engineer-bot[bot] <peco-engineer-bot[bot]@users.noreply.github.com>

The previous commit edited the customHeaders row without re-aligning the table; prettier requires the column padding to match the widest cell. No content change — realignment only. Fixes the lint / "Check code style" job. Co-authored-by: Isaac Signed-off-by: eric-wang-1990 <e.wang@databricks.com>

peco-review-bot

✅ No issues identified by the review bot.

Copilot AI review requested due to automatic review settings July 23, 2026 02:17

eric-wang-1990 temporarily deployed to azure-prod July 23, 2026 02:17 — with GitHub Actions Inactive

Copilot AI reviewed Jul 23, 2026

eric-wang-1990 temporarily deployed to azure-prod July 23, 2026 02:23 — with GitHub Actions Inactive

eric-wang-1990 requested a review from msrathore-db July 23, 2026 02:24

msrathore-db approved these changes Jul 23, 2026

View reviewed changes

eric-wang-1990 marked this pull request as draft July 24, 2026 07:07

eric-wang-1990 added the integration-test Trigger the cross-repo driver-test Node.js integration suite on this PR label Jul 24, 2026

eric-wang-1990 marked this pull request as ready for review July 28, 2026 05:31

eric-wang-1990 temporarily deployed to azure-prod July 28, 2026 05:31 — with GitHub Actions Inactive

github-actions Bot removed the integration-test Trigger the cross-repo driver-test Node.js integration suite on this PR label Jul 28, 2026

eric-wang-1990 added 2 commits July 27, 2026 22:33

peco-review-bot Bot approved these changes Jul 28, 2026

View reviewed changes

eric-wang-1990 force-pushed the docs/connection-parameters branch from adcb617 to 789c465 Compare July 28, 2026 05:35

eric-wang-1990 temporarily deployed to azure-prod July 28, 2026 05:35 — with GitHub Actions Inactive

eric-wang-1990 deployed to azure-prod August 17, 2026 22:34 — with GitHub Actions Active

peco-review-bot Bot approved these changes Aug 17, 2026

View reviewed changes

eric-wang-1990 commented Aug 17, 2026

View reviewed changes

peco-engineer-bot Bot added a commit that referenced this pull request Aug 17, 2026

ai: apply changes for #457 (1 review thread)

a2282f5

Addresses: - #3799315347 at CONNECTION_PARAMETERS.md:60 Signed-off-by: peco-engineer-bot[bot] <peco-engineer-bot[bot]@users.noreply.github.com>

peco-engineer-bot Bot deployed to azure-prod August 17, 2026 22:41 Active

peco-review-bot Bot approved these changes Aug 17, 2026

View reviewed changes

eric-wang-1990 mentioned this pull request Aug 17, 2026

docs: add connection parameter reference (Thrift vs Kernel) databricks/databricks-sql-python#913

Merged

eric-wang-1990 and others added 6 commits August 17, 2026 16:41

Merge branch 'main' into docs/connection-parameters

6a1f827

Signed-off-by: eric-wang-1990 <115501094+eric-wang-1990@users.noreply.github.com>

ai: apply changes for #457 (1 review thread)

768f7b6

Addresses: - #3799169490 at CONNECTION_PARAMETERS.md:88 Signed-off-by: peco-engineer-bot[bot] <peco-engineer-bot[bot]@users.noreply.github.com> Signed-off-by: eric-wang-1990 <e.wang@databricks.com>

ai: apply changes for #457 (1 review thread)

fe47621

Addresses: - #3799315347 at CONNECTION_PARAMETERS.md:60 Signed-off-by: peco-engineer-bot[bot] <peco-engineer-bot[bot]@users.noreply.github.com> Signed-off-by: eric-wang-1990 <e.wang@databricks.com>

eric-wang-1990 force-pushed the docs/connection-parameters branch from a2282f5 to ec26f9a Compare August 17, 2026 23:44

eric-wang-1990 deployed to azure-prod August 17, 2026 23:44 — with GitHub Actions Active

peco-review-bot Bot reviewed Aug 17, 2026

View reviewed changes

Comment thread CONNECTION_PARAMETERS.md Outdated

ai: apply changes for #457 (1 review thread)

7f4a972

Addresses: - #3799637110 at CONNECTION_PARAMETERS.md:76 Signed-off-by: peco-engineer-bot[bot] <peco-engineer-bot[bot]@users.noreply.github.com>

peco-engineer-bot Bot deployed to azure-prod August 17, 2026 23:49 Active

peco-review-bot Bot approved these changes Aug 17, 2026

View reviewed changes

eric-wang-1990 mentioned this pull request Aug 18, 2026

docs: add connection parameter reference (Thrift vs SEA/Kernel) databricks/databricks-sql-go#445

Merged

Uh oh!

Conversation

eric-wang-1990 commented Jul 23, 2026

What

Format

Sources of truth

Notable gaps documented

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Jul 23, 2026

Uh oh!

github-actions Bot commented Jul 23, 2026

Uh oh!

msrathore-db left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Jul 24, 2026

Uh oh!

github-actions Bot commented Jul 28, 2026

Uh oh!

github-actions Bot commented Jul 28, 2026

Uh oh!

peco-review-bot Bot left a comment

Choose a reason for hiding this comment

Other findings

Uh oh!

github-actions Bot commented Aug 17, 2026

Uh oh!

peco-review-bot Bot left a comment

Choose a reason for hiding this comment

Uh oh!

eric-wang-1990 Aug 17, 2026

Choose a reason for hiding this comment

Uh oh!

peco-engineer-bot Bot Aug 17, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Aug 17, 2026

Uh oh!

peco-review-bot Bot left a comment

Choose a reason for hiding this comment

Uh oh!

peco-review-bot Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

peco-review-bot Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants