npm / @databricks/sql
@databricks/sql
What changed in @databricks/sql 1 to 3, from its official release notes, upgrade guides and advisories. Sources checked 2026-11-13.
5 breaking3 security13 new APIs and options1 performance8 behavior and defaults10 fixes and other
See which of these apply to your code, ranked, in your agent:
npx @unstale/cli init@databricks/sql 32 changes
Breaking changes 2
Returns empty results with the standard schema when a catalog, schema, or table is missing, instead of throwing.
Requires Node.js 22.23.4+, 24.22.1+, or 26.12.1+; Node.js 20, 23, and 25 are no longer supported because those end-of-life lines have no Brotli decoder fix.
@databricks/sql 218 changes
Breaking changes 2
Thrift TLS certificates are verified by default, improving connection security.
The minimum supported Node.js version is raised to 20, dropping Node 14, 16, and 18.
Security 1
The native kernel backend was upgraded to 1.3.0, including security fixes in the SQL kernel bindings.
New APIs and options 7
Adds an option, defaulting to false, to return kernel GEOMETRY / GEOGRAPHY results as { srid, wkb } instead of WKT / EWKT.
Adds an option, defaulting to false, to escape catalog underscores in metadata requests.
The kernel backend adds Azure Entra authentication.
Custom CA and mTLS options are available for configuring Thrift TLS.
Adds disableRowMaterialization for fetch-throughput benchmarks.
Static-token federation is available with the kernel backend.
U2M token caching can be enabled optionally.
Behavior and default changes 2
The kernel dependency is now stable and no longer experimental.
Telemetry options are forwarded to the kernel backend.
Fixes and other changes 6
Kernel result metadata now preserves DECIMAL precision and scale.
Fixes catalog metadata and required-name validation.
Accepts omitted or empty namespaces in kernel calls.
Default Thrift connections to Reyden/Real-Time SQL warehouses automatically recover onto the kernel backend while preserving structured SQL errors.
The kernel backend now has getTypeInfo() parity.
Interval-type issues in the kernel backend are fixed.
@databricks/sql 120 changes
Breaking changes 1
The kernel backend requires Node >= 18; on older Node, enabling it raises an error directing you to the Thrift backend.
Security 2
Clears critical and other non-breaking OSV-Scanner findings through dependency overrides and a dev-toolchain bump, without changing the engine or runtime API.
OAuth uses a tenant-aware discovery URL and the correct scope resource.
New APIs and options 6
Configure maximum attempts, minimum and maximum backoff, and overall timeout via connect() for both backends.
Opt in per connection to the native kernel backend; Thrift remains the default.
ConnectionOptions accepts caller-supplied headers through customHeaders.
Statement-level query tag support was added, allowing developers to tag individual statements.
Token federation support was added with custom token providers.
Metric view metadata support was added.
Performance 1
The package is no longer required when it is not needed.
Behavior and default changes 6
Telemetry now emits auth_type.
Telemetry now emits driver_connection_params.
Telemetry now emits sql_operation.
The driver parses ?o=<workspaceId> from httpPath and injects x-databricks-org-id on Thrift, telemetry, and feature-flag requests for SPOG routing.
Telemetry is enabled by default, with priority controlled by a feature flag.
AI coding agents are detected and identified in the User-Agent header.
Fixes and other changes 4
Fixes a promise-rejection leak during CloudFetch prefetch.
The kernel backend aligns with Thrift for query parameters, metadata, TLS/mTLS, headers, proxies, retries, query tags, cancellation, operation metadata, types, and logger output.
Transient network errors are retried.
Final telemetry flushes are no longer dropped on client.close() because of a close-ordering bug.