Drop `DISABLE_SQLALCHEMY_CEXT_RUNTIME=1` once SQLAlchemy's cyextensions declare free-thread safety

[lesnik512]

What

The freethreaded CI job (.github/workflows/_checks.yml) sets DISABLE_SQLALCHEMY_CEXT_RUNTIME=1,
and docs/introduction/installation.md tells users to set the same variable for a genuinely
GIL-free process. Both are a workaround for an upstream gap, and both should come out once upstream
closes it.

Why it is there

SQLAlchemy ships cp314t wheels, but its Cython extensions do not declare Py_MOD_GIL_NOT_USED, so
CPython force-re-enables the GIL process-wide on import sqlalchemy. A free-threaded wheel is
necessary but not sufficient for a GIL-free run. asyncpg and pydantic-core are unaffected —
SQLAlchemy is the only offender in the dependency graph.

Reproduced on CPython 3.14.7t against SQLAlchemy 2.0.52 (current latest):

$ python -c "import sys, sqlalchemy; print(sys._is_gil_enabled())"
<frozen importlib._bootstrap>:491: RuntimeWarning: The global interpreter lock (GIL) has been
enabled to load module 'sqlalchemy.cyextension.collections', which has not declared that it can
run safely without the GIL.
True

$ DISABLE_SQLALCHEMY_CEXT_RUNTIME=1 python -c "import sys, sqlalchemy; print(sys._is_gil_enabled())"
False

CPython emits the diagnostic itself, naming sqlalchemy.cyextension.collections. The variable is
SQLAlchemy's own documented switch to the pure-Python implementations of the same behaviour — not a
hack — but the fallback is slower, so it is a real (if small) cost we are paying only to keep the
GIL-off assertion meaningful.

Why it matters at all

The library runs correctly on 3.14t either way; the GIL state does not change outbox semantics. It
matters for a user running other threaded code in the same process, whose parallelism SQLAlchemy's
cyextensions would otherwise kill process-wide. That is the guarantee docs/introduction/installation.md
advertises, and the CI assertion is what keeps it honest.

Done when

• SQLAlchemy's Cython extensions declare Py_MOD_GIL_NOT_USED.
• Re-running the freethreaded job's assertion without the variable still reports
  sys._is_gil_enabled() is False.
• Then: remove the env: entry from the job, the caveat block in
  docs/introduction/installation.md, and the corresponding paragraph in
  docs/adr/0002-free-threading-is-compat-only.md.

Upstream's free-threading work is sqlalchemy/sqlalchemy#12881, which covered building and testing
cp314t wheels and is closed; declaring the extensions themselves GIL-safe was not part of it, so
there is no upstream tracking issue to watch yet. Worth re-checking on each SQLAlchemy minor.

Note

The docs caveat also mentions that the same problem applies to foreign-broker clients used with the
relay feature (for example aiokafka). That half is not ours to fix and stays regardless.

[lesnik512]

This was generated by AI during triage.

Triage outcome: needs-info

Relabeling needs-triage → needs-info. Not closing, and deliberately so — see below.

All three removal sites verified:

Site	Verified
.github/workflows/_checks.yml:73	DISABLE_SQLALCHEMY_CEXT_RUNTIME: 1 under the freethreaded job's env:
docs/introduction/installation.md:42-50	the !!! note caveat block
docs/adr/0002-free-threading-is-compat-only.md:12-14, 29-33	the rationale paragraph and the revisit trigger

Upstream has not moved. SQLAlchemy's current latest release on PyPI is 2.0.52 — the exact version this issue reproduced against — and uv.lock pins that same 2.0.52 under a >=2.0 constraint. So the workaround is still load-bearing today, and the "Done when" preconditions are unmet.

Concrete next recheck point: SQLAlchemy 2.1.0 is at rc1 on PyPI. The body says "worth re-checking on each SQLAlchemy minor", and 2.1.0 is the next one — that release is the moment to re-run the freethreaded job's assertion without the variable, rather than an open-ended watch.

Why this does not close as wontfix, despite the revisit trigger being an external event:

1. ADR 0002 points at it by number. Its revisit trigger ends "Tracked as Drop DISABLE_SQLALCHEMY_CEXT_RUNTIME=1 once SQLAlchemy's cyextensions declare free-thread safety #160." Closing this would leave the ADR pointing at a closed issue — the same stranded-pointer defect flagged in modern-di#436, where pyproject.toml's comment outlived the issue it cited.
2. The ADR classifies it as scheduled work, not a judgement call: "This is the one part of the decision that is scheduled work rather than a judgement call — the workaround is upstream's to remove, and until it does, the env var is load-bearing." An item its own ADR calls scheduled is not a wontfix.

That is the distinction from modern-di#441, which did close: there, no artifact in the repo depended on the issue existing, and the governing policy already lived in the docs. Here, an ADR names this issue as its tracker.

What would move it: SQLAlchemy declaring Py_MOD_GIL_NOT_USED on its Cython extensions, confirmed by the job's assertion reporting sys._is_gil_enabled() is False without the variable set.

Unchanged: the foreign-broker-client half of the docs caveat (for example aiokafka) is not ours and stays regardless of what SQLAlchemy does. Whoever removes the SQLAlchemy paragraph must leave that one.