db-migrate

name	db-migrate
description	Inspect and apply database schema migrations (alembic current/heads, upgrade, downgrade, diverged heads) for Backend.AI components (manager, accountmgr, appproxy)
disable-model-invocation	false
tags	["database","alembic","migration"]

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
• 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	fix down_revision per alembic/AGENTS.md (no merge migrations)
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	fix down_revision per alembic/AGENTS.md (no merge migrations), 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, fix down_revision per alembic/AGENTS.md (never create merge migrations) before applying.

Related skills

• /local-dev — start/restart services, infra checks
• src/ai/backend/manager/models/alembic/AGENTS.md — authoring migrations, diverged heads, backports