菜单
Inspect and apply database schema migrations (alembic current/heads, upgrade, downgrade, diverged heads) for Backend.AI components (manager, accountmgr, appproxy)
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Guide for implementing REST and GraphQL APIs (create, get, search, update, delete, purge, scope prefix patterns, admin_ prefix, SearchScope, BaseFilterAdapter, @api_function, Click CLI)
./bai v2 CLI usage for testing/verifying API endpoints and managing resources — entity-command reference, login/config, search patterns, testing workflow (REST API client, NOT the v1 backend.ai CLI)
Guide for writing and managing BEPs (Backend.AI Enhancement Proposals) - creation workflow, document segmentation, context-for-ai blocks, Decision Log
Guide for implementing Backend.AI client SDK and CLI (Session, BaseFunction, @api_function, Click commands, Pydantic models, FieldSpec, output handlers, APIConfig, testing)
Trace a feature across the layered architecture (REST v2, GraphQL, Service, Repository, DB, Errors) and explore the entity source tree — includes how to read the 21k-line supergraph.graphql without loading it whole
Local server management — ./dev start/stop/restart via tmux, startup-crash debugging, pre-flight infra checks, raw component start-server commands, post-change restart workflow
| 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"] |
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.
manager (default) · accountmgr · appproxy
alembic.ini · alembic-accountmgr.ini · alembic-appproxy.iniupgrade (default) · downgradehead (default) · <revision_id> · relative (+1, -1)# 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 |
./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.
| 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 |
git pull → check status → upgrade → start services (/local-dev) → verify.alembic/AGENTS.md): review file → test upgrade → test downgrade (--direction=downgrade --target=-1) → re-upgrade → commit.down_revision per alembic/AGENTS.md (never create merge migrations) before applying./local-dev — start/restart services, infra checkssrc/ai/backend/manager/models/alembic/AGENTS.md — authoring migrations, diverged heads, backports