Migration Helper

Guide Alembic database migrations through creation, verification, testing, and application.

Updated Aug 23, 2026
One-click install
npx skills add https://github.com/lwilly3/api.audace --skill migration-helper-lwilly3
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: Migration Helper
Source: https://github.com/lwilly3/api.audace/tree/main/.github/skills/migration-helper
Command: npx skills add https://github.com/lwilly3/api.audace --skill migration-helper-lwilly3

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

This Skill provides a comprehensive guide to safely manage database schema migrations using Alembic, preventing data loss and ensuring smooth upgrades and rollbacks.

Core Features & Use Cases

  • Safe Migration Workflow: Step-by-step instructions for creating, verifying, testing, and committing Alembic migrations.
  • Data Migration Strategies: Guidance on migrating existing data when altering tables or columns.
  • Preventing Common Pitfalls: Explicit warnings and correct approaches for avoiding data loss and migration errors.
  • Use Case: When adding a new required column to the users table, this Skill ensures you correctly add the column as nullable, populate existing rows with a default value, and then alter it to be non-nullable, all while providing a safe downgrade path.

Quick Start

Follow the mandatory workflow to create a new Alembic migration for a database schema change.

Frequently Asked Questions about Migration Helper

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I add a non-nullable column in Alembic without losing existing data?

To add a non-nullable column in Alembic without data loss, first add the column as nullable, populate existing rows with a default value, then alter it to non-nullable. This safe workflow ensures existing records are updated before enforcing constraints.

What is the best way to test an Alembic downgrade path?

Testing an Alembic downgrade path requires applying the migration, verifying the schema change, then explicitly running the downgrade command to ensure rollback capability. Strict adherence to manual verification and downgrade testing prevents data loss and migration errors.

How do I handle data migration when altering database tables with SQLAlchemy?

When altering database tables with SQLAlchemy, handle data migration by adding nullable columns, populating existing rows with default values, and then applying constraints. This step-by-step process ensures smooth upgrades and rollbacks without losing existing records.

Can I manage foreign keys and indexes safely during database schema migrations?

Yes, you can manage foreign keys and indexes safely during database schema migrations by following a strict workflow. This includes creating, verifying, testing, and committing changes to ensure smooth upgrades and reliable rollback capability without data loss.

Why does my Alembic migration fail when adding a required column to an existing table?

An Alembic migration fails when adding a required column to an existing table because existing rows lack a value. The correct approach is adding the column as nullable, populating existing rows with a default value, and then altering it to be non-nullable.