CONNECTION_PARAMETERS.md

Connection parameter reference

This document lists every typed public parameter accepted by DBSQLClient.connect, DBSQLClient.openSession, and DBSQLSession.executeStatement, plus the internal or deprecated connection inputs that the runtime still recognizes. Because the driver ships two backends, each table states whether the parameter is honored by the Thrift backend (the default), the SEA / Kernel backend, or both.

Backend selection. The connector defaults to Thrift. Pass the internal, unstable useKernel: true option to select Kernel. It is intentionally absent from the published .d.ts and may be removed without notice.

Legend

Symbol	Meaning
✅	Honored by the backend.
❌	Ignored, rejected, or unsupported by the backend.
⚠️	Honored only for some values, flows, or requests; read the note.
—	Not applicable or no default on this backend.

Sources of truth

• Public option shapes: lib/contracts/IDBSQLClient.ts and lib/contracts/IDBSQLSession.ts.
• Internal Kernel options: lib/contracts/InternalConnectionOptions.ts and the runtime-only casts in lib/kernel/KernelAuth.ts.
• Defaults: DBSQLClient.getDefaultConfig, DEFAULT_TELEMETRY_CONFIG, and native/kernel/index.d.ts.
• Thrift wiring: lib/DBSQLClient.ts, lib/thrift-backend/ThriftBackend.ts, lib/thrift-backend/ThriftSessionBackend.ts, and lib/connection/connections/HttpConnection.ts.
• Kernel wiring: lib/kernel/KernelAuth.ts, lib/kernel/KernelBackend.ts, and lib/kernel/KernelSessionBackend.ts.

---

Connection identity and backend selection

Option	Type	Thrift	Kernel	Default Value	Note
host	string	✅	✅	— (required)	Required on both.
path	string	✅	✅	— (required)	Kernel also derives x-databricks-org-id from a ?o=<id> query parameter.
port	number	✅	❌	443 / —	Kernel ignores this field. Include a non-default port in host for Kernel.
userAgentEntry	string	✅	✅	—	Folded into the connector User-Agent on both.
useKernel (internal)	boolean	—	—	false	Selects the backend: false/omitted → Thrift, true → Kernel.
clientId (deprecated)	string	✅	✅	—	Runtime-only alias for userAgentEntry. userAgentEntry wins when both are supplied.

Authentication

Option	Type	Thrift	Kernel	Default Value	Note
authType — common modes	'access-token' | 'databricks-oauth' | 'static-token'	✅	✅	'access-token'	access-token uses token; static-token uses staticToken. OAuth supports U2M and M2M, with the Kernel qualifications below.
authType — Thrift-only modes	'custom' | 'token-provider' | 'external-token'	✅	❌	—	Kernel rejects these auth modes.
token	string	✅	✅	required for access-token	Thrift sends the PAT as a Bearer token (Authorization: Bearer <token>); Kernel uses native PAT auth. Kernel rejects blank/reserved values client-side.
staticToken	string	✅	✅	required for static-token	Thrift optionally wraps it in federation. Kernel uses native bearer-token auth with federation always enabled.
provider	IAuthentication	✅	❌	required for custom	Custom Thrift authentication provider.
tokenProvider	ITokenProvider	✅	❌	required for token-provider	Thrift wraps it with caching and optional federation.
getToken	TokenCallback	✅	❌	required for external-token	Callback used by the Thrift external-token provider.
oauthScopes	Array<string>	❌	⚠️	flow-dependent	Thrift does not pass caller-supplied scopes to DatabricksOAuth. Kernel honors them for U2M and workspace-OIDC M2M, but Azure Entra-direct M2M uses its fixed <resource>/.default scope.
oauthClientId	string	✅	✅	flow- and cloud-dependent	In-house OAuth defaults to databricks-sql-connector. Thrift Entra-direct defaults to its Azure application id; Kernel Entra-direct M2M requires an explicit id.
oauthClientSecret	string	✅	✅	—	Presence selects M2M; absence selects U2M on both. Kernel forwards blank values for workspace-OIDC parity, but rejects them in the Azure Entra-direct arm.
azureTenantId / useDatabricksOAuthInAzure	string / boolean	✅	⚠️	—	Kernel ignores both for U2M. On Azure M2M, useDatabricksOAuthInAzure: false/omitted selects Entra-direct and true selects workspace OIDC; azureTenantId applies only to Entra-direct.
persistence	OAuthPersistence	✅	❌	in-memory store / —	Custom OAuth persistence hook. Kernel rejects it; use tokenCacheEnabled for the Kernel U2M cache.
tokenCacheEnabled	boolean	❌	✅	— / false	Kernel U2M only. Enables its encrypted on-disk refresh-token cache; it has no effect on M2M or other auth types.
enableTokenFederation	boolean	✅	❌	false / —	Thrift federation opt-in. Kernel ignores it because federation is always enabled for static-token.
federationClientId	string	✅	⚠️	—	Thrift uses it when federation is enabled for token-provider, external-token, or static-token auth. Kernel honors it only for static-token; a non-empty value selects SP-wide WIF and omission selects account-wide WIF.
authProvider second argument (deprecated)	IAuthentication	✅	❌	—	Deprecated second argument to DBSQLClient.connect. It overrides Thrift authentication; Kernel ignores it and authenticates from ConnectionOptions.

HTTP client, proxy, and retries

Option	Type	Thrift	Kernel	Default Value	Note
socketTimeout	number (ms)	✅	⚠️	900000 / 120000	Kernel forwards only positive values. 0 means no timeout on Thrift but is omitted on Kernel, which then keeps its 120-second default.
proxy	ProxyOptions	✅	⚠️	—	{protocol, host, port, auth}. Kernel supports HTTP/HTTPS proxies only; Thrift also supports the declared SOCKS variants.
noProxy (internal)	string	❌	⚠️	—	Runtime-only Kernel bypass list, forwarded as bypassHosts only when an explicit proxy is also supplied.
customHeaders	Record<string, string>	⚠️	✅	—	Thrift applies these only to driver-owned telemetry and feature-flag requests, not the primary transport or OAuth. Kernel applies them after dropping reserved auth/org headers, validating control characters, and appending the connector UA.
retryMaxAttempts	number	✅	✅	5	Total attempts, including the initial request. Kernel converts this to its retries-after-first representation internally.
retriesTimeout	number (ms)	✅	✅	900000	Kernel converts milliseconds to whole seconds.
retryDelayMin	number (ms)	✅	✅	1000	Kernel converts milliseconds to whole seconds.
retryDelayMax	number (ms)	✅	✅	60000	Kernel converts milliseconds to whole seconds.
maxConnections (internal)	number	❌	✅	— / Kernel default	Kernel connection-pool size. Must be a positive integer within the napi u32 range.

TLS / SSL

Both backends verify server certificates by default. Prefer customCaCert to disabling verification.

Option	Type	Thrift	Kernel	Default Value	Note
checkServerCertificate	boolean	✅	✅	true	Master verification toggle. false disables chain and hostname verification.
checkServerCertificateHostname (internal)	boolean	❌	✅	— / true	Independent Kernel hostname-vs-SNI check; no-op when checkServerCertificate is false.
customCaCert	Buffer | string	✅	✅	—	Additional PEM CA. Thrift uses Node bundled roots plus NODE_EXTRA_CA_CERTS, then appends this CA; Kernel adds it to its normal trust roots.
clientCert	Buffer | string	✅	✅	—	Public mTLS client certificate. Must be paired with clientKey.
clientKey	Buffer | string	✅	✅	—	Public mTLS private key. Must be paired with clientCert; PKCS#8 is recommended for Kernel portability.
clientCertPem / clientKeyPem (internal)	Buffer | string	❌	✅	—	Runtime-only Kernel aliases for the public mTLS pair. They take precedence over clientCert/clientKey when both pairs are supplied.

