Skip to content

Document psycopg3 driver switch for PostgresHook connections#70360

Merged
shahar1 merged 1 commit into
apache:mainfrom
shahar1:postgres-changelog-hook-driver-scope
Jul 24, 2026
Merged

Document psycopg3 driver switch for PostgresHook connections#70360
shahar1 merged 1 commit into
apache:mainfrom
shahar1:postgres-changelog-hook-driver-scope

Conversation

@shahar1

@shahar1 shahar1 commented Jul 24, 2026

Copy link
Copy Markdown
Contributor

The 7.0.0 breaking-change notes in the Postgres provider changelog describe the
psycopg3 switch purely in terms of the metadata database on Airflow 3.4.0+,
with [database] sql_alchemy_conn / sql_alchemy_conn_async given as the way to
stay on psycopg2 / asyncpg.

That leaves out the larger half of the change. PostgresHook picks its driver
independently of the metadata-database settings — it selects psycopg3 whenever
SQLAlchemy 2.x is importable alongside psycopg, and 7.0.0 makes
psycopg[binary] a default dependency:

https://github.com/apache/airflow/blob/main/providers/postgres/src/airflow/providers/postgres/hooks/postgres.py#L38-L49

So a user on Airflow 3.2 or 3.3 reads the current notes, concludes nothing
changes for them until 3.4, and silently gets a different driver for every task
connection on upgrade — with no connection-level or config-level opt-out, since
the sql_alchemy_conn workaround only governs the metadata DB.

This adds a third note covering that scope. Affected-version claims were checked
against each branch's SQLAlchemy requirement:

Airflow SQLAlchemy Hook driver
2.11, 3.0 capped <2.0 psycopg2 (unaffected)
3.1 >=1.4.54, constraints pin 1.4.54 psycopg2 by default; psycopg3 if upgraded to SQLAlchemy 2.x
3.2, 3.3 >=2.0.48 psycopg3

The google, pgvector and amazon integrations import USE_PSYCOPG3 (or
replicate the check) and follow the same selection; a Celery result_backend
derived from the metadata-database URL follows it too, unless
[celery] result_backend is set explicitly.

Docs-only change. No newsfragment — providers do not consume them.

related: #69526, #69089


Was generative AI tooling used to co-author this PR?
  • Yes — Claude Code (Fable 5)

Generated-by: Claude Code (Fable 5) following the guidelines

The 7.0.0 breaking-change notes describe only the metadata database, so a
user on Airflow 3.2 or 3.3 reading them concludes they are unaffected until
3.4. In fact PostgresHook picks its driver independently, from the installed
SQLAlchemy version, so their task connections switch to psycopg3 on upgrade
with no connection-URL or config opt-out available.
@shahar1
shahar1 merged commit d713e2d into apache:main Jul 24, 2026
70 checks passed
@shahar1
shahar1 deleted the postgres-changelog-hook-driver-scope branch July 24, 2026 08:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants