Document psycopg3 driver switch for PostgresHook connections#70360
Merged
shahar1 merged 1 commit intoJul 24, 2026
Conversation
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.
eladkal
approved these changes
Jul 24, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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_asyncgiven as the way tostay on psycopg2 / asyncpg.
That leaves out the larger half of the change.
PostgresHookpicks its driverindependently of the metadata-database settings — it selects psycopg3 whenever
SQLAlchemy 2.x is importable alongside
psycopg, and 7.0.0 makespsycopg[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_connworkaround only governs the metadata DB.This adds a third note covering that scope. Affected-version claims were checked
against each branch's SQLAlchemy requirement:
<2.0>=1.4.54, constraints pin 1.4.54>=2.0.48The
google,pgvectorandamazonintegrations importUSE_PSYCOPG3(orreplicate the check) and follow the same selection; a Celery
result_backendderived from the metadata-database URL follows it too, unless
[celery] result_backendis 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?
Generated-by: Claude Code (Fable 5) following the guidelines