SQLite 부분 UNIQUE 인덱스로 대기 작업 중복 등록 막기
대기 작업만 SQLite 부분 UNIQUE 인덱스로 제한하고, UPSERT와 RETURNING으로 중복 여부를 판별한다. 완료 이력은 여러 건 보존한다.
SQLite 작업 큐에 같은 작업이 중복으로 들어오면 WHERE done_at IS NULL이 붙은 부분 UNIQUE 인덱스로 대기 작업의 중복을 막을 수 있다. 테넌트와 작업 키가 같은 대기 행은 하나만 허용하고, 완료된 행은 여러 건 보존한다. Python 예제로 삽입 여부를 확인하고 이 방식이 보장하는 범위를 살펴본다.
전체 데이터 행 중 일부가 주황색 테두리 안에서 청록색으로 강조된 모습
완료 이력까지 포함하면 생기는 문제
UNIQUE(tenant_id, job_key)는 작업이 완료된 뒤에도 같은 키의 새 행을 막는다. 반대로 완료 시각을 추가한 UNIQUE(tenant_id, job_key, done_at)는 대기 상태의 중복을 막지 못한다. SQLite는 UNIQUE 제약에서 NULL을 다른 NULL과 구별하기 때문이다. 이 모델에서는 완료 시각이 NULL인 행만 인덱스에 포함하고, 두 키 열은 NOT NULL로 선언한다. SQLite UNIQUE 제약 · 부분 UNIQUE 인덱스
중복 확인을 삽입문에 맡기기
기존 대기 작업을 먼저 조회하고 따로 삽입하면, 그 사이 다른 요청이 같은 키를 삽입할 수 있다. 인덱스가 데이터베이스에서 규칙을 강제하도록 하고, 삽입문의 ON CONFLICT 대상에 같은 열과 조건을 지정한다. 아래 코드에서 RETURNING id는 새 행이 생겼을 때만 ID를 반환한다. 중복일 때는 반환 행이 없으므로, 기존 작업의 ID가 필요한 API라면 별도의 조회 절차를 설계한다. SQLite UPSERT · RETURNING
sqlite_pending_jobs.py로 저장하고 python3 sqlite_pending_jobs.py를 실행한다. 이 예제의 RETURNING에는 SQLite 3.35.0 이상이 필요하다.
테넌트 경계와 완료 후 재등록 확인하기
2026년 11월 17일 Python 3.12.14와 SQLite 3.53.1의 메모리 데이터베이스에서 실행했다. 같은 테넌트에서 중복 삽입은 무시됐고, 다른 테넌트에서는 같은 키를 삽입할 수 있었다. 기존 행을 두 번 완료 처리한 뒤 한 번 더 등록해, 같은 테넌트와 키에 완료 행 두 건과 대기 행 한 건이 남는 것을 확인했다.
기존 큐에 적용할 때 점검할 조건
이미 중복 대기 행이 있다면 인덱스 생성이 실패한다. 먼저 WHERE done_at IS NULL로 필터링하고 GROUP BY tenant_id, job_key HAVING COUNT(*) > 1로 중복을 찾은 뒤, 업무 규칙에 따라 남길 행을 결정한다. 실제 서비스가 실행 중인 작업도 같은 키로 중복 등록할 수 없게 해야 한다면, 인덱스 조건과 충돌 대상에 그 상태까지 포함한다. 부분 UNIQUE 인덱스 · SQLite UPSERT
이 예제는 단일 연결에서 등록 규칙을 확인했다. 여러 워커의 작업 획득, 완료의 내구성, 외부 처리의 중복 방지는 별도 설계가 필요하다. 특히 완료 후 같은 키를 허용하므로 영구 멱등성이 필요한 요청은 완료 이력과 별도의 멱등성 키 정책을 사용한다.
English version ·
Prevent Duplicate Pending Jobs with a SQLite Partial Unique Index