About zeabur-migration
zeabur-migration is a troubleshooting skill for database migrations stuck during Zeabur deployments, intended for app deployment and migration configuration. It presents two approaches: run migrations during API startup or configure a separate migrator service.
Key features
- 01Identify migration wait loops
- 02Run migrations during API startup
- 03Configure a separate migrator service
- 04Check migration logs for errors
Use cases
- 01Resolve migrations stuck in a waiting state
- 02Add migration steps to API startup
- 03Deploy a dedicated database migrator service
Install
Copy the command and run it in a terminal.
npx skills add https:/After installing, type/zeabur-migrationin Claude Code to confirm it loaded.
Details
From the project READMEZeabur Migration Issues
Always use
npx zeabur@latestto invoke Zeabur CLI. Never usezeaburdirectly or any other installation method. Ifnpxis not available, install Node.js first.
Symptom
Waiting for database migrations to complete...
Waiting for database migrations to complete...
(repeating forever)
Cause
App expects migrations to run separately, but no migrator service exists.
Solutions
Option A: Add migration to API startup (edit template YAML — use the zeabur-template skill for reference)
# In api service — command MUST be inside source
spec:
source:
image: myapp:latest
command:
- /bin/sh
- -c
- "python manage.py wait_for_db && python manage.py migrate && exec ./entrypoint.sh"
Option B: Add migrator service
- name: migrator
spec:
source:
image: same-backend-image
command:
- ./bin/docker-entrypoint-migrator.sh
env:
DATABASE_URL: ...
Option A is simpler - migrations run on API startup and are idempotent (safe to repeat).
To check migration logs for errors, use the zeabur-deployment-logs skill. If the issue is about services starting before dependencies are ready (not migration-specific), use the zeabur-startup-order skill instead.