PostgreSQL 2200H 오류 원인과 해결 방법 완벽 가이드

2200H
2026년 08월 16일 | DBMS Error 가이드

이 글에서 다루는 내용

2200H 에러의 원인 분석, 해결 SQL, 예방 방법을 실무 관점에서 정리합니다.

2200H sequence generator limit exceeded 는?

PostgreSQL 에러 코드 2200H(sequence_generator_limit_exceeded)는 시퀀스(Sequence) 객체가 허용된 최솟값 또는 최댓값의 한계에 도달했을 때 발생하는 오류입니다. 시퀀스는 기본키(Primary Key) 자동 증가, 고유 식별자 생성 등 다양한 목적으로 사용되는데, 정해진 범위를 초과하거나 그 이하로 내려가면 더 이상 새로운 값을 생성할 수 없게 됩니다. 특히 SERIAL, BIGSERIAL, SMALLSERIAL 타입이나 GENERATED AS IDENTITY 컬럼에서 빈번히 발생하며, 대용량 트랜잭션 환경에서 예상보다 빠르게 시퀀스가 소진되는 경우 운영 장애로 이어질 수 있습니다.

주요 발생 원인

1. SERIAL 또는 INTEGER 기반 시퀀스 최댓값 초과

가장 흔한 원인으로, SERIAL 타입은 내부적으로 integer 범위(최대 약 21억, 2,147,483,647)를 사용하는 시퀀스를 생성합니다. 대량의 INSERT 작업이 반복되거나, 삭제 후 재삽입을 반복하는 패턴에서는 실제 레코드 수가 적더라도 시퀀스 값이 최댓값에 빠르게 도달할 수 있습니다. 특히 롤백된 트랜잭션에서도 시퀀스 값은 소비되기 때문에 예상보다 훨씬 빠르게 소진됩니다.

2. CYCLE 옵션 미설정 상태에서 범위 초과

시퀀스 생성 시 CYCLE 옵션을 지정하지 않으면(기본값은 NO CYCLE) 최댓값에 도달한 순간 더 이상 값을 생성하지 못하고 에러가 발생합니다. 반대로 MINVALUE보다 작아지는 경우에도 마찬가지입니다. 이 상황은 새벽 배치 작업이나 대규모 데이터 마이그레이션 도중 갑작스럽게 발생하여 서비스 전체를 중단시키는 심각한 장애로 이어질 수 있습니다.

3. SMALLSERIAL 또는 SMALLINT 기반 시퀀스 사용

SMALLSERIAL 타입은 최대 32,767까지만 값을 생성할 수 있어 상대적으로 훨씬 빠르게 한계에 도달합니다. 초기 설계 단계에서 데이터 증가량을 과소평가하거나, 로그성 테이블 또는 이벤트 큐 테이블에 SMALLSERIAL을 무심코 사용했다가 운영 중 에러가 터지는 사례가 많습니다. 이 경우 컬럼 타입 변경이 필요하며, 운영 중인 테이블에 적용하려면 사전 준비가 필요합니다.

해결 방법

원인 1 해결: 시퀀스 최댓값 재설정 또는 타입 변경

현재 시퀀스의 상태를 먼저 확인합니다.

-- 현재 시퀀스 상태 확인
SELECT
    schemaname,
    sequencename,
    last_value,
    max_value,
    is_cycled
FROM pg_sequences
WHERE sequencename = 'your_table_id_seq';

시퀀스가 거의 소진된 경우, 시퀀스를 리셋하거나 최댓값을 늘릴 수 있습니다.

-- 시퀀스 최댓값을 BIGINT 범위로 확장
ALTER SEQUENCE your_table_id_seq MAXVALUE 9223372036854775807;

-- 혹은 시퀀스를 특정 값으로 재시작 (주의: 기존 데이터와 충돌 가능)
SELECT MAX(id) FROM your_table;
-- 위 결과 값보다 크게 설정
ALTER SEQUENCE your_table_id_seq RESTART WITH 1000000;

컬럼 타입 자체를 INTEGER에서 BIGINT로 변경하는 근본적인 해결책도 필요합니다.

-- 컬럼 타입을 BIGINT로 변경 (운영 중 주의 필요)
ALTER TABLE your_table ALTER COLUMN id TYPE BIGINT;

-- SERIAL 대신 BIGSERIAL로 변경 (신규 테이블 권장)
CREATE TABLE new_table (
    id BIGSERIAL PRIMARY KEY,
    name TEXT NOT NULL,
    created_at TIMESTAMPTZ DEFAULT NOW()
);

원인 2 해결: CYCLE 옵션 설정 (임시방편)

-- 즉각적인 장애 대응용 CYCLE 설정 (영구 해결책 아님, 키 중복 위험 있음)
ALTER SEQUENCE your_table_id_seq CYCLE;

-- 운영 안정화 후 CYCLE 해제 및 타입 변경 진행
ALTER SEQUENCE your_table_id_seq NO CYCLE;

> ⚠️ 주의: CYCLE 옵션은 임시 조치입니다. 기본키 컬럼에 CYCLE을 적용하면 값이 반복되어 유니크 제약 위반이 발생할 수 있으므로 반드시 근본적인 해결책을 병행해야 합니다.

원인 3 해결: SMALLSERIAL을 BIGSERIAL로 마이그레이션

-- 1단계: 새 시퀀스 생성
CREATE SEQUENCE new_table_id_seq AS BIGINT
    START WITH 1
    INCREMENT BY 1
    NO CYCLE;

-- 2단계: 현재 최댓값으로 시퀀스 동기화
SELECT setval('new_table_id_seq', (SELECT MAX(id) FROM your_table));

-- 3단계: 컬럼 타입 변경 및 기본값 재설정
ALTER TABLE your_table ALTER COLUMN id TYPE BIGINT;
ALTER TABLE your_table ALTER COLUMN id SET DEFAULT nextval('new_table_id_seq');

-- 4단계: 기존 시퀀스 소유권 이전
ALTER SEQUENCE new_table_id_seq OWNED BY your_table.id;

시퀀스 소진 모니터링 쿼리

-- 시퀀스 소진율 모니터링 (80% 이상이면 경고)
SELECT
    schemaname || '.' || sequencename AS sequence_name,
    last_value,
    max_value,
    ROUND((last_value::NUMERIC / max_value::NUMERIC) * 100, 2) AS usage_pct,
    CASE
        WHEN (last_value::NUMERIC / max_value::NUMERIC) >= 0.9 THEN '🔴 위험'
        WHEN (last_value::NUMERIC / max_value::NUMERIC) >= 0.8 THEN '🟡 경고'
        ELSE '🟢 정상'
    END AS status
FROM pg_sequences
WHERE NOT is_cycled
ORDER BY usage_pct DESC;

예방 방법

1. 신규 테이블 설계 시 BIGSERIAL 또는 GENERATED AS IDENTITY(BIGINT) 기본 적용

모든 신규 테이블의 기본키는 반드시 BIGSERIAL 또는 BIGINT GENERATED ALWAYS AS IDENTITY를 사용하도록 개발 표준으로 지정합니다. BIGINT의 최댓값은 약 922경(9,223,372,036,854,775,807)으로 실질적으로 소진을 걱정하지 않아도 됩니다. 코드 리뷰 단계에서 SERIAL이나 SMALLSERIAL 사용을 차단하는 정책을 수립하고, CI/CD 파이프라인에 DDL 검사 스크립트를 추가하면 실수를 원천 차단할 수 있습니다.

2. 주기적인 시퀀스 모니터링 및 알림 시스템 구축

위에서 제시한 모니터링 쿼리를 Prometheus, Grafana, Datadog 등 모니터링 도구와 연동하거나, 크론잡(cron job)으로 주기적으로 실행하여 사용률이 80%를 초과하면 Slack, PagerDuty 등으로 즉시 알림이 오도록 설정합니다. 장애는 대부분 예측 가능한 시점에 발생하므로, 사용률 90% 이전에 미리 대응하면 서비스 중단 없이 조용히 해결할 수 있습니다.