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

39P03 event trigger protocol violated 는?

PostgreSQL 에러 코드 39P03은 이벤트 트리거(Event Trigger) 함수가 PostgreSQL 내부 프로토콜을 위반했을 때 발생하는 오류입니다. 이벤트 트리거는 DDL 명령(CREATE, ALTER, DROP 등)에 반응하여 실행되는 특수한 트리거로, 일반 트리거와는 달리 반환 타입이 event_trigger여야 하며 특정 규칙을 엄격히 따라야 합니다. 이 에러는 주로 이벤트 트리거 함수가 잘못된 반환 타입을 사용하거나, 허용되지 않는 방식으로 트리거 컨텍스트를 조작하려 할 때 발생합니다.

주요 발생 원인

• 이벤트 트리거 함수의 잘못된 반환 타입 사용

이벤트 트리거 함수는 반드시 RETURNS event_trigger로 선언되어야 합니다. 일반 트리거처럼 RETURNS trigger로 선언하거나, RETURNS void, RETURNS text 등 다른 반환 타입을 지정하면 PostgreSQL 내부 프로토콜을 위반하게 됩니다. 이 경우 트리거가 실행되는 시점에 PostgreSQL 엔진이 예상한 반환 프로토콜과 실제 함수의 반환 방식이 불일치하여 39P03 에러가 발생합니다.

• 이벤트 트리거 전용 함수를 일반 트리거로 등록하거나, 반대 상황 발생

이벤트 트리거 함수(event_trigger 반환)를 CREATE TRIGGER로 일반 테이블 트리거에 등록하거나, 반대로 일반 트리거 함수(trigger 반환)를 CREATE EVENT TRIGGER로 이벤트 트리거에 연결하는 실수가 빈번히 발생합니다. PostgreSQL은 트리거 종류에 따라 내부 호출 프로토콜이 완전히 다르기 때문에, 잘못 연결된 경우 실행 시점에 프로토콜 위반 에러가 발생합니다. 이는 기존 코드베이스에서 복사-붙여넣기를 통해 트리거 함수를 재사용할 때 특히 자주 나타납니다.

• PL/pgSQL 이외의 언어로 작성된 이벤트 트리거 함수의 프로토콜 불일치

C 언어 또는 PL/Python, PL/Perl 등 외부 언어로 이벤트 트리거 함수를 작성할 때, 해당 언어의 PostgreSQL 인터페이스가 이벤트 트리거 프로토콜을 제대로 구현하지 않으면 이 에러가 발생합니다. 특히 구버전 언어 확장이나 직접 작성한 C 언어 트리거 함수에서, EventTriggerData 구조체를 올바르게 처리하지 않거나 반환값을 잘못 설정하는 경우 프로토콜 위반이 발생합니다.

해결 방법

원인 1 해결: 반환 타입 수정

이벤트 트리거 함수는 반드시 RETURNS event_trigger로 선언해야 합니다. 기존 함수를 삭제하고 올바른 반환 타입으로 재생성하세요.

-- 잘못된 예시 (RETURNS void 사용)
CREATE OR REPLACE FUNCTION audit_ddl_wrong()
RETURNS void
LANGUAGE plpgsql
AS $$
BEGIN
    RAISE NOTICE 'DDL 이벤트 발생: %', tg_event;
END;
$$;

-- 올바른 예시 (RETURNS event_trigger 사용)
CREATE OR REPLACE FUNCTION audit_ddl_correct()
RETURNS event_trigger
LANGUAGE plpgsql
AS $$
BEGIN
    RAISE NOTICE 'DDL 이벤트 발생: %, 태그: %', tg_event, tg_tag;
END;
$$;

-- 이벤트 트리거 등록
CREATE EVENT TRIGGER audit_ddl_trigger
ON ddl_command_start
EXECUTE FUNCTION audit_ddl_correct();

원인 2 해결: 트리거 종류에 맞는 등록 방식 사용

이벤트 트리거와 일반 트리거를 혼용하지 않도록 명확히 구분하여 생성해야 합니다.

-- 잘못된 예시: 이벤트 트리거 함수를 일반 트리거로 등록 시도 (에러 발생)
-- CREATE TRIGGER wrong_trigger
-- BEFORE INSERT ON my_table
-- EXECUTE FUNCTION audit_ddl_correct();  -- event_trigger 반환 함수는 사용 불가

-- 올바른 예시: 일반 트리거는 trigger 반환 함수 사용
CREATE OR REPLACE FUNCTION my_table_audit()
RETURNS trigger
LANGUAGE plpgsql
AS $$
BEGIN
    INSERT INTO audit_log(operation, changed_at)
    VALUES (TG_OP, now());
    RETURN NEW;
END;
$$;

