db-workflow

majiayu000's avatarfrom majiayu000

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.

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026
[SQL and Databases]

When & Why to Use This Skill

This Claude skill provides a comprehensive automation framework for managing database migration workflows using SQLAlchemy and Alembic. It streamlines the process of evolving database schemas by automatically detecting model changes, generating migration scripts, and managing database upgrades, ensuring consistency and reducing the risk of manual errors during backend development.

Use Cases

  • Schema Evolution: Automatically generate and apply Alembic migrations when adding new fields or modifying existing SQLAlchemy models to keep the database in sync with the application code.
  • Database Initialization: Facilitate the creation of new database tables and complex relationships by managing the boilerplate migration logic and ensuring proper import structures.
  • Migration Safety & Review: Implement a structured workflow for reviewing auto-generated migration files, verifying upgrade/downgrade paths, and preventing data loss before applying changes to the local or production database.
  • Troubleshooting & Version Control: Resolve database migration conflicts (such as multiple heads) and audit schema history using integrated Alembic status and history commands.
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