Skip to content

Migrate API v1 persistence to SQLAlchemy and Alembic - #3788

Draft
anth-volk wants to merge 76 commits into
masterfrom
agent/stage7-v1-orm-alembic
Draft

Migrate API v1 persistence to SQLAlchemy and Alembic#3788
anth-volk wants to merge 76 commits into
masterfrom
agent/stage7-v1-orm-alembic

Conversation

@anth-volk

@anth-volk anth-volk commented Aug 7, 2026

Copy link
Copy Markdown
Collaborator

Fixes #3787

Summary

  • Migrates API v1 persistence to service-owned SQLAlchemy 2 Sessions and direct mapped models.
  • Keeps routes and legacy endpoints limited to validation, service calls, and response serialization; they no longer construct or pass Sessions.
  • Removes the DAO, repository, unit-of-work, raw database facade, and session-manager compatibility layers.
  • Makes simulation and report multi-model writes atomic and returns immutable result objects for orchestration workflows.
  • Keeps database sessions closed during household calculation, simulation-gateway calls, and Claude streaming.
  • Retains the autogenerated Alembic baseline, read-only schema comparison, and model-agnostic migration guidance.
  • Documents local SQLite bootstrapping as temporary infrastructure scheduled for replacement by a shared cache in Stage 8.

Canonical SQLAlchemy boundary

  • One lazy Engine and pool are owned per worker process.
  • The Cloud SQL connector supplies DBAPI connections through SQLAlchemy's creator hook; SQLAlchemy owns pooling and connection lifecycle.
  • Application services own short-lived read Sessions and sessionmaker.begin() write transactions.
  • Services query and mutate mapped models directly; internal transaction-scoped helpers may accept a Session.
  • Dependencies are lazily defaulted in production and explicitly injectable in tests.
  • Application startup performs no MySQL DDL, and shutdown disposes Engines and closes Cloud SQL connectors.

Validation

  • Complete migration regression gate: 997 passed (tests/to_refactor, tests/unit, tests/contract, and the budget-window integration test).
  • Architecture tests enforce persistence-free routes/endpoints, persistence-free public service signatures, and continued removal of compatibility abstractions.
  • Transaction tests cover commit, rollback, generated IDs, atomic multi-model writes, and closed sessions during external or compute work.
  • Changed Python modules pass Ruff and formatting checks; git diff --check passes.
  • No schema-model or Alembic revision change was required by the service-owned Session conversion.
  • The existing optional live-schema comparison remains read-only and requires an explicit STAGE7_EXISTING_DATABASE_URL.

Anthony Volk added 30 commits August 6, 2026 17:06
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.

Complete Stage 7 API v1 SQLAlchemy and Alembic migration

1 participant