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

작성자:

09000
2026년 05월 31일 | DBMS Error 가이드

이 글에서 다루는 내용

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

09000 triggered action exception 는?

PostgreSQL 에러 코드 09000은 triggered action exception으로, 트리거(Trigger) 내부에서 발생한 예외 상황을 나타냅니다. 트리거 함수가 실행되는 도중 명시적으로 RAISE EXCEPTION을 호출하거나, 트리거 내부 로직에서 제약 조건 위반, 잘못된 데이터 접근, 런타임 오류 등이 발생했을 때 이 에러가 클라이언트에게 전달됩니다. 주로 비즈니스 규칙을 트리거로 구현한 환경에서 INSERT, UPDATE, DELETE 작업 중에 자주 마주치게 되며, 에러 메시지만으로는 근본 원인을 파악하기 어렵기 때문에 트리거 본문을 직접 확인해야 하는 경우가 많습니다.

주요 발생 원인

1. 트리거 함수 내 명시적 RAISE EXCEPTION 호출

트리거 함수 내에서 비즈니스 규칙을 검증하고, 조건 불만족 시 RAISE EXCEPTION을 명시적으로 호출하는 경우가 가장 흔한 원인입니다. 예를 들어 재고 수량이 음수가 되는 UPDATE를 막거나, 특정 상태값 전이가 허용되지 않을 때 의도적으로 트랜잭션을 롤백시키기 위해 사용합니다. 이 경우 에러 메시지에 개발자가 작성한 설명이 포함되므로, 메시지를 주의 깊게 읽으면 원인 파악이 비교적 쉽습니다.

2. 트리거 내부의 런타임 오류 (NULL 참조, 타입 불일치, 부재 컬럼 접근)

트리거 함수 내에서 NEW 또는 OLD 레코드의 특정 컬럼을 참조할 때, 해당 컬럼이 NULL이거나 예상치 못한 타입으로 캐스팅에 실패하는 경우 런타임 예외가 발생합니다. 또한 테이블 스키마 변경(컬럼 추가/삭제/타입 변경) 이후 트리거 함수를 업데이트하지 않아 존재하지 않는 컬럼을 참조할 때도 이 에러가 발생합니다. 이런 유형의 오류는 개발 환경에서는 잘 드러나지 않다가, 프로덕션 데이터에서 예외 케이스가 들어올 때 갑자기 터지는 경향이 있어 더욱 위험합니다.

3. 트리거 체인(Trigger Chain)에서 발생하는 연쇄 예외

하나의 테이블에 여러 트리거가 등록되어 있거나, 트리거 내부에서 다른 테이블에 DML을 수행하고 그 테이블에도 트리거가 있는 경우 연쇄적으로 예외가 전파됩니다. 트리거 A가 트리거 B를 유발하고, B에서 발생한 예외가 A로 전파되어 최종적으로 09000 에러로 클라이언트에게 노출되는 구조입니다. 이 경우 에러의 진짜 발생 지점을 추적하려면 PostgreSQL 로그의 CONTEXT 정보를 반드시 확인해야 합니다.

해결 방법

원인 1 해결: 트리거 함수의 명시적 예외 처리 확인 및 수정

먼저 해당 테이블에 등록된 트리거 목록과 트리거 함수 본문을 조회합니다.

-- 특정 테이블에 등록된 트리거 목록 조회
SELECT
    tgname AS trigger_name,
    tgtype,
    proname AS function_name,
    tgenabled
FROM pg_trigger t
JOIN pg_proc p ON t.tgfoid = p.oid
JOIN pg_class c ON t.tgrelid = c.oid
WHERE c.relname = 'your_table_name'
  AND NOT tgisinternal;

-- 트리거 함수 본문 확인
SELECT prosrc
FROM pg_proc
WHERE proname = 'your_trigger_function_name';

트리거 함수 내에서 비즈니스 규칙을 검증하는 예시와 명확한 에러 메시지를 포함하는 올바른 패턴은 다음과 같습니다.

-- 예: 재고 수량 음수 방지 트리거 함수
CREATE OR REPLACE FUNCTION check_stock_quantity()
RETURNS TRIGGER AS $$
BEGIN
    IF NEW.quantity < 0 THEN
        -- 명확한 에러 메시지와 함께 HINT, DETAIL 제공
        RAISE EXCEPTION
            'Stock quantity cannot be negative. Table: %, Row ID: %, Attempted value: %',
            TG_TABLE_NAME, NEW.id, NEW.quantity
            USING ERRCODE = 'P0001',  -- raise_exception
                  HINT = 'Ensure the quantity is zero or positive before updating.';
    END IF;
    RETURN NEW;
END;
$$ LANGUAGE plpgsql;

-- 트리거 등록
DROP TRIGGER IF EXISTS trg_check_stock ON inventory;
CREATE TRIGGER trg_check_stock
    BEFORE INSERT OR UPDATE ON inventory
    FOR EACH ROW
    EXECUTE FUNCTION check_stock_quantity();

원인 2 해결: 런타임 오류에 대한 방어적 코딩 적용

NULL 참조나 타입 오류를 방지하기 위해 트리거 함수 내에서 EXCEPTION 블록을 사용한 방어적 처리를 구현합니다.

CREATE OR REPLACE FUNCTION safe_audit_trigger()
RETURNS TRIGGER AS $$
DECLARE
    v_user_id INTEGER;
    v_action  TEXT;
BEGIN
    -- NULL 방어: COALESCE로 기본값 처리
    v_user_id := COALESCE(NEW.updated_by, -1);
    v_action  := TG_OP; -- INSERT, UPDATE, DELETE

    -- 안전한 타입 캐스팅 예시
    BEGIN
        INSERT INTO audit_log (table_name, action, user_id, changed_at, row_data)
        VALUES (
            TG_TABLE_NAME,
            v_action,
            v_user_id,
            NOW(),
            row_to_json(NEW)::jsonb
        );
    EXCEPTION
        WHEN others THEN
            -- 감사 로그 실패가 메인 트랜잭션을 막지 않도록 처리
            RAISE WARNING 'audit_log insert failed for table %: SQLSTATE=%, MESSAGE=%',
                TG_TABLE_NAME, SQLSTATE, SQLERRM;
    END;

    RETURN NEW;
END;
$$ LANGUAGE plpgsql;

스키마 변경 후 트리거 함수의 유효성을 확인하는 쿼리도 주기적으로 실행하면 좋습니다.

-- 트리거 함수의 컴파일 유효성 재확인 (함수 재생성으로 검증)
DO $$
DECLARE
    r RECORD;
BEGIN
    FOR r IN
        SELECT proname, prosrc
        FROM pg_proc p
        JOIN pg_trigger t ON t.tgfoid = p.oid
        WHERE p.prolang = (SELECT oid FROM pg_language WHERE lanname = 'plpgsql')
    LOOP
        RAISE NOTICE 'Trigger function checked: %', r.proname;
    END LOOP;
END;
$$;

원인 3 해결: 트리거 체인 디버깅 및 실행 순서 제어

트리거 체인 문제를 디버깅할 때는 PostgreSQL 로그 레벨을 높여 CONTEXT를 확인합니다.

-- 세션 레벨에서 디버그 메시지 활성화
SET client_min_messages = 'DEBUG1';

-- 트리거 내부에서 실행 경로 추적용 로그 추가
CREATE OR REPLACE FUNCTION debug_trigger_chain()
RETURNS TRIGGER AS $$
BEGIN
    RAISE NOTICE '[TRIGGER DEBUG] Table: %, Op: %, Depth: %',
        TG_TABLE_NAME, TG_OP, pg_trigger_depth();

    -- 재귀 트리거 방지: 트리거 깊이가 1 이상이면 조기 반환
    IF pg_trigger_depth() > 1 THEN
        RETURN NEW;
    END IF;

    -- 실제 비즈니스 로직 처리
    RETURN NEW;
END;
$$ LANGUAGE plpgsql;

특정 트리거만 일시적으로 비활성화하여 문제 트리거를 격리하는 방법도 유용합니다.

-- 특정 트리거 임시 비활성화 (슈퍼유저 또는 테이블 소유자 권한 필요)
ALTER TABLE your_table DISABLE TRIGGER trg_suspected_trigger;

-- 문제 재현 테스트
INSERT INTO your_table (col1, col2) VALUES ('test', 'data');

-- 트리거 재활성화
ALTER TABLE your_table ENABLE TRIGGER trg_suspected_trigger;

-- 모든 트리거 비활성화 (긴급 상황 시)
ALTER TABLE your_table DISABLE TRIGGER ALL;

예방 방법

1. 트리거 함수 내 충분한 예외 처리와 로깅 표준화

모든 트리거 함수는 작성 시 반드시 EXCEPTION 블록을 포함하고, 에러 발생 시 SQLSTATE, SQLERRM, TG_TABLE_NAME, TG_OP 등의 컨텍스트 정보를 포함하는 로그를 남기는 표준 템플릿을 조직 내에서 강제화해야 합니다. 또한 스키마 변경(마이그레이션) 작업 후에는 반드시 관련 트리거 함수 목록을 체크리스트로 관리하고, 영향받는 함수를 재검토 및 테스트하는 프로세스를 CI/CD 파이프라인에 포함시켜야 합니다.

2. 트리거 복잡도 최소화 및 단위 테스트 의무화

하나의 트리거 함수가 지나치게 많은 책임을 갖지 않도록 단일 책임 원칙(SRP)을 적용하고, 복잡한 비즈니스 로직은 트리거 대신 애플리케이션 레이어나 저장 프로시저로 이관하는 것을 고려해야 합니다. pgTAP과 같은 PostgreSQL 전용 단위 테스트 프레임워크를 활용하여 트리거 함수에 대한 자동화된 테스트 케이스를 작성하고, 경계값(NULL, 음수, 최대값 등)에 대한 테스트를 의무적으로 포함시켜야 합니다.

관련 에러

  • P0001 (raise_exception): 트리거 또는 PL/pgSQL 함수에서 RAISE EXCEPTION을 명시적으로 호출했을 때 발생하며, 09000과 함께 자주 쌍으로 나타납니다.
  • P0004 (assert_failure): ASSERT 구문이 트리거 내에서 실패할 때 발생하며, 개발/테스트 환경에서 트리거 로직 검증 중 마주칩니다.
  • 23000 (integrity_constraint_violation): 트리거 내부에서 외래 키, UNIQUE, NOT NULL 등의 제약 조건을 위반하는 DML이 실행될 때 발생하며, 트리거 체인 오류와 혼동될 수 있습니다.
  • 40001 (serialization_failure): 트리거가 실행되는 트랜잭션이 직렬화 격리 수준에서 충돌할 때 발생하며, 고부하 환경에서 트리거와 함께 나타나는 경우가 있습니다.
  • 54001 (statement_too_complex): 다수의 트리거가 중첩 실행되어 실행 스택이 복잡해질 때 간접적으로 연관될 수 있으며, 트리거 체인이 깊어질 때 주의해야 합니다.
DBMS 에러 코드 시리즈

주요 DBMS error code를 정리하는 시리즈입니다.
블로그 홈에서 다른 에러도 확인하세요.

본 포스트는 AI가 생성한 기술 가이드입니다. 운영 환경 적용 전 충분한 검토를 권장합니다.

댓글 남기기