# DB Migrate

> Inspect and apply database schema migrations (alembic current/heads, upgrade, downgrade, diverged heads) for Backend.AI components (manager, accountmgr, appproxy)

- Skill: `lablup/db-migrate` (Agent Skill)
- Install (CLI): `npx skillmds@latest add lablup/db-migrate`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lablup/db-migrate/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: lablup (https://skillmd.com/u/lablup)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/lablup/db-migrate

---


## 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

```bash
# 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

```bash
./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's `down_revision`, or add an empty merge migration when main itself has 2+ heads) before applying.

## Related skills

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