Imported from David-Li0406/meta-skill-evloving (skill-flow/data/skills-refined-skillclaw-36k/skillsmp/database-migration-3/SKILL.md). Install upstream with npx skills add David-Li0406/meta-skill-evloving --skill database-migration-3. Copyright stays with the author.

Database Migration Skill

Purpose

Use this skill when modifying the database schema (Models) in backend/models/*.py. It ensures migrations are generated, inspected, and applied safely.

Workflow

1. Create Migration (Local)

1. Modify the Model: Ensure your changes in backend/models/*.py are saved.
2. Generate Migration: Run the following command:

   cd backend && .venv/bin/alembic revision --autogenerate -m "<describe_your_change>"

3. Review the file:
   • Locate the new file in backend/alembic/versions/.
   • CRITICAL: Read the file to ensure it ONLY contains the intended changes. If it drops tables or columns unexpectedly, ABORT and investigate.

2. Apply Migration (Local)

1. Upgrade Database:

   cd backend && .venv/bin/alembic upgrade head

2. Verify:
   • Check if the changes are reflected in the database (e.g., table created, column added).
   • You can use psql or run a test script if needed.

3. Commit Strategy

Migrations should be their own atomic commit or grouped with the model change.

git add backend/alembic/versions/
git commit -m "chore(db): add migration for <feature>"