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

39P03 event trigger protocol violated 는?

PostgreSQL 에러 코드 39P03 event trigger protocol violated는 이벤트 트리거(Event Trigger) 함수가 PostgreSQL 내부 프로토콜을 위반했을 때 발생하는 에러입니다. 이벤트 트리거는 DDL 명령(CREATE, ALTER, DROP 등)에 반응하는 특수한 트리거로, 반드시 정해진 반환 타입과 호출 규약을 따라야 합니다. 함수가 event_trigger 반환 타입을 올바르게 선언하지 않거나, 내부적으로 잘못된 방식으로 결과를 반환하려 할 때 이 에러가 발생하며, 특히 PL/pgSQL 외의 언어로 이벤트 트리거를 작성할 때 더 자주 마주치게 됩니다.

주요 발생 원인

• 이벤트 트리거 함수의 반환 타입 오선언

이벤트 트리거 함수는 반드시 RETURNS event_trigger로 선언되어야 합니다. 일반 트리거처럼 RETURNS trigger나 RETURNS void, 또는 다른 타입으로 선언하면 PostgreSQL 내부 프로토콜과 충돌하여 39P03 에러가 발생합니다. 이는 가장 흔한 원인으로, 기존 일반 트리거 함수를 이벤트 트리거로 전환할 때 자주 발생합니다.

• C 언어 또는 외부 언어 확장에서의 잘못된 프로토콜 구현

C 언어로 작성된 이벤트 트리거 함수는 PostgreSQL의 EventTriggerData 구조체를 올바르게 참조하고, PG_RETURN_VOID()를 통해 반환해야 합니다. 만약 함수가 일반 함수 호출 규약(fmgr convention)을 따르지 않거나, 잘못된 포인터를 반환하려 하면 이 에러가 발생합니다. 서드파티 확장 플러그인을 최신 PostgreSQL 버전으로 업그레이드할 때 구버전 API를 사용하는 경우에도 동일한 문제가 생깁니다.

• 이벤트 트리거 내부에서 결과셋을 반환하려는 시도

이벤트 트리거 함수는 어떠한 결과셋도 반환할 수 없습니다. PL/Python, PL/Perl 등의 언어로 이벤트 트리거를 작성할 때 return 문으로 값을 반환하거나, PERFORM 대신 SELECT를 사용하여 결과를 반환하려 할 경우 프로토콜 위반으로 간주됩니다. 이벤트 트리거의 목적은 DDL 작업에 반응하는 부수 효과(side effect)를 수행하는 것이지, 데이터를 반환하는 것이 아닙니다.

해결 방법

원인 1: 반환 타입 수정

기존에 잘못 선언된 함수를 삭제하고 올바른 반환 타입으로 재생성합니다.

-- 잘못된 예시 (RETURNS void로 선언된 경우)
CREATE OR REPLACE FUNCTION wrong_event_trigger_func()
RETURNS void
LANGUAGE plpgsql
AS $$
BEGIN
  RAISE NOTICE 'DDL 이벤트 발생';
END;
$$;

-- 위 함수로 이벤트 트리거를 생성하면 나중에 에러 발생
-- CREATE EVENT TRIGGER bad_trigger ON ddl_command_start
--   EXECUTE FUNCTION wrong_event_trigger_func();
-- 위 트리거가 실행될 때 39P03 에러 발생

-- 올바른 예시: RETURNS event_trigger 로 선언
CREATE OR REPLACE FUNCTION correct_event_trigger_func()
RETURNS event_trigger
LANGUAGE plpgsql
AS $$
DECLARE
  obj record;
BEGIN
  -- pg_event_trigger_ddl_commands()로 DDL 정보 조회
  FOR obj IN SELECT * FROM pg_event_trigger_ddl_commands()
  LOOP
    RAISE NOTICE 'DDL 커맨드: %, 오브젝트 타입: %', 
                  obj.command_tag, obj.object_type;
  END LOOP;
END;
$$;

-- 올바르게 이벤트 트리거 생성
CREATE EVENT TRIGGER audit_ddl_trigger
ON ddl_command_end
EXECUTE FUNCTION correct_event_trigger_func();

원인 2: C 언어 확장 함수 수정

C 언어로 작성된 이벤트 트리거 함수가 올바른 프로토콜을 따르는지 확인합니다.

-- C 확장 함수 등록 후 이벤트 트리거 연결 예시
-- (C 소스에서 EventTriggerData 올바르게 처리 후)
CREATE OR REPLACE FUNCTION c_event_trigger_handler()
RETURNS event_trigger
LANGUAGE C
AS '$libdir/my_extension', 'my_event_trigger_handler';

-- 이벤트 트리거 생성
CREATE EVENT TRIGGER c_ddl_monitor
ON ddl_command_start
EXECUTE FUNCTION c_event_trigger_handler();

-- 기존 문제가 있는 이벤트 트리거 비활성화 후 재생성
ALTER EVENT TRIGGER c_ddl_monitor DISABLE;
DROP EVENT TRIGGER IF EXISTS c_ddl_monitor;
DROP FUNCTION IF EXISTS c_event_trigger_handler();

원인 3: PL/Python 이벤트 트리거 올바른 작성법

-- 잘못된 PL/Python 이벤트 트리거 예시 (값을 반환하려 함)
CREATE OR REPLACE FUNCTION bad_plpython_trigger()
RETURNS event_trigger
LANGUAGE plpython3u
AS $$
  # 이벤트 트리거에서 값을 반환하면 안 됨
  return "some value"  -- 이 경우 프로토콜 위반 에러 발생