CREATE TRIGGER my_table_audit_trigger
BEFORE INSERT OR UPDATE OR DELETE ON my_table
FOR EACH ROW EXECUTE FUNCTION my_table_audit();

-- 올바른 예시: DDL 감사는 이벤트 트리거로 별도 구성
CREATE OR REPLACE FUNCTION ddl_audit_log()
RETURNS event_trigger
LANGUAGE plpgsql
AS $$
DECLARE
    audit_rec RECORD;
BEGIN
    FOR audit_rec IN SELECT * FROM pg_event_trigger_ddl_commands()
    LOOP
        INSERT INTO ddl_audit_log(command_tag, object_type, schema_name, object_identity, changed_at)
        VALUES (
            audit_rec.command_tag,
            audit_rec.object_type,
            audit_rec.schema_name,
            audit_rec.object_identity,
            now()
        );
    END LOOP;
END;
$$;

CREATE EVENT TRIGGER ddl_audit_event_trigger
ON ddl_command_end
EXECUTE FUNCTION ddl_audit_log();

원인 3 해결: 외부 언어 트리거 함수 점검 및 수정

C 언어로 작성된 이벤트 트리거라면 EventTriggerData 구조체 처리와 반환 프로토콜을 반드시 확인하세요. PL/pgSQL로 재작성하는 것이 가장 안전합니다.

-- 현재 등록된 이벤트 트리거 목록과 함수 정보 확인
SELECT
    et.evtname AS trigger_name,
    et.evtevent AS event,
    et.evtenabled AS enabled,
    p.proname AS function_name,
    l.lanname AS language,
    p.prorettype::regtype AS return_type
FROM pg_event_trigger et
JOIN pg_proc p ON p.oid = et.evtfoid
JOIN pg_language l ON l.oid = p.prolang
ORDER BY et.evtname;

-- 반환 타입이 event_trigger(26479)인지 확인
SELECT proname, prorettype, prorettype::regtype
FROM pg_proc
WHERE proname = 'your_event_trigger_function';

-- 문제가 있는 이벤트 트리거 비활성화 후 수정
ALTER EVENT TRIGGER problematic_trigger DISABLE;

-- 함수 재작성 후 다시 활성화
ALTER EVENT TRIGGER problematic_trigger ENABLE;

예방 방법

• 이벤트 트리거 함수 배포 전 반환 타입 자동 검증 스크립트 운영

이벤트 트리거 함수를 운영 환경에 배포하기 전, 반드시 반환 타입과 등록 방식을 자동으로 검증하는 스크립트를 CI/CD 파이프라인에 포함시키세요. pg_proc 시스템 카탈로그를 조회하여 모든 이벤트 트리거 함수가 event_trigger 타입을 반환하는지 확인하는 검증 쿼리를 배포 전 단계에서 실행하면, 운영 환경에서 발생할 수 있는 프로토콜 위반 오류를 사전에 차단할 수 있습니다.

“`sql

— 배포 전 검증 쿼리: event_trigger 반환 타입이 아닌 함수가 이벤트 트리거로 등록된 경우 탐지

SELECT

et.evtname,

p.proname,

p.prorettype::regtype AS return_type

FROM pg_event_trigger et

JOIN pg_proc p ON p.oid = et.evtfoid

WHERE p.prorettype != ‘event_trigger’::regtype;

— 결과가 있으면 배포 중단

“`

• 이벤트 트리거 함수 템플릿 표준화 및 코드 리뷰 체계 구축

팀 내에서 이벤트 트리거 함수를 작성할 때 사용할 표준 템플릿을 미리 정의하고, 트리거 관련 코드는 반드시 시니어 DBA의 코드 리뷰를 거치도록 프로세스를 수립하세요. 일반 트리거와 이벤트 트리거는 목적과 사용 방법이 완전히 다르므로, 팀 내 개발자들이 혼용하지 않도록 명확한 가이드라인 문서를 작성하고 정기적으로 공유하는 것이 중요합니다.

관련 에러

• 39P01 (trigger_protocol_violated): 일반 트리거 함수가 프로토콜을 위반했을 때 발생하는 에러로, 39P03과 유사한 맥락에서 발생합니다. 트리거 함수가 RETURNS trigger로 선언되지 않았거나 올바른 레코드를 반환하지 않을 때 발생합니다.
• 39P02 (srf_protocol_violated): Set-Returning Function(집합 반환 함수)이 프로토콜을 위반했을 때 발생합니다. 이벤트 트리거 내부에서 pg_event_trigger_ddl_commands() 같은 SRF 함수를 잘못 사용할 때 간접적으로 연관될 수 있습니다.
• 42P13 (invalid_function_definition): 함수 정의 자체가 잘못된 경우 발생하며, 이벤트 트리거 함수를 최초 생성할 때 반환 타입 오류로 함께 나타날 수 있습니다.

---

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