Skip to content

deps: SQLAlchemy 2.1.8, staying on psycopg2 (DEC-134) - #981

Merged
Masterplanner25 merged 4 commits into
mainfrom
feat/sqlalchemy-2.1-psycopg2-url
Nov 18, 2026
Merged

Masterplanner25 merged 4 commits into
mainfrom
feat/sqlalchemy-2.1-psycopg2-url

Conversation

@Masterplanner25

Copy link
Copy Markdown
Owner

DEP-UPGRADE-DEFERRED-1, SQLAlchemy half / DEC-134 (owner chose option A).

SQLAlchemy 2.1 changed the default PostgreSQL driver from psycopg2 to psycopg 3. This package ships psycopg2, and every URL operators set is the bare postgresql://, so #966 failed Integration, Boot Smoke and Upgrade Path with No module named 'psycopg'. 2.1's notes say psycopg2 "remains fully supported" when the URL names it.

The change:

  • AINDY.config.normalize_database_url rewrites a bare postgresql:// to postgresql+psycopg2://.
    • It rewrites the scheme as text, never via make_url, because str(URL)'s escaping also changed in 2.1.
    • An explicit driver, SQLite and empty strings pass through unchanged, and it's idempotent.
  • Every engine the runtime creates wraps its URL in it: db/database.py, db/schema_ops.py, platform_layer/health_service.py ×2, startup.py, and alembic/env.py's get_url. settings.DATABASE_URL still reads exactly as the operator wrote it.
  • Operators change nothing.
  • SQLAlchemy 2.0.52 → 2.1.8 at both pin sites.
  • The three PG integration fixtures that build their own engines from the raw environment URL now normalise it too. test_cli_fresh_interpreter still passes the bare URL to the CLI subprocess, so it also proves the runtime handles one under 2.1.

Guard (tests/unit/test_database_url_driver.py):

  • Census: an AST walk of AINDY/ and alembic/env.py finds every create_engine / engine_from_config, asserts each URL goes through the function, and asserts the census isn't empty. Mutation: unwrapping database.py:75 fails it and names the line.
  • Dialect checks: a normalised URL resolves to the psycopg2 dialect, and a control shows that a bare URL resolves to psycopg 3 on 2.1. That control is the reason the function exists.

Other 2.1 changes, checked against this code:

  • No enum types, computed columns or dataclass mappings here.
  • greenlet is pinned explicitly, so the asyncio-extra change doesn't matter.
  • tags is JSONB, which has its own containment operator, so the JSON .contains() deprecation doesn't apply.
  • ★ Autoflush now also fires before raw text() queries. That could change ordering in sessions that mix ORM writes with text(). The unit subset passes locally on 2.1.8; CI's real-PG Integration, Boot Smoke and Upgrade Path jobs are the judge.

Tests run locally on 2.1.8: the guard suite (12), plus test_runtime_schema_contract, test_fr70_activity_caller, test_effect_compensation, test_lease_fence and test_runtime_alembic_head, all green. Ruff is clean. Only a targeted subset ran because host memory was ~570 MB free.

After merge: unignore SQLAlchemy 2.1.x for Dependabot (it was ignored on #966), or later 2.1 patches won't arrive.

Records: DEC-134, DEP-UPGRADE-DEFERRED-1 (SQLAlchemy half resolved), CLAUDE.md index line.

🤖 Generated with Claude Code

Masterplanner25 and others added 3 commits November 17, 2026 22:38
…l (DEC-134)

SQLAlchemy 2.1 resolves a bare postgresql:// to psycopg 3, which this package
does not ship, so #966 failed every PG job. normalize_database_url rewrites
the bare scheme to postgresql+psycopg2:// as text; every engine in AINDY/ and
alembic/env.py passes its URL through it, guarded by a source-derived census
(mutation-tested). Operators' DATABASE_URLs are unchanged. PG integration
fixtures that build their own engines do the same; the CLI test still passes
the bare URL to the runtime.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…et the 2.1 default

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@Masterplanner25

Copy link
Copy Markdown
Owner Author

Changelog fragment renamed 00-981-…: the app creates its own engines from a bare URL (its alembic/env.py, deploy scripts such as ensure_pgvector.py and replay_app_migrations.py, and its test fixtures). SQLAlchemy reaches it through our pin, so the release carrying this needs the app to name the driver first. The release handoff must lead with it.

… YAML

#981's Integration job failed in runtime-ci.yml's "Verify schema bootstrap
on PostgreSQL" step: an inline create_engine(os.environ["DATABASE_URL"]) the
.py census could not see. latency-floor.yml had the same. psycopg2.connect
calls (upgrade-path-guard.yml) are libpq and keep the bare URL.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@Masterplanner25
Masterplanner25 merged commit 58e4d5c into main Nov 18, 2026
12 checks passed
@Masterplanner25
Masterplanner25 deleted the feat/sqlalchemy-2.1-psycopg2-url branch November 18, 2026 06:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant