# What changed in @databricks/sql

> 40 changes in @databricks/sql 1 to 3 from its official release notes, upgrade guides and advisories: 5 breaking, 3 security, 13 new APIs and options. Each one cited. Sources checked 2026-11-13. HTML: https://unstale.sh/npm/@databricks/sql/

To see which of these apply to a repository, run `npx @unstale/cli init` in it.

## @databricks/sql 3

### Breaking changes

- Returns empty results with the standard schema when a catalog, schema, or table is missing, instead of throwing. (3.0.0) — [release notes](https://github.com/databricks/databricks-sql-nodejs/releases/tag/3.0.0)
- 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. (3.0.0) — [release notes](https://github.com/databricks/databricks-sql-nodejs/releases/tag/3.0.0)

## @databricks/sql 2

### Breaking changes

- Thrift TLS certificates are verified by default, improving connection security. (2.1.0) — [release notes](https://github.com/databricks/databricks-sql-nodejs/releases/tag/2.1.0)
- The minimum supported Node.js version is raised to 20, dropping Node 14, 16, and 18. (2.0.0) — [release notes](https://github.com/databricks/databricks-sql-nodejs/releases/tag/2.0.0)

### Security

- The native kernel backend was upgraded to 1.3.0, including security fixes in the SQL kernel bindings. (2.4.0) — [release notes](https://github.com/databricks/databricks-sql-nodejs/releases/tag/2.4.0)

### New APIs and options

- Adds an option, defaulting to false, to return kernel GEOMETRY / GEOGRAPHY results as { srid, wkb } instead of WKT / EWKT. (2.3.0) — [release notes](https://github.com/databricks/databricks-sql-nodejs/releases/tag/2.3.0)
- Adds an option, defaulting to false, to escape catalog underscores in metadata requests. (2.3.0) — [release notes](https://github.com/databricks/databricks-sql-nodejs/releases/tag/2.3.0)
- The kernel backend adds Azure Entra authentication. (2.1.0) — [release notes](https://github.com/databricks/databricks-sql-nodejs/releases/tag/2.1.0)
- Custom CA and mTLS options are available for configuring Thrift TLS. (2.1.0) — [release notes](https://github.com/databricks/databricks-sql-nodejs/releases/tag/2.1.0)
- Adds disableRowMaterialization for fetch-throughput benchmarks. (2.1.0) — [release notes](https://github.com/databricks/databricks-sql-nodejs/releases/tag/2.1.0)
- Static-token federation is available with the kernel backend. (2.1.0) — [release notes](https://github.com/databricks/databricks-sql-nodejs/releases/tag/2.1.0)
- U2M token caching can be enabled optionally. (2.1.0) — [release notes](https://github.com/databricks/databricks-sql-nodejs/releases/tag/2.1.0)

### Behavior and default changes

- The kernel dependency is now stable and no longer experimental. (2.2.0) — [release notes](https://github.com/databricks/databricks-sql-nodejs/releases/tag/2.2.0)
- Telemetry options are forwarded to the kernel backend. (2.1.0) — [release notes](https://github.com/databricks/databricks-sql-nodejs/releases/tag/2.1.0)

### Fixes and other changes

- Kernel result metadata now preserves DECIMAL precision and scale. (2.3.0) — [release notes](https://github.com/databricks/databricks-sql-nodejs/releases/tag/2.3.0)
- Fixes catalog metadata and required-name validation. (2.3.0) — [release notes](https://github.com/databricks/databricks-sql-nodejs/releases/tag/2.3.0)
- Accepts omitted or empty namespaces in kernel calls. (2.3.0) — [release notes](https://github.com/databricks/databricks-sql-nodejs/releases/tag/2.3.0)
- Default Thrift connections to Reyden/Real-Time SQL warehouses automatically recover onto the kernel backend while preserving structured SQL errors. (2.2.0) — [release notes](https://github.com/databricks/databricks-sql-nodejs/releases/tag/2.2.0)
- The kernel backend now has getTypeInfo() parity. (2.1.0) — [release notes](https://github.com/databricks/databricks-sql-nodejs/releases/tag/2.1.0)
- Interval-type issues in the kernel backend are fixed. (2.1.0) — [release notes](https://github.com/databricks/databricks-sql-nodejs/releases/tag/2.1.0)

## @databricks/sql 1

### Breaking changes

- The kernel backend requires Node >= 18; on older Node, enabling it raises an error directing you to the Thrift backend. (1.16.0) — [release notes](https://github.com/databricks/databricks-sql-nodejs/releases/tag/1.16.0)

### Security

- Clears critical and other non-breaking OSV-Scanner findings through dependency overrides and a dev-toolchain bump, without changing the engine or runtime API. (1.17.0) — [release notes](https://github.com/databricks/databricks-sql-nodejs/releases/tag/1.17.0)
- OAuth uses a tenant-aware discovery URL and the correct scope resource. (1.15.0) — [release notes](https://github.com/databricks/databricks-sql-nodejs/releases/tag/1.15.0)

### New APIs and options

- Configure maximum attempts, minimum and maximum backoff, and overall timeout via connect() for both backends. (1.16.0) — [release notes](https://github.com/databricks/databricks-sql-nodejs/releases/tag/1.16.0)
- Opt in per connection to the native kernel backend; Thrift remains the default. (1.16.0) — [release notes](https://github.com/databricks/databricks-sql-nodejs/releases/tag/1.16.0)
- ConnectionOptions accepts caller-supplied headers through customHeaders. (1.15.0) — [release notes](https://github.com/databricks/databricks-sql-nodejs/releases/tag/1.15.0)
- Statement-level query tag support was added, allowing developers to tag individual statements. (1.14.0) — [release notes](https://github.com/databricks/databricks-sql-nodejs/releases/tag/1.14.0)
- Token federation support was added with custom token providers. (1.13.0) — [release notes](https://github.com/databricks/databricks-sql-nodejs/releases/tag/1.13.0)
- Metric view metadata support was added. (1.13.0) — [release notes](https://github.com/databricks/databricks-sql-nodejs/releases/tag/1.13.0)

### Performance

- The package is no longer required when it is not needed. (1.13.0) — [release notes](https://github.com/databricks/databricks-sql-nodejs/releases/tag/1.13.0)

### Behavior and default changes

- Telemetry now emits auth_type. (1.16.0) — [release notes](https://github.com/databricks/databricks-sql-nodejs/releases/tag/1.16.0)
- Telemetry now emits driver_connection_params. (1.16.0) — [release notes](https://github.com/databricks/databricks-sql-nodejs/releases/tag/1.16.0)
- Telemetry now emits sql_operation. (1.16.0) — [release notes](https://github.com/databricks/databricks-sql-nodejs/releases/tag/1.16.0)
- The driver parses ?o=<workspaceId> from httpPath and injects x-databricks-org-id on Thrift, telemetry, and feature-flag requests for SPOG routing. (1.15.0) — [release notes](https://github.com/databricks/databricks-sql-nodejs/releases/tag/1.15.0)
- Telemetry is enabled by default, with priority controlled by a feature flag. (1.15.0) — [release notes](https://github.com/databricks/databricks-sql-nodejs/releases/tag/1.15.0)
- AI coding agents are detected and identified in the User-Agent header. (1.14.0) — [release notes](https://github.com/databricks/databricks-sql-nodejs/releases/tag/1.14.0)

### Fixes and other changes

- Fixes a promise-rejection leak during CloudFetch prefetch. (1.16.0) — [release notes](https://github.com/databricks/databricks-sql-nodejs/releases/tag/1.16.0)
- The kernel backend aligns with Thrift for query parameters, metadata, TLS/mTLS, headers, proxies, retries, query tags, cancellation, operation metadata, types, and logger output. (1.16.0) — [release notes](https://github.com/databricks/databricks-sql-nodejs/releases/tag/1.16.0)
- Transient network errors are retried. (1.16.0) — [release notes](https://github.com/databricks/databricks-sql-nodejs/releases/tag/1.16.0)
- Final telemetry flushes are no longer dropped on client.close() because of a close-ordering bug. (1.15.0) — [release notes](https://github.com/databricks/databricks-sql-nodejs/releases/tag/1.15.0)