[척척학사] 🚨 PostgreSQL: duplicate key value violates unique constraint 에러 해결하기

이 글은 Velog에서 이전한 글입니다. Velog 원문 보기

척척학사 프로젝트를 진행하던 중 다음과 같은 에러가 발생했습니다.

ERROR: duplicate key value violates unique constraint "student_courses_pkey"
Detail: Key (id)=(1646) already exists.

Transaction silently rolled back because it has been marked as rollback-only

---

🔍 원인 분석

제 프로젝트에서는 StudentCourse 엔티티가 다음과 같이 설정되어 있습니다.

@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;

즉, id는 DB에서 자동 증가(시퀀스) 방식으로 생성됩니다.
그런데도 id가 중복되면서 에러가 발생했습니다.

id는 자동 증가(시퀀스) 설정이기 때문에 중복 키가 생길 이유가 없다고 생각했습니다. 그러나, DB 데이터를 확인해보니 중복 key 값인 1646에 해당하는 StudentCourse 레코드가 존재하는 것을 확인했습니다.

---

❗ 시퀀스 불일치 문제

원인은 수동으로 CSV 데이터를 삽입한 것이었습니다.

PostgreSQL은 자동 증가를 위해 내부적으로 시퀀스를 관리합니다.
예를 들어 student_courses 테이블의 기본키 시퀀스는 student_courses_id_seq 입니다.

하지만 CSV나 SQL로 id 값을 직접 지정해서 insert하면, 시퀀스는 그 사실을 알지 못합니다.
결과적으로…

• 테이블에는 id = 1646까지 존재
• 시퀀스 값은 여전히 1645에 머무름
• 새로운 insert 시도 시 → id = 1646 재사용 → 중복 키 에러 발생

---

✅ 해결 방법

시퀀스 값을 테이블의 현재 최대 id 이후로 수동 갱신해야 합니다.

-- student_courses 테이블의 최대 id 기준으로 시퀀스 값 재설정
SELECT setval('student_courses_id_seq', (SELECT MAX(id) 
FROM student_courses) + 1);

이제 시퀀스가 정상적으로 이어서 번호를 발급합니다.

---

예방 방법

1. CSV 등으로 데이터를 넣을 때는 id를 생략 → DB 시퀀스가 알아서 관리  
2. 불가피하게 id를 지정해야 한다면, 삽입 후 반드시 setval()로 시퀀스를 조정  

---

정리

문제  : 자동 증가 컬럼에서 중복 ID 발생  
원인  : CSV 등 수동 삽입 시 시퀀스 값이 갱신되지 않음  
해결  : setval()로 시퀀스를 테이블 최대 id + 1 로 수동 설정  
예방  : 수동 삽입 후 시퀀스 재조정, 가능하면 id 생략 후 insert  

---

결론: PostgreSQL에서는 시퀀스와 실제 데이터가 어긋날 수 있다.
특히 수동 데이터 삽입을 했다면 반드시 setval()로 확인/보정하는 습관이 필요하다.