| name | saleor-django-migration |
| description | Generate Django schema migrations for the Saleor codebase using manage.py makemigrations. Use when (1) a new Django model is created, (2) model fields are added/altered/removed, (3) user explicitly asks to create a migration. This skill covers ONLY synchronous schema migrations (CreateModel, AddField, AlterField, RemoveField, etc.) — NOT data migrations with RunPython or RunSQL. If unsure whether the migration is schema-only, ask the user. |
Saleor Django Schema Migration
Scope
This skill handles schema-only migrations: CreateModel, AddField, AlterField, RemoveField, AddIndex, AddConstraint, etc. It does NOT cover:
- Data migrations (RunPython, RunSQL with data changes)
- Async/background migrations (celery tasks, post_migrate signals)
If the change requires data transformation, stop and ask the user.
Critical Rules
- NEVER write migration files by hand. Always let Django generate them.
- ALWAYS use
./manage.py makemigrations to generate migrations.
- Activate the virtual environment first — run
. .venv/bin/activate before any manage.py command.
- If database connection fails, stop and ask the user to start the database.
Workflow
Step 1: Make model changes
Edit the Django model file(s) as needed. Do not touch any migration files.
Step 2: Generate migration
. .venv/bin/activate && python manage.py makemigrations
If Django asks interactive questions (e.g. "Did you rename field X to Y?"), answer based on the model changes you made.
Step 3: Read and analyze the generated migration
Read every generated migration file. Verify:
- It contains only schema operations (CreateModel, AddField, AlterField, RemoveField, AddIndex, etc.)
- Dependencies look correct
- No unexpected operations
Step 4: Apply separation rules
Apply these rules to the generated migration(s):
Rule A — One model per migration for new models:
If the migration creates MORE THAN ONE new model (multiple CreateModel operations), split them. Generate each separately:
python manage.py makemigrations <app>
If Django generates them together, delete the combined migration, then create models one at a time (add one model to models.py, run makemigrations, repeat).
Rule B — One field change per migration:
If the migration alters MORE THAN ONE field within a single model (e.g. two AddField or two AlterField operations on the same model), split into separate migrations — one per field. Delete the combined migration, make one field change at a time, and run makemigrations after each.
Exceptions (do NOT split):
- A
CreateModel with all its fields is one operation — do not split the fields of a new model
- Cross-model dependencies where Django requires them together (e.g. ForeignKey + related model creation)
- Field + its index/constraint in the same migration is acceptable when auto-generated together
Step 5: Verify
Run the check command to confirm no pending migrations remain:
python manage.py makemigrations --check --dry-run
Expected output: No changes detected — meaning all model changes are captured in migrations.
Error Handling
| Error | Action |
|---|
django.db.utils.OperationalError: could not connect | Ask user to start the database |
Conflicting migrations detected | Stop and let user decide |
ModuleNotFoundError | Virtual environment not activated — run . .venv/bin/activate |
Tips
- Rely on autogenerated migrations for correct timestamps, sequential numbers, dependencies, and field definitions. If you must hand-edit (e.g. to split), regenerate rather than edit — delete the migration, adjust models.py, and re-run makemigrations.
- When splitting, let Django figure out dependencies between the new smaller migrations.
- Check the newest existing migration in the app (
ls saleor/<app>/migrations/ | tail -5) before generating, so you can confirm the new migration number is sequential.
