db-workflow

Plabrum's avatarfrom Plabrum

Database migration workflow helper. Use when creating database migrations, modifying SQLAlchemy models, or managing Alembic migrations. Automatically handles model changes, migration creation, and database upgrades.

⭐0stars🔀0forks📁View on GitHub🕐Updated Jan 4, 2026
[SQL and Databases]

When & Why to Use This Skill

This Claude skill provides a comprehensive workflow for managing database migrations using SQLAlchemy and Alembic. It automates the transition from model modifications to database schema updates, ensuring consistency and reducing the risk of manual errors during the development lifecycle. By integrating best practices for migration creation, review, and testing, it helps developers maintain a robust and version-controlled database architecture.

Use Cases

  • Schema Evolution: Seamlessly add, modify, or remove database columns and tables by synchronizing SQLAlchemy models with auto-generated Alembic migrations.
  • Migration Management: Automate the generation, review, and application of migration scripts to maintain a reliable and traceable database schema history.
  • Environment Synchronization: Ensure local, test, and production databases are consistently updated with the latest schema changes using standardized upgrade commands.
  • Conflict Resolution and Testing: Identify and resolve migration version conflicts (multiple heads) and verify both upgrade and downgrade paths through automated testing.
namedb-workflow
descriptionDatabase migration workflow helper. Use when creating database migrations, modifying SQLAlchemy models, or managing Alembic migrations. Automatically handles model changes, migration creation, and database upgrades.

Database Migration Workflow

This skill helps with the complete database migration workflow in this project.

When to use this skill

  • Modifying SQLAlchemy models in backend/app/models/
  • Creating new database tables or columns
  • Changing relationships between models
  • Running database migrations
  • Checking migration status

Workflow Steps

  1. Before modifying models: Check current migration status

    make db-upgrade  # Ensure all migrations are applied

  2. After modifying models: Create migration

    make db-migrate  # Auto-generate migration from model changes

  3. Review migration: Always read the generated migration file in backend/alembic/versions/

    • Verify upgrade() and downgrade() operations
    • Check for data migrations if needed
    • Ensure no data loss operations

  4. Apply migration:

    make db-upgrade  # Apply to local database

  5. Test migration: Run tests to verify schema changes

    make test

Critical Rules

  • NEVER delete the Docker volume pgdata - local database must persist
  • Always review auto-generated migrations before applying
  • Test both upgrade AND downgrade paths
  • For production: coordinate with team before running migrations
  • Row-level security (RLS) policies may need manual updates in migrations

Common Tasks

Add new model field

  1. Add field to SQLAlchemy model
  2. Run make db-migrate
  3. Review generated migration
  4. Run make db-upgrade
  5. Run make test

Create new table

  1. Create new model class in appropriate module
  2. Import model in backend/app/models/__init__.py
  3. Run make db-migrate
  4. Review generated migration
  5. Run make db-upgrade
  6. Run make test

Check migration status

cd backend
uv run alembic current     # Show current revision
uv run alembic heads       # Show latest revision
uv run alembic history     # Show all migrations

Troubleshooting

  • Migration conflict: Multiple heads exist, merge with alembic merge
  • Auto-generation missed changes: Check model imports and table metadata
  • Test database issues: Use DATABASE_URL="postgresql://postgres:postgres@localhost:5433/manageros_test" make db-upgrade