PostgreSQL 오류 코드 23505 - 중복 키 에러 해결 방법
PostgreSQL 오류 코드 23505 - 중복 키 에러 해결 방법
PostgreSQL을 사용하다 보면 누구나 한 번쯤 마주치는 오류가 있습니다. 바로 오류 코드 23505, 일명 중복 키 에러입니다. 주로 INSERT나 UPDATE 작업 중에 발생하며, 이미 존재하는 고유한 값(Primary Key 또는 Unique Constraint)을 다시 입력하려고 할 때 뜨게 됩니다. 이 에러를 처음 보면 당황할 수 있지만, 원인과 대처법을 알면 빠르게 해결할 수 있어요. 이 글에서는 중복 키 에러의 원인부터, 다양한 해결 방법, 그리고 실전에서 활용할 수 있는 팁까지 알차게 정리해드립니다!
목차
📌 오류 코드 23505란?
PostgreSQL의 오류 코드 23505는 "unique_violation"이라는 의미를 가지고 있습니다. 이는 데이터베이스 테이블에 PRIMARY KEY나 UNIQUE 제약 조건이 걸린 컬럼에 중복된 값을 삽입하거나 수정하려 할 때 발생합니다.
예를 들어, 이미 존재하는 이메일 주소를 다시 등록하려 하면 PostgreSQL은 이렇게 응답합니다:
ERROR: duplicate key value violates unique constraint "users_email_key"
에러 메시지는 친절하게 어느 테이블, 어떤 컬럼에서 문제가 발생했는지 알려주므로, 이를 단서로 원인을 추적할 수 있습니다.
📌 중복 키 에러가 발생하는 주요 케이스
중복 키 에러는 다음과 같은 상황에서 자주 발생합니다:
- 자동 증가 키 누락: ID를 수동으로 입력하거나, SEQUENCE와 싱크가 맞지 않을 때
- 중복 데이터 삽입: 이미 존재하는 데이터를 다시 입력하려 할 때
- 다중 요청 경합: 동시에 여러 트랜잭션이 같은 값을 삽입하려 할 때
- 업데이트 로직 오류: 조건문 없이 무분별하게 INSERT/UPDATE를 수행할 때
이처럼 다양한 원인 때문에 오류가 발생할 수 있으니, 상황별로 원인을 정확히 파악하는 것이 중요합니다.
📌 해결 방법과 우회 전략
중복 키 에러를 해결하기 위한 방법은 상황에 따라 다를 수 있습니다. 대표적인 방법들은 다음과 같습니다:
1. INSERT 전에 존재 여부 확인하기
SELECT 쿼리로 데이터가 이미 존재하는지 체크한 후, 없을 때만 INSERT를 수행합니다.
2. UPSERT(ON CONFLICT) 사용하기
PostgreSQL에서는 ON CONFLICT 구문을 사용해 충돌 발생 시 업데이트나 무시를 할 수 있습니다:
INSERT INTO users (email) VALUES ('test@example.com') ON CONFLICT (email) DO NOTHING;
3. SEQUENCE 리셋하기
자동 증가 컬럼의 SEQUENCE가 꼬였을 경우, 현재 최대값을 기준으로 리셋할 수 있습니다:
SELECT setval('your_table_id_seq', (SELECT MAX(id) FROM your_table));
4. 트랜잭션과 Lock을 적절히 사용하기
동시성 문제로 인한 중복 삽입을 막기 위해, 트랜잭션과 적절한 Lock을 걸어 제어할 수도 있습니다.
📌 실전 사례로 보는 문제 해결
실제 스타트업 프로젝트를 진행하면서, 회원 가입 기능에서 23505 오류를 경험한 적이 있습니다.
문제 상황
여러 사용자가 동시에 같은 이메일로 회원가입을 시도할 때, 중복 키 에러가 빈번하게 발생했습니다. 문제는 서버에서 중복 체크를 하지 않고, DB에 직접 INSERT만 시도했기 때문입니다.
해결 방법
- 1차: 클라이언트 측 중복 검사 강화
- 2차: 서버 API에서 INSERT 시도 시
ON CONFLICT DO NOTHING전략 사용 - 3차: 회원가입 성공/실패를 사용자에게 정확히 피드백
이렇게 조치한 이후, 중복 키로 인한 서버 에러가 거의 발생하지 않았고, 사용자 경험도 개선되었습니다.
📌 추가 팁과 주의사항
마지막으로, 중복 키 에러를 예방하기 위해 다음을 추천합니다:
- 고유성 체크를 항상 서버 단에서 최종 확인할 것
- 다중 삽입 시, 트랜잭션 처리를 신경 쓸 것
- SEQUENCE는 주기적으로 점검할 것
- ON CONFLICT 구문을 상황에 맞게 적극 활용할 것
📌 추가 경험과 실용적인 팁
PostgreSQL 오류 코드 23505, 중복 키 에러는 저도 개발자로서 참 여러 번 경험했습니다. 특히 빠르게 MVP를 개발하거나, 팀 프로젝트 중에 급하게 기능을 붙이다 보면 예상치 못한 중복 삽입이 문제를 일으키곤 했어요.
1. 급할수록 기본에 충실하자
하루는 데모 준비 때문에 새벽까지 코드를 짜다가, 회원가입 로직에 중복 체크를 빼먹은 채 배포했던 적이 있어요. 결과는? 데모 중 23505 에러가 터졌습니다. 😭 그때 느꼈던 건 "아무리 시간이 없어도 기본 검증은 절대 빼먹지 말자"는 거였어요.
조금 귀찮더라도, INSERT 전에 SELECT로 존재 여부를 확인하거나, ON CONFLICT 구문을 써서 예외를 방지하는 습관을 들이면 확실히 사고를 줄일 수 있습니다.
2. 사후 대처보다 사전 예방
오류가 발생한 후 수정하는 것도 방법이지만, 가장 좋은 건 오류 자체를 예방하는 거죠. 그래서 저는 프로젝트 초기 스키마 설계 단계에서 반드시 다음과 같은 체크리스트를 사용합니다:
- 모든 유니크 제약 조건을 명확하게 정의했는가?
- 자동 증가 컬럼(SEQUENCE)이 제대로 연결되어 있는가?
- 중복 삽입이 예상되는 경로에는 예외 처리나 우회 로직이 있는가?
이 체크리스트를 적용하면서 부터 중복 키 에러가 정말 많이 줄었어요.
3. 개발 환경과 운영 환경은 다르다
로컬 개발 환경에서는 혼자 테스트하니까 중복 문제가 잘 안 드러나요. 하지만 운영 서버에서는 수십 명, 수백 명의 사용자가 동시에 요청을 보내죠. 이럴 때는 경합 조건(Race Condition)이 쉽게 터집니다.
그래서 저는 운영 환경 배포 전, 부하 테스트(Load Testing)를 꼭 해봤습니다. JMeter나 k6 같은 툴을 사용해서 수백 개 요청을 동시에 보내보고, 문제가 없는지 확인했어요. 이런 습관이 운영 중 오류를 줄이는 데 정말 큰 도움이 됐습니다.
4. "DO NOTHING" vs "DO UPDATE" 전략 선택
ON CONFLICT 구문에는 크게 두 가지 선택지가 있어요: 하나는 아무것도 하지 않는 DO NOTHING, 다른 하나는 값을 업데이트하는 DO UPDATE입니다.
예를 들어, 이미 가입된 이메일이면 무시하고 넘어가야 할 때는 DO NOTHING이 맞고, 최신 정보를 유지하고 싶을 땐 DO UPDATE가 더 나은 선택이죠.
상황에 따라 전략을 다르게 선택하는 센스가 필요합니다. 저도 처음에는 무조건 DO NOTHING만 썼다가, 나중에 업데이트가 필요한 케이스를 놓쳐서 데이터 싱크가 엉망이 된 경험이 있어요. 😅
5. 에러 메시지는 소중한 단서다
23505 에러가 발생하면 단순히 "에러 났네?" 하고 넘기기 쉬운데, 실제로는 에러 메시지에 소중한 정보가 담겨 있어요.
예를 들면, 어느 테이블, 어떤 제약 조건이 위반되었는지 구체적으로 알려줍니다. 이 정보를 꼼꼼히 읽고, 관련된 데이터 흐름을 추적해보면 원인을 정확히 파악할 수 있어요. 에러 로그를 습관처럼 캡처해두고, 차분히 분석하는 습관이 정말 중요합니다.
Tip: 중복 키 에러를 무조건 "예외 처리"로 덮어버리는 것은 임시방편일 뿐입니다. 근본적인 데이터 플로우를 이해하고 고치는 게 진짜 해결이에요!
6. 팀 작업 시 더 신경 쓸 부분
혼자 개발할 때보다, 팀 프로젝트에서는 중복 키 문제에 더 민감해야 합니다. 특히 테이블 설계나 API 명세를 다른 개발자들과 명확히 공유해야 해요.
제가 겪은 경우, 백엔드 팀과 프론트 팀 간 데이터 규칙을 맞추지 않아서 중복 삽입이 발생한 적이 있었어요. 그 이후로는 항상 "이 컬럼은 유니크 제약이 있으니, 이런 식으로 처리해주세요"라고 명확히 문서화하고 공유했습니다.
📌 결론
PostgreSQL의 오류 코드 23505, 중복 키 에러는 개발자가 실무에서 자주 마주치는 문제 중 하나입니다. 하지만 너무 겁먹을 필요는 없습니다. 원인을 정확히 이해하고, 데이터 흐름을 점검하고, 올바른 해결 전략을 선택하면 충분히 빠르고 깔끔하게 대처할 수 있어요.
무엇보다 중요한 것은, 단순히 오류를 '피하기'보다는, 오류를 통해 '배우고 성장하는' 자세를 가지는 것입니다. 한 번 경험하고 나면, 같은 문제를 훨씬 능숙하게 다룰 수 있게 되거든요. 저도 수없이 많은 23505 에러를 겪으며, 어느새 데이터베이스 다루는 감각이 자연스럽게 생겼답니다.
마지막으로, 작은 실수나 오류에도 좌절하지 마세요. 에러는 당신이 개발자로서 한 단계 성장하고 있다는 증거입니다. 오늘 이 글을 통해 중복 키 에러를 조금 더 친숙하게 느끼셨기를 바랍니다. 🙌