Database Migrations Guide¶

Version: Arctyk ITSM v0.6.0+
Last Updated: January 2026

Managing Django database migrations.

Creating Migrations¶

There are a couple of ways to run migrations in Arctyk ITSM. Local migrations are applied to your local database and not to the Docker container database. This is a very important distinction. All project-level mirgrations must be created using Docker Compose commands so the changes are made to the Docker database.

Local Migrations¶

Creates a migration that will be applied to your local database.

python src/manage.py makemigrations 

Docker Compose Migrations (Recommended)¶

Creates a migration that will be applied to the Docker container database.

docker compose exec web python src/manage.py makemigrations tickets

Applying Migrations¶

Applying migrations uses the same logic. They must be applied using the same method as they were created. Remember from the previous step, applying migrations at the project-level must be done using Docker Compose commands.

Local Migration¶

If you created the migration as a local mirgration, then you must apply it locally.

python src/manage.py migrate

Docker Compose Migration¶

If you created the migration using Docker Compose as is recommended, you must apply it using Docker Compose commands.

docker compose exec web python src/manage.py migrate

Best Practices¶

• Create and apply migrations at the project-level using Docker Compose commands
• Review migration files before committing
• Avoid modifying existing migrations
• Test migrations on copy of production data

Common Issues¶

UndefinedColumn Error¶

Error:

psycopg.errors.UndefinedColumn: column "field_name" of relation "app_model" does not exist

Cause: Migration is trying to remove/modify a column that doesn't exist in the database. Often happens when:

• Database schema doesn't match migration history
• Migrations were run out of order
• Database was manually modified

Solutions:

Option 1: Fresh Database (Development Only)

docker compose down -v  # Destroys all data
docker compose up -d
docker compose exec web python src/manage.py migrate

Option 2: Fake the Problematic Migration

# Check migration status
docker compose exec web python src/manage.py showmigrations app_name

# Fake specific migration
docker compose exec web python src/manage.py migrate app_name 0018 --fake

Option 3: Reset App Migrations

docker compose exec web python src/manage.py migrate app_name zero
docker compose exec web python src/manage.py migrate app_name

Migration Conflicts¶

Error:

Conflicting migrations detected; multiple leaf nodes in the migration graph

Cause: Two migration files with the same number or conflicting dependencies.

Solution:

# Let Django resolve conflicts automatically
docker compose exec web python src/manage.py makemigrations --merge

Duplicate Migration Names¶

Issue: Auto-generated migration filenames can be misleading (e.g., 0019_remove_field... when actually adding fields).

Solution: Rename migration files to be descriptive:

# Rename to descriptive name
mv src/app/migrations/0019_auto_20260112.py src/app/migrations/0019_add_parent_field.py

Cannot Migrate in Docker¶

Error: Migrations work locally but fail in Docker.

Checklist:

• Ensure .env file exists and is loaded (env_file: .env in docker-compose.yml)
• Check database connection (verify POSTGRES_* variables)
• Ensure database service is running: docker compose ps
• Check logs: docker compose logs db

Rollback Migrations¶

Rollback to specific migration:

docker compose exec web python src/manage.py migrate app_name 0015

Rollback all migrations for an app:

docker compose exec web python src/manage.py migrate app_name zero

Squashing Migrations¶

When you have too many migration files:

# Squash migrations 0001 through 0020 into one
docker compose exec web python src/manage.py squashmigrations app_name 0001 0020

Docker-Specific Commands¶

All migration commands should be run inside the Docker container:

# Check migration status
docker compose exec web python src/manage.py showmigrations

# Apply migrations
docker compose exec web python src/manage.py migrate

# Create new migrations
docker compose exec web python src/manage.py makemigrations

# List all migrations
docker compose exec web python src/manage.py showmigrations --list

Learn more about common Docker Compose commands in Docker Reference.