---

name: alembic-migration-manager description: A skill for managing database migrations with Alembic. Use this for tasks involving Alembic initialization, configuration, creating new migration scripts (both autogenerated and manual), defining upgrade and downgrade logic, handling data migrations, testing migrations, performing rollbacks, and following production deployment best practices for database changes.

Alembic Migration Management

This skill provides a comprehensive guide to managing database schema and data migrations using Alembic.

Core Workflow

1. Initialization & Configuration: Set up Alembic for a new project.

   • See references/01_initialization_and_configuration.md for detailed setup instructions and configuration templates.

2. Generating Migrations: Create new migration files.

   • See references/02_generating_migrations.md for guidance on autogenerate vs. manual creation.

3. Writing Migration Scripts: Implement the upgrade and downgrade logic.

   • See references/03_migration_script_patterns.md for common patterns and examples (creating tables, adding columns).

4. Handling Data Migrations: Perform data backfilling or transformations.

   • See references/04_data_migrations.md for patterns and safety checks.

5. Testing & CI/CD: Ensure migrations are safe and automated.

   • See references/05_testing_and_ci_cd.md for testing strategies and CI/CD integration examples.

6. Deployment & Rollbacks: Manage migrations in production.

   • See references/06_rollbacks_and_production.md for a production checklist and a rollback playbook.

Bundled Resources

• Configuration Templates:
  • assets/alembic.ini.template: A ready-to-use template for alembic.ini.
  • assets/env.py.template: A template for env.py to connect to your database and models.