Results and type rendering

Option	Type	Thrift	Kernel	Default Value	Note
preserveBigNumericPrecision	boolean	✅	✅	false	Returns DECIMAL as an exact string and BIGINT as bigint on both.
disableRowMaterialization	boolean	✅	✅	false	Fetches and parses Arrow batches but returns null row placeholders instead of converting cells. Intended for fetch-throughput tests.
enableGeoSpatialSupport	boolean	❌	✅	false	Returns GEOMETRY / GEOGRAPHY as canonical { srid: number, wkb: Buffer } values when true, or WKT / EWKT strings when false. The choice is local and is not forwarded to SEA.
enableMetricViewMetadata	boolean	✅	⚠️	false	Injected into session configuration on both paths. Kernel may drop its non-allowlisted configuration key.

Metadata catalog filters

Option	Type	Thrift	Kernel	Default Value	Note
escapeMetadataCatalogName	boolean	✅	✅	false	Escapes unescaped _ in catalog filters; existing \_ escapes and % wildcards are preserved, matching JDBC.

Set escapeMetadataCatalogName: true in client.connect(...) to treat catalog underscores literally in metadata requests. For example, comparator_tests matches that catalog rather than also matching comparatorXtests. Schema, table, column, and function name patterns are unaffected.

Thrift applies this to getSchemas, getTables, getColumns, and getFunctions. Kernel applies it to getTables, avoiding catalog enumeration for names without % wildcards; its other methods already use exact catalog identifiers. getPrimaryKeys and getCrossReference use exact catalog identifiers on both backends.

Session defaults (openSession(request))

Option	Type	Thrift	Kernel	Default Value	Note
initialCatalog	string	✅	✅	—	Initial catalog for the session.
initialSchema	string	✅	✅	—	Initial schema for the session.
configuration	{ [key: string]: string }	✅	⚠️	—	Kernel matches keys case-insensitively against an allowlist and drops non-allowlisted keys with a warning. Thrift forwards the map more freely.
queryTags	Record<string, string | null | undefined>	✅	✅	—	Both serialize this into the reserved QUERY_TAGS session conf. It takes precedence over configuration.QUERY_TAGS.

Telemetry

Thrift uses the driver-layer telemetry implementation. Kernel uses its native telemetry implementation, so only the options explicitly forwarded by buildKernelTelemetryOptions apply to Kernel.

Option	Type	Thrift	Kernel	Default Value	Note
telemetryEnabled	boolean	✅	✅	true / false	Thrift is enabled by default but gated by a workspace feature flag. Kernel is opt-in: pass true explicitly. DATABRICKS_TELEMETRY_DISABLED disables both.
telemetryBatchSize	number	✅	✅	100	Events per export batch.
telemetryFlushIntervalMs	number (ms)	✅	✅	5000	Periodic flush interval.
telemetryMaxRetries	number	✅	✅	3	Export retry attempts after the initial request.
telemetryAuthenticatedExport	boolean	✅	❌	true / —	Selects the authenticated endpoint only in the Thrift driver-layer exporter. It is not forwarded to Kernel.
telemetryCircuitBreakerThreshold	number	✅	⚠️	5	Forwarded to Kernel, but effective there only when the native telemetry circuit breaker is enabled.
telemetryCircuitBreakerTimeout	number (ms)	✅	⚠️	60000	Forwarded to Kernel, but effective there only when the native telemetry circuit breaker is enabled.
telemetryCloseTimeoutMs	number (ms)	✅	✅	2000	Maximum wait for the final telemetry flush.
telemetryMaxStatementMetrics	number	✅	❌	5000 / —	Thrift driver-layer aggregation-map cap. It is not forwarded to Kernel.
telemetryMaxPendingMetrics	number	✅	❌	500 / —	Thrift driver-layer pending-buffer cap. It is not forwarded to Kernel.

Telemetry events also differ by backend. Kernel owns execution and result fetching below the TypeScript layer, so its event set is not identical to the Thrift driver-layer event set.

Per-statement options (session.executeStatement(sql, options))

Option	Type	Thrift	Kernel	Default Value	Note
queryTimeout	number | bigint | Int64	✅	❌	—	Thrift sends this server-side timeout for Compute clusters. Kernel ignores it; SQL Warehouses use STATEMENT_TIMEOUT.
runAsync	boolean	❌	✅	— / false	Thrift always sends asynchronously and ignores the option. Kernel false/omitted uses direct execution; true submits and polls. This execute option is not deprecated.
maxRows	number | bigint | Int64 | null	✅	❌	100000 / —	Thrift uses it for the initial Direct Results row count; null disables Direct Results. Kernel does not retain or forward the supplied value.
useCloudFetch	boolean	✅	❌	true / —	Kernel logs and ignores this per-statement hint; Kernel result fetching owns its CloudFetch behavior.
useLZ4Compression	boolean	✅	❌	true / —	Thrift uses it when supported and when the result is not CloudFetch. Kernel owns and auto-detects result compression.
stagingAllowedLocalPath	string | string[]	✅	❌	—	Local allowlist for Thrift volume/staging operations. Kernel volume operations are unsupported.
namedParameters	Record<string, DBSQLParameter | DBSQLParameterValue>	✅	✅	—	Named SQL parameters. Cannot be combined with non-empty ordinalParameters. Thrift requires a protocol that supports parameterized queries.
ordinalParameters	Array<DBSQLParameter | DBSQLParameterValue>	✅	✅	—	Positional SQL parameters. Cannot be combined with non-empty namedParameters.
queryTags	Record<string, string | null | undefined>	✅	✅	—	Serialized into the per-statement query_tags conf overlay on both.
rowLimit	number	❌	✅	—	Kernel-only server-side row cap. Thrift logs and ignores it.
statementConf	Record<string, string>	❌	✅	—	Kernel-only per-statement Spark conf overlay. Structured queryTags overwrite its query_tags key when non-empty.

Metadata-operation request parameters

The public session metadata methods also accept request objects. These are not connection options, but are included so the reference covers the complete session parameter surface.

Methods	Option(s)	Thrift	Kernel	Note
Request-object metadata methods	maxRows	✅	❌	Thrift uses it for Direct Results. Kernel currently drops it rather than applying it at fetch time.
Request-object metadata methods	runAsync (deprecated)	❌	❌	The caller value is ignored. Thrift derives wire async behavior from protocol support; Kernel metadata calls are already terminal.
getSchemas	catalogName, schemaName	✅	✅	Optional filters.
getTables	catalogName, schemaName, tableName, tableTypes	✅	✅	Optional filters.
getColumns	catalogName, schemaName, tableName, columnName	✅	✅	Optional filters.
getFunctions	catalogName, schemaName, functionName	✅	✅	functionName is required.
getPrimaryKeys	catalogName, schemaName, tableName	✅	⚠️	Schema and table are required. Kernel additionally requires a non-empty catalogName; Thrift can resolve an omitted catalog.
getCrossReference	parentCatalogName, parentSchemaName, parentTableName, foreignCatalogName, foreignSchemaName, foreignTableName	✅	✅	All six fields are required.
getInfo	infoType	⚠️	⚠️	Both effectively support the three values the Databricks server answers: server name, DBMS name, and DBMS version.

---

Main backend gaps

Thrift-only capabilities include custom/token-provider authentication, custom OAuth persistence, SOCKS proxies, authenticated/driver-buffer telemetry knobs, query timeout, Direct Results maxRows, per-statement CloudFetch/LZ4 hints, and volume operations.

Kernel-only capabilities include connection-pool sizing, proxy bypass hosts, independent TLS hostname verification, optional U2M disk caching, and per-statement rowLimit/statementConf.

The Kernel path remains internal and unstable; its behavior may change.