Part of #257 — Phase 1 step (1).
RFC: #275.
Goal
Add SQLAlchemy and Alembic as server dependencies and stand up the
Alembic skeleton. No migrations are written yet, no runtime code uses
either library yet. Passive infrastructure only.
Scope
- Add to
server/backend/pyproject.toml dependencies (versions are
current latest at the time of writing — bump to latest at PR time):
sqlalchemy>=2.0.49,<2.1
alembic>=1.18.4,<2
uv lock is regenerated and committed; the lockfile carries the
exact resolved versions and content hashes. The lockfile — not the
pyproject.toml bound — is what protects against supply-chain
swaps at install time. Bounds in pyproject.toml exist to express
compatibility intent.
server/backend/alembic.ini.
server/backend/alembic/env.py configured with
render_as_batch=True and reading CQ_DATABASE_URL (fall back to
CQ_DB_PATH for now so existing setups keep working).
- Empty
server/backend/alembic/versions/ directory.
Out of scope
- No baseline migration (handled in the next Phase 1 child — Baseline
Alembic migration + stamp-on-startup logic).
- No startup wiring (handled in the same).
- No store rewrite (handled in the
SqliteStore Phase 1 child).
Acceptance criteria
alembic current runs cleanly against an existing dev SQLite
database (returns nothing — no migrations defined yet).
uv.lock is up to date and committed.
- Existing test suite passes unchanged.
- No change in server runtime behavior.
Definition of Done
- TDD: any new logic introduced (e.g. URL resolution helper if added
in env.py) lands with a failing unit test first, then the
implementation that makes it pass.
- Full server test suite (
make test or equivalent) is green.
- Lint clean (
make lint or uv run pre-commit run --all-files).
- Docs updated where applicable (this issue: a short README note in
server/backend mentioning Alembic is wired up but unused; the
full env-var documentation lands in the CQ_DATABASE_URL Phase 1
child).
Part of #257 — Phase 1 step (1).
RFC: #275.
Goal
Add SQLAlchemy and Alembic as server dependencies and stand up the
Alembic skeleton. No migrations are written yet, no runtime code uses
either library yet. Passive infrastructure only.
Scope
server/backend/pyproject.tomldependencies (versions arecurrent latest at the time of writing — bump to latest at PR time):
sqlalchemy>=2.0.49,<2.1alembic>=1.18.4,<2uv lockis regenerated and committed; the lockfile carries theexact resolved versions and content hashes. The lockfile — not the
pyproject.tomlbound — is what protects against supply-chainswaps at install time. Bounds in
pyproject.tomlexist to expresscompatibility intent.
server/backend/alembic.ini.server/backend/alembic/env.pyconfigured withrender_as_batch=Trueand readingCQ_DATABASE_URL(fall back toCQ_DB_PATHfor now so existing setups keep working).server/backend/alembic/versions/directory.Out of scope
Alembic migration + stamp-on-startup logic).
SqliteStorePhase 1 child).Acceptance criteria
alembic currentruns cleanly against an existing dev SQLitedatabase (returns nothing — no migrations defined yet).
uv.lockis up to date and committed.Definition of Done
in
env.py) lands with a failing unit test first, then theimplementation that makes it pass.
make testor equivalent) is green.make lintoruv run pre-commit run --all-files).server/backendmentioning Alembic is wired up but unused; thefull env-var documentation lands in the
CQ_DATABASE_URLPhase 1child).