$$;

-- 올바른 PL/Python 이벤트 트리거 예시
CREATE OR REPLACE FUNCTION good_plpython_trigger()
RETURNS event_trigger
LANGUAGE plpython3u
AS $$
  import plpy
  # DDL 감사 로그를 테이블에 기록
  event = TD["event"]
  tag = TD["tag"]
  plpy.execute(
    "INSERT INTO ddl_audit_log(event_type, command_tag, created_at) "
    "VALUES (%s, %s, NOW())" % (
      plpy.quote_literal(event),
      plpy.quote_literal(tag)
    )
  )
  # 반드시 None을 반환하거나 return 문 없이 종료
$$;

-- DDL 감사 로그 테이블 생성
CREATE TABLE IF NOT EXISTS ddl_audit_log (
  id          SERIAL PRIMARY KEY,
  event_type  TEXT NOT NULL,
  command_tag TEXT NOT NULL,
  executed_by TEXT DEFAULT current_user,
  created_at  TIMESTAMPTZ DEFAULT NOW()
);

-- 이벤트 트리거 등록
CREATE EVENT TRIGGER python_ddl_audit
ON ddl_command_end
EXECUTE FUNCTION good_plpython_trigger();

현재 등록된 이벤트 트리거 목록 확인

-- 시스템에 등록된 이벤트 트리거 조회
SELECT 
  evtname        AS trigger_name,
  evtevent       AS event,
  evtenabled     AS enabled,
  evtfoid::regproc AS function_name,
  evttags        AS filter_tags
FROM pg_event_trigger
ORDER BY evtname;

-- 이벤트 트리거와 함수 정의 함께 조회
SELECT 
  et.evtname,
  et.evtevent,
  p.proname,
  p.prorettype::regtype AS return_type,
  pg_get_functiondef(p.oid) AS function_def
FROM pg_event_trigger et
JOIN pg_proc p ON p.oid = et.evtfoid
ORDER BY et.evtname;

예방 방법

• 이벤트 트리거 함수 작성 시 템플릿 사용 및 코드 리뷰 프로세스 도입

팀 내에서 이벤트 트리거 함수를 작성할 때 반드시 검증된 템플릿을 사용하고, 반환 타입이 event_trigger인지 코드 리뷰 체크리스트에 포함시킵니다. CI/CD 파이프라인에 DDL 스크립트 검증 단계를 추가하여 RETURNS event_trigger 선언 여부를 자동으로 검사하는 스크립트를 운영합니다. 개발 환경에서 충분한 테스트를 거친 후 프로덕션에 배포하는 절차를 반드시 준수해야 합니다.

“`sql

— 이벤트 트리거 함수 유효성 검사 쿼리 (배포 전 확인용)

SELECT

p.proname,

p.prorettype::regtype AS return_type,

CASE

WHEN p.prorettype = ‘event_trigger’::regtype THEN ‘✅ 정상’

ELSE ‘❌ 반환 타입 오류 – event_trigger 여야 함’

END AS validation_result

FROM pg_proc p

WHERE p.proname LIKE ‘%trigger%’

AND p.prorettype != ‘trigger’::regtype

ORDER BY p.proname;

“`

• 이벤트 트리거 비활성화 메커니즘 사전 구축

긴급 상황에서 잘못된 이벤트 트리거로 인해 모든 DDL이 차단될 수 있으므로, 슈퍼유저 권한으로 이벤트 트리거를 빠르게 비활성화할 수 있는 절차를 문서화해 둡니다. 특히 session_replication_role을 replica로 설정하면 이벤트 트리거가 실행되지 않으므로, 긴급 복구 시 활용할 수 있습니다.

“`sql

— 긴급 시 특정 이벤트 트리거 비활성화

ALTER EVENT TRIGGER audit_ddl_trigger DISABLE;

— 세션 레벨에서 이벤트 트리거 우회 (슈퍼유저만 가능)

SET session_replication_role = replica;

— 이 상태에서 DDL 작업 수행

— 작업 완료 후 원래 상태로 복원

SET session_replication_role = DEFAULT;

— 모든 이벤트 트리거 상태 모니터링

SELECT evtname, evtevent,

CASE evtenabled

WHEN ‘O’ THEN ‘ENABLED’

WHEN ‘D’ THEN ‘DISABLED’

WHEN ‘R’ THEN ‘REPLICA’

WHEN ‘A’ THEN ‘ALWAYS’

END AS status

FROM pg_event_trigger;

“`

관련 에러

• 39P01 (trigger protocol violated): 일반 트리거 함수가 프로토콜을 위반할 때 발생하는 에러로, 39P03과 유사한 맥락이지만 DML 트리거(INSERT, UPDATE, DELETE)에 해당합니다.
• 39P02 (SRF protocol violated): Set-Returning Function(집합 반환 함수)이 프로토콜을 위반할 때 발생하며, 함수가 결과셋 반환 방식을 올바르게 구현하지 않은 경우입니다.
• 42P13 (invalid_function_definition): 함수 정의 자체가 잘못되어 생성에 실패할 때 발생하며, 이벤트 트리거 함수 생성 단계에서 먼저 이 에러를 만날 수 있습니다.
• 0A000 (feature_not_supported): 특정 이벤트 타입이나 언어에서 이벤트 트리거를 지원하지 않을 때 발생할 수 있습니다.

---

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