Unique 제약 위반 에러가 나면

배포 후에 갑자기 데이터가 안 보이고 에러 로그에 'unique constraint violation' 같은 메시지가 떨어지는 경우가 있다. 이건 보통 스키마 마이그레이션 과정에서 기존 데이터와 새 제약이 충돌할 때 생긴다.

먼저 어느 필드에서 충돌하는지 확인하기

Unique 제약 에러 메시지에는 보통 어느 컬럼이 충돌했는지 명시되어 있다. 에러를 자세히 읽고, 정확히 어느 테이블의 어느 필드에서 문제가 생겼는지 파악하자. 데이터베이스에 직접 쿼리를 날려서 해당 컬럼의 값들을 확인해보면 좋다.

기존 데이터 중에 중복이 있는지 확인하기

Unique 제약을 새로 추가하려면, 먼저 기존 데이터에 중복이 없어야 한다. 예를 들어 email 컬럼에 unique 제약을 추가하고 싶은데, 기존 데이터에 같은 이메일이 여러 개 있다면 마이그레이션이 실패한다. 다음 쿼리로 확인해보자:

SELECT email, COUNT(*) FROM users GROUP BY email HAVING COUNT(*) > 1;

마이그레이션 순서 확인하기

Prisma나 TypeORM 같은 ORM에서 마이그레이션 파일을 작성할 때, 먼저 중복된 데이터를 정리한 뒤 unique 제약을 추가해야 한다. 마이그레이션을 여러 단계로 나누자. 첫 번째는 데이터 정리, 두 번째는 unique 제약 추가.

배포 환경의 데이터베이스 상태 파악하기

로컬에서는 깨끗한 데이터로 테스트했을 수 있지만, 운영 환경의 데이터베이스에는 여러 달 동안 쌓인 데이터가 있을 수 있다. 마이그레이션을 배포하기 전에 스테이징 환경에서 실제 데이터로 한 번 테스트해보자. 혹은 운영 DB의 백업본을 로컬에 받아서 마이그레이션을 돌려보는 것도 좋은 방법이다.

Unique 제약 추가 시 기본값 전략

기존 테이블에 unique 컬럼을 추가할 때, 기존 행들에 어떤 값을 채울지가 중요하다. 마이그레이션에서 default 값을 지정하거나, 먼저 nullable로 추가한 뒤 데이터를 채운 다음 not-null로 변경하는 방법도 있다. Prisma의 data 옵션으로 기존 행들을 마이그레이션할 때 특정 값으로 채울 수도 있다.

롤백 계획 세우기

Unique 제약 마이그레이션은 신중하게 다루어야 한다. 만약 배포 후에 문제가 생기면 빠르게 롤백할 수 있도록 준비해두자. 마이그레이션을 여러 단계로 나누고, 각 단계마다 이전 상태로 돌아갈 수 있도록 체크포인트를 만들어두는 게 좋다. 운영 환경에서는 절대 한 번에 큰 마이그레이션을 하지 말자.