Postgres 마이그레이션이 안 먹을 때

Postgres 마이그레이션을 실행했는데 조용히 실패하거나, 부분적으로만 적용되는 경우가 있다. 특히 혼자 개발할 때는 로컬 환경과 운영 환경의 차이 때문에 같은 마이그레이션이 한쪽에서는 작동하고 다른 한쪽에서는 작동하지 않을 수 있다.

핵심은 마이그레이션 파일을 의심하기 전에, 현재 스키마 상태와 권한을 먼저 확인하는 것이다.

현재 마이그레이션 상태 확인

Prisma나 다른 마이그레이션 도구를 쓰면, 어디까지 마이그레이션이 적용되었는지 확인한다.

npx prisma migrate status
# 또는 Alembic을 쓰면
alembic current

Postgres 스키마 직접 확인

SQL로 직접 현재 스키마 상태를 본다. 마이그레이션 도구가 예상한 대로 작동했는지 확인한다.

psql -h localhost -U postgres -d mydb -c "\dt"
# 테이블 목록

psql -h localhost -U postgres -d mydb -c "\d tablename"
# 특정 테이블의 컬럼과 인덱스

사용자 권한 확인

Postgres에서는 사용자가 테이블을 생성하거나 수정할 수 없을 수도 있다.

psql -h localhost -U postgres -d mydb -c "GRANT ALL PRIVILEGES ON SCHEMA public TO myuser;"
psql -h localhost -U postgres -d mydb -c "GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO myuser;"

마이그레이션 파일 로그 보기

마이그레이션이 실패한 경우, 도구가 출력한 에러 메시지를 자세히 본다.

# Prisma는 상세 로그를 볼 수 있다
npx prisma migrate deploy --verbose

데이터 충돌 확인

새 NOT NULL 컬럼을 추가하려고 하는데 기존 데이터가 있으면 마이그레이션이 실패한다. 기존 데이터를 보고, 기본값을 설정하거나 데이터를 정리해야 한다.

# 특정 컬럼의 데이터 확인
psql -h localhost -U postgres -d mydb -c "SELECT COUNT(*) FROM tablename WHERE columnname IS NULL;"

로컬과 운영 데이터베이스 비교

로컬에서는 성공했던 마이그레이션이 운영에서 실패할 수도 있다. 운영 데이터베이스의 상태가 다를 수 있기 때문이다.

# 운영 데이터베이스의 스키마 추출
pg_dump -h prod.db.server.com -U postgres --schema-only mydb > schema.sql

# 로컬과 비교
diff <(pg_dump -h localhost --schema-only mydb) schema.sql

마이그레이션 롤백

마이그레이션이 부분적으로 적용되었다면, 롤백하고 다시 시도해야 할 수도 있다.

# Prisma
npx prisma migrate resolve --rolled-back migrationname

# 또는 수동으로 롤백 SQL 실행
psql -h localhost -U postgres -d mydb < rollback.sql

1. 마이그레이션 상태를 확인한다.
2. Postgres 스키마를 직접 SQL로 본다.
3. 사용자 권한이 충분한지 확인한다.
4. 에러 메시지를 자세히 본다.

마지막 확인

마이그레이션이 성공한 후에는 실제 데이터로 쿼리를 테스트해봐야 한다. 스키마 변경이 기존 쿼리에 영향을 주지는 않는지, 성능이 떨어지지는 않는지 확인한다. 각 마이그레이션 단계를 기록해두면 다음 번 데이터베이스 문제가 나을 때 재사용할 수 있다.