# What changed in databricks-sql-connector

> 77 changes in databricks-sql-connector 3 to 4 from its official release notes, upgrade guides and advisories: 12 breaking, 1 deprecations, 2 security, 28 new APIs and options. Each one cited. Sources checked 2026-11-15. HTML: https://unstale.sh/pypi/databricks-sql-connector/

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

## databricks-sql-connector 4

### Breaking changes

- Rejects an mTLS private key when no client certificate is supplied, and identifies missing or empty client certificate and key files in connection errors. (4.6.0) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v4.6.0)
- The minimum supported Python version is now 3.10; Python 3.8 and 3.9 are no longer supported. (4.4.0) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v4.4.0)
- The kernel wheel requires Python 3.10 or newer; on older interpreters the extra is a no-op and enabling the kernel raises ImportError. (4.3.0) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v4.3.0)
- The default for use_hybrid_disposition changes to False. (4.2.2) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v4.2.2)
- The SQLAlchemy dialect is now provided in a separate package, split from the core connector package. (4.0.0) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v4.0.0)
- Pyarrow is now an optional dependency; users who need Arrow must install pyarrow explicitly. (4.0.0) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v4.0.0)

### Security

- Allows Apache Thrift 0.25.x, including security fixes while preserving support for large Thrift results. (4.7.0) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v4.7.0)
- Allows OAuthlib 4.x, including security fixes while preserving support for large Thrift results. (4.7.0) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v4.7.0)

### Deprecations

- SEA is deprecated in favor of the kernel backend. (4.5.0) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v4.5.0)

### New APIs and options

- Adds a kernel-only option, defaulting to False, that returns GEOMETRY / GEOGRAPHY values as SRID/WKB objects instead of WKT/EWKT strings. (4.7.0) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v4.7.0)
- Adds opt-in support, defaulting to False, for escaping catalog names in metadata queries on Thrift and kernel connections. (4.7.0) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v4.7.0)
- Kernel connections now support JWT private-key M2M and Azure Entra authentication. (4.5.0) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v4.5.0)
- Adds an option to enable token caching for kernel U2M authentication. (4.5.0) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v4.5.0)
- Adds an install extra for the native kernel client. (4.3.0) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v4.3.0)
- Kernel logs are available through Python logging under this logger. (4.3.0) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v4.3.0)
- Adds an opt-in per-connection kernel backend using the SEA HTTP transport; the default remains Thrift. (4.3.0) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v4.3.0)
- Adds a mode for complying with the Retry-After header. (4.1.5, 4.2.7) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v4.2.7), [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v4.1.5)
- SPOG routing now supports account-level vanity URLs. (4.2.6) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v4.2.6)
- Statement-level query_tags support is available for the SEA backend. (4.2.6) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v4.2.6)
- query_tags can now be specified as a dict when creating a connection. (4.2.6) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v4.2.6)
- execute methods now support a query_tags parameter. (4.2.6) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v4.2.6)
- A utility method was added to normalize the HTTP protocol in the HTTP path. (4.2.4) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v4.2.4)
- Adds a configuration option to disable transaction operations. (4.2.1) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v4.2.1)
- Adds support for multi-statement transactions. (4.2.0) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v4.2.0)
- A new session conf enables metric view metadata. (4.1.4) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v4.1.4)
- Adds token federation support for the Databricks SQL Python Driver. (4.1.4) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v4.1.4)

### Performance

- Apache Thrift is lazy-loaded for kernel and SEA connections. (4.5.0) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v4.5.0)
- Telemetry latency logging is optimized to reduce overhead. (4.2.2) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v4.2.2)

### Behavior and default changes

- Lakehouse Real-Time sessions retain session affinity. (4.9.0) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v4.9.0)
- Feature-flag values are shared across connections to the same workspace, with typed reads and coordinated refreshes. (4.7.0) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v4.7.0)
- When a warehouse rejects the default Thrift protocol with SQLSTATE KP001, the session is reopened on the kernel backend and that warehouse is remembered so later connections skip Thrift, unless a backend was explicitly chosen. (4.6.0) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v4.6.0)
- Kernel connections now forward telemetry, socket timeout, OAuth, identity-federation, and row-limit settings. (4.5.0) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v4.5.0)
- REMOVE staging operations no longer require this setting because removing a remote file does not touch the local filesystem. (4.4.0) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v4.4.0)
- Dependency constraints now allow pandas 3.x. (4.2.7) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v4.2.7)
- Telemetry unwraps TokenFederationProvider to report the inner authentication mechanism and flow. (4.2.7) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v4.2.7)
- PyArrow table concatenation now uses promote_options as the default. (4.2.6) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v4.2.6)
- The User-Agent header now includes AI coding agent detection. (4.2.6) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v4.2.6)
- Circuit breaker behavior changes using pybreaker. (4.2.2) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v4.2.2)
- Telemetry is batched at the host level to reduce rate limiting. (4.2.2) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v4.2.2)
- Telemetry is enabled by default. (4.2.2) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v4.2.2)
- Makes the Python telemetry event model consistent with JDBC. (4.2.0) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v4.2.0)

### Fixes and other changes

- Re-fetching or concurrently polling async statements on the kernel backend preserves the originating session. (4.9.0) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v4.9.0)
- Fixes result fetching for queries that return duplicate column names. (4.8.0) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v4.8.0)
- Forwards `_pool_maxsize` to supported Databricks SQL Kernel versions. (4.6.0) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v4.6.0)
- Fixes telemetry for asynchronous statements. (4.5.0) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v4.5.0)
- Empty metadata filters are now preserved. (4.5.0) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v4.5.0)
- On the Thrift backend, DML statements set `cursor.rowcount` to the server's affected-row count; `executemany` aggregates counts across parameter sets. SELECT and statements without a reported count still return -1. (4.4.0) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v4.4.0)
- Reverts the Thrift 0.23.0 bump that broke installation on DBR LTS. (4.3.0) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v4.3.0)
- Aligns kernel behavior with Thrift for cursor state, metadata, DML rowcount, async state, cancellation, staging and volume operations, and structured error context. (4.3.0) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v4.3.0)
- Empty chunks are removed during CloudFetch concatenation. (4.2.7) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v4.2.7)
- SPOG org-id is extracted from the cluster http_path for non-Thrift requests. (4.2.7) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v4.2.7)
- Float inference now uses the 64-bit DoubleParameter instead of FloatParameter. (4.2.6) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v4.2.6)
- The dependency manager now handles PEP 440 compatible release syntax. (4.2.6) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v4.2.6)
- Fixed feature-flag endpoint retries in the gov region. (4.2.5) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v4.2.5)
- Added support for pandas versions below 2.4.0. (4.2.3) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v4.2.3)
- Added support for pandas 2.3.3 on Python versions below 3.14. (4.2.3) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v4.2.3)

## databricks-sql-connector 3

### Breaking changes

- PyArrow concatenation now merges with promote options by default, which may affect how concatenated results are produced. (3.7.5) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v3.7.5)
- Native parameterized SQL queries are supported; they require DBR 14.2 and above. (3.0.0) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v3.0.0)
- The minimum pyarrow version is raised to 14.0.1 in response to CVE-2023-47248. (3.0.0) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v3.0.0)
- Python 3.7 is no longer supported. (3.0.0) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v3.0.0)
- The dialect supports SQLAlchemy 2.0 and above and drops support for SQLAlchemy 1.x. (3.0.0) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v3.0.0)
- Cloud fetch is enabled by default; set use_cloud_fetch=False when building databricks.sql.client to disable it. (3.0.0) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v3.0.0)

### New APIs and options

- The SQLAlchemy dialect supports reading and writing composite keys. (3.0.0) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v3.0.0)
- The SQLAlchemy dialect supports reading and writing ForeignKeyConstraint. (3.0.0) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v3.0.0)
- The SQLAlchemy dialect supports writing Identity to tables for autoincrementing primary keys. (3.0.0) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v3.0.0)
- The SQLAlchemy dialect supports LIMIT and OFFSET for paging through results. (3.0.0) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v3.0.0)
- The SQLAlchemy dialect supports reading and writing PrimaryKeyConstraint. (3.0.0) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v3.0.0)
- A _retry_max_redirects configuration option is added. (3.0.0) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v3.0.0)
- The SQLAlchemy dialect adds support for the TIME type. (3.0.0) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v3.0.0)
- The SQLAlchemy dialect adds support for the TIMESTAMP type. (3.0.0) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v3.0.0)
- The SQLAlchemy dialect adds support for the TIMESTAMP_NTZ type. (3.0.0) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v3.0.0)
- The SQLAlchemy dialect adds support for the TINYINT type. (3.0.0) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v3.0.0)
- The SQLAlchemy dialect supports reading and writing from views. (3.0.0) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v3.0.0)

### Performance

- The SQLAlchemy dialect caches metadata calls. (3.0.0) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v3.0.0)

### Behavior and default changes

- _enable_v3_retries is set to True, and users are warned if they override it. (3.0.0) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v3.0.0)
- The SQLAlchemy dialect was completely rewritten. (3.0.0) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v3.0.0)

### Fixes and other changes

- The SQLAlchemy dialect supports Numeric type scale and precision, such as Numeric(10,2). (3.0.0) — [release notes](https://github.com/databricks/databricks-sql-python/releases/tag/v3.0.0)