Hot Item

[Hot Item] 트러블슈팅 #1. AUTH_USER_MODEL 변경 후 migrate 실패 — InconsistentMigrationHistory

devjingood 2026. 3. 9. 20:04

어떤 문제였나요?

이전 포스트에서 PostgreSQL을 연결한 뒤 migrate를 먼저 실행했고, 이후 accounts 앱과 커스텀 User 모델을 추가했습니다. AUTH_USER_MODEL = 'accounts.User'를 settings.py에 등록하고 다시 마이그레이션을 시도했을 때 아래 에러가 발생했습니다.

root@bae9e778ad33:/workspaces/HotItem# python manage.py makemigrations
Migrations for 'accounts':
  accounts/migrations/0001_initial.py
    - Create model User

root@bae9e778ad33:/workspaces/HotItem# python manage.py migrate
...
django.db.migrations.exceptions.InconsistentMigrationHistory:
Migration admin.0001_initial is applied before its dependency
accounts.0001_initial on database 'default'.

makemigrations는 성공했는데 migrate에서 막혔습니다.

원인 분석

에러 메시지를 그대로 읽으면:

admin.0001_initial이 자신이 의존하는 accounts.0001_initial보다 먼저 적용되어 있다.

풀어서 설명하면 이렇습니다.

Django의 admin 앱은 내부적으로 User 모델에 의존합니다. 우리가 AUTH_USER_MODEL을 accounts.User로 바꿨으니, admin은 이제 accounts.0001_initial이 먼저 적용된 후에 실행되어야 합니다.

그런데 이전에 이미 migrate를 한 번 실행했습니다. 그 시점에는 AUTH_USER_MODEL이 Django 기본값(auth.User)이었으므로, admin.0001_initial이 기본 User 테이블을 기준으로 DB에 이미 적용된 상태였습니다.

이후 AUTH_USER_MODEL을 accounts.User로 바꾸면 Django는 "앞으로 admin은 accounts.0001_initial 이후에 실행되어야 한다"고 인식하는데, DB에는 이미 반대 순서로 기록이 남아 있어 충돌이 발생한 것입니다.

[ 현재 DB 상태 ]          [ Django가 기대하는 순서 ]
admin.0001_initial  ←→   accounts.0001_initial
(이미 적용됨)              (아직 적용 안 됨, 먼저 와야 함)

→ 순서 불일치 → InconsistentMigrationHistory

왜 flush로는 해결이 안 됐나요?

가장 먼저 시도한 명령어는 이것이었습니다.

python manage.py flush --no-input

flush는 DB의 데이터(rows) 를 비우는 명령입니다. 그러나 Django가 마이그레이션 적용 기록을 저장하는 django_migrations 테이블의 메타데이터는 지우지 않습니다.

결국 데이터는 사라졌지만 "어떤 마이그레이션이 이미 적용됐는지"에 대한 기록은 그대로 남아 있어, 충돌 상태가 해소되지 않았습니다.

명령어 지워지는 것 지워지지 않는 것

flush 테이블의 데이터(rows) django_migrations 마이그레이션 기록
docker-compose down -v 컨테이너 + 볼륨(DB 전체) 없음 (완전 초기화)

해결 방법 — 볼륨 자체를 삭제하고 재시작

마이그레이션 기록까지 포함한 DB 전체를 날려야 했습니다. Dev Container 터미널이 아닌 로컬 터미널(iTerm2) 에서 아래 명령어를 실행했습니다.

# 1. 컨테이너와 볼륨을 함께 삭제
docker-compose down -v

# 2. 컨테이너를 다시 백그라운드로 실행
docker-compose up -d

-v 플래그가 핵심입니다. down만 하면 컨테이너는 내려가지만 PostgreSQL 데이터가 저장된 Docker 볼륨은 유지됩니다. -v를 붙이면 볼륨까지 함께 삭제되어 DB가 완전히 초기화됩니다.

이후 VS Code에서 Dev Container를 Rebuild했습니다.

Cmd+Shift+P → Dev Containers: Rebuild and Reopen in Container

Rebuild가 완료된 뒤 Dev Container 터미널에서 마이그레이션을 다시 실행했습니다.

python manage.py makemigrations accounts
python manage.py migrate

Migrations for 'accounts':
  accounts/migrations/0001_initial.py
    - Create model User

Operations to perform:
  Apply all migrations: accounts, admin, auth, contenttypes, sessions
Running migrations:
  Applying contenttypes.0001_initial... OK
  Applying accounts.0001_initial... OK   ← 이제 admin보다 먼저 적용됨
  Applying admin.0001_initial... OK
  ...

accounts.0001_initial이 admin.0001_initial보다 먼저 적용된 것을 확인할 수 있습니다.

핵심 교훈

AUTH_USER_MODEL은 프로젝트 시작 시, 첫 migrate 실행 전에 반드시 설정해야 합니다.

Django 공식 문서도 이를 강조합니다. 커스텀 User 모델은 프로젝트 초반에 결정하고, migrate 이전에 등록하는 것이 원칙입니다. 이미 migrate를 진행한 뒤에 변경하면 이처럼 마이그레이션 기록 충돌이 발생합니다.

개발 초기 단계라면 docker-compose down -v로 볼륨을 초기화하는 것이 가장 빠르고 확실한 해결책입니다. 단, 데이터가 쌓인 이후라면 볼륨 삭제는 데이터 손실을 의미하므로 신중하게 판단해야 합니다.