ai-agents-workspace-starter: Skill for Claude Code

Skill: Database Migration

Database migration procedures using Alembic with SQLAlchemy async.

Creating a New Migration

1. Define or Update the Model

Create or update SQLAlchemy model in backend/app/infrastructure/adapters/db/models.py. Ensure the model inherits from Base and has proper __tablename__.

1b. Check the migration naming convention

Before generating a migration, the agent MUST inspect existing files in backend/alembic/versions/.

Rules:

• If the project uses sequential numbering, e.g. 0001_..., 0002_..., the agent MUST continue the same convention
• If the project uses any other established naming scheme, the agent MUST preserve it exactly
• The agent MUST NOT invent its own migration filename format
• The agent MUST NOT create random, generic, or low-signal names such as update, fix, changes, test, or misc
• The migration description must be short, technical, descriptive, and in English
• If the repository does not yet contain migrations or an explicit convention, the agent must ask the user which format should be used

2. Generate Migration

# Auto-generate from model changes
make db-migrate msg="add users table"

# Equivalent Docker command:
# docker compose -f infra/docker-compose.yml exec backend alembic revision --autogenerate -m "add users table"

3. Review Migration

Check the generated file in backend/alembic/versions/:

• Are all columns correct?
• Are indexes and constraints included?
• Does the migration handle upgrade() and downgrade() properly?
• Is the MariaDB dialect compatible? (no PostgreSQL-specific syntax)

4. Apply Migration

# Apply all pending migrations
make db-upgrade

# Equivalent: alembic upgrade head

5. Verify

# Check current migration status
make db-shell
# Then: SHOW TABLES; DESCRIBE my_table;

Rollback

# Rollback last migration
make db-downgrade

# Equivalent: alembic downgrade -1

Data Migrations

For seed data or data transformations, use op.execute() with raw SQL in upgrade() and matching DELETE in downgrade().