lablup Purpose
Check the schema version and apply or roll back Alembic migrations for Backend.AI components.
When to use: after pulling code with new migrations · check current vs head · apply pending changes · rollback (downgrade) · initial setup.
Parameters
- component (optional):
manager(default) ·accountmgr·appproxy- configs:
alembic.ini·alembic-accountmgr.ini·alembic-appproxy.ini
- configs:
- direction (optional):
upgrade(default) ·downgrade - target (optional):
head(default) ·<revision_id>· relative (+1,-1)
Check status
# manager — shows current + head together
./backend.ai mgr dbschema show
# any component
./py -m alembic -c <config> current # applied revision
./py -m alembic -c <config> heads # latest available
| State | Meaning | Action |
|---|---|---|
| up-to-date | current == head | none |
| behind | current behind head | upgrade (below) |
| diverged | multiple heads | reconcile per alembic/AGENTS.md: repoint your own migration's down_revision, or add an empty merge migration when main itself has 2+ heads |
| no revision | current empty (fresh DB) | upgrade for initial setup |
Apply
./py -m alembic -c <config> <direction> <target>
# examples
./py -m alembic -c alembic.ini upgrade head # manager to latest
./py -m alembic -c alembic-appproxy.ini upgrade head # appproxy
./py -m alembic -c alembic.ini downgrade -1 # rollback one revision
./py -m alembic -c alembic.ini upgrade abc123def456 # specific revision
Re-check status afterwards. Downgrade may remove data or features — verify application compatibility.
Error handling
| Symptom | Cause | Action |
|---|---|---|
| Multiple heads detected | diverged migrations | reconcile per alembic/AGENTS.md (repoint your own down_revision, or add an empty merge migration if main has 2+ heads), then retry |
| Cannot locate revision 'X' | bad revision id / wrong config | ./py -m alembic -c <config> history; check typo & component |
| Foreign key constraint violation | existing data blocks the change | review the migration's data-migration logic; fix data integrity; often needs manual intervention |
| Cannot connect (connection refused :5432) | PostgreSQL down / misconfig | docker ps | grep postgres; see /halfstack |
| Migration file not found | code not pulled / wrong branch | git pull; verify branch |
Safety notes
- Before downgrade: back up the database, review what data is removed, stop active connections, never test on production first.
- After upgrade: verify key features, restart affected services, monitor logs for migration errors.
- Best practices: commit migrations to Git, test both upgrade and downgrade, review autogenerated migrations, keep one logical change per migration.
Workflow integration
- After pulling code:
git pull→ check status → upgrade → start services (/local-dev) → verify. - After authoring a migration (see
alembic/AGENTS.md): review file → test upgrade → test downgrade (--direction=downgrade --target=-1) → re-upgrade → commit. - Merge conflicts: if status shows diverged heads, reconcile per
alembic/AGENTS.md(repoint your own migration'sdown_revision, or add an empty merge migration when main itself has 2+ heads) before applying.
Related skills
/local-dev— start/restart services, infra checkssrc/ai/backend/manager/models/alembic/AGENTS.md— authoring migrations, diverged heads, backports