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

2D000
2026년 08월 31일 | DBMS Error 가이드

이 글에서 다루는 내용

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

2D000 invalid transaction termination 는?

PostgreSQL 에러 코드 2D000 invalid transaction termination은 트랜잭션 종료 명령(COMMIT 또는 ROLLBACK)이 허용되지 않는 컨텍스트에서 호출될 때 발생하는 에러입니다. 대표적으로 PL/pgSQL 함수나 프로시저 내부에서 직접 트랜잭션을 종료하려 할 때, 또는 트리거 함수 안에서 COMMIT/ROLLBACK을 사용할 때 이 에러가 발생합니다. 이 에러는 PostgreSQL이 트랜잭션의 경계를 엄격하게 관리하기 때문에 발생하며, 트랜잭션 상태가 현재 실행 컨텍스트와 맞지 않을 때 데이터 무결성을 보호하기 위해 즉시 예외를 발생시킵니다.

주요 발생 원인

1. PL/pgSQL 함수(Function) 내부에서 COMMIT/ROLLBACK 직접 호출

PostgreSQL에서 일반 FUNCTION(함수)은 호출자의 트랜잭션 컨텍스트 안에서 실행됩니다. 따라서 함수 내부에서 COMMIT 또는 ROLLBACK을 직접 사용하면 호출자의 트랜잭션 경계를 침범하게 되어 2D000 에러가 발생합니다. PostgreSQL 11 이후부터 PROCEDURE(프로시저)는 CALL 문으로 호출할 때 자체 트랜잭션 제어가 가능하지만, FUNCTION에서는 여전히 허용되지 않습니다.

2. 트리거 함수(Trigger Function) 내에서 트랜잭션 종료 시도

트리거는 테이블에 DML 이벤트(INSERT, UPDATE, DELETE)가 발생할 때 자동으로 실행되는 특수 함수입니다. 트리거는 이미 진행 중인 트랜잭션의 일부로 실행되기 때문에, 트리거 함수 내에서 COMMIT이나 ROLLBACK을 호출하면 PostgreSQL은 이를 잘못된 트랜잭션 종료로 간주하여 2D000 에러를 즉시 발생시킵니다. 트리거 내에서 오류 처리가 필요하다면 예외(EXCEPTION) 블록을 활용해야 합니다.

3. 중첩된 함수 호출 또는 잘못된 Savepoint 관리

복잡한 비즈니스 로직에서 여러 함수가 중첩 호출될 때, 내부 함수에서 트랜잭션을 종료하려는 시도가 외부 트랜잭션 상태와 충돌하여 이 에러가 발생할 수 있습니다. 또한 SAVEPOINT를 사용하는 상황에서 이미 릴리즈(RELEASE)된 세이브포인트로 ROLLBACK TO SAVEPOINT를 시도하거나, 서브트랜잭션 처리 중 예상치 못한 트랜잭션 상태 변경이 발생하면 에러로 이어질 수 있습니다. 이런 경우는 코드 구조를 재설계하고 트랜잭션 경계를 명확히 정의해야 합니다.

해결 방법

원인 1 해결: FUNCTION을 PROCEDURE로 변경

트랜잭션 제어가 필요한 경우, FUNCTION 대신 PROCEDURE를 사용하고 CALL 명령으로 호출하세요.

-- ❌ 잘못된 예시: FUNCTION 내에서 COMMIT 사용 (2D000 에러 발생)
CREATE OR REPLACE FUNCTION bad_transaction_func()
RETURNS void AS $$
BEGIN
    INSERT INTO orders(product_id, quantity) VALUES (101, 5);
    COMMIT; -- 여기서 2D000 에러 발생!
END;
$$ LANGUAGE plpgsql;

-- ✅ 올바른 예시: PROCEDURE로 변환하여 트랜잭션 제어
CREATE OR REPLACE PROCEDURE good_transaction_proc()
LANGUAGE plpgsql
AS $$
BEGIN
    INSERT INTO orders(product_id, quantity) VALUES (101, 5);
    COMMIT; -- PROCEDURE에서는 허용됨

    INSERT INTO order_logs(action, created_at) VALUES ('ORDER_CREATED', NOW());
    COMMIT;
EXCEPTION
    WHEN OTHERS THEN
        ROLLBACK;
        RAISE NOTICE '에러 발생: %', SQLERRM;
END;
$$;

-- PROCEDURE 호출 방법
CALL good_transaction_proc();

원인 2 해결: 트리거 함수에서 트랜잭션 제어 제거

트리거 함수에서는 COMMIT/ROLLBACK 대신 EXCEPTION 블록을 사용하여 오류를 처리하세요.

-- ❌ 잘못된 예시: 트리거 함수 내 COMMIT 사용
CREATE OR REPLACE FUNCTION bad_trigger_func()
RETURNS trigger AS $$
BEGIN
    INSERT INTO audit_log(table_name, action) VALUES (TG_TABLE_NAME, TG_OP);
    COMMIT; -- 2D000 에러 발생!
    RETURN NEW;
END;
$$ LANGUAGE plpgsql;

-- ✅ 올바른 예시: EXCEPTION 블록으로 오류 처리
CREATE OR REPLACE FUNCTION good_trigger_func()
RETURNS trigger AS $$
BEGIN
    INSERT INTO audit_log(table_name, action, changed_at)
    VALUES (TG_TABLE_NAME, TG_OP, NOW());

    RETURN NEW;
EXCEPTION
    WHEN OTHERS THEN
        -- 트리거 실패 시 로그 테이블에 기록 (별도 처리)
        RAISE WARNING '감사 로그 기록 실패: % - %', SQLSTATE, SQLERRM;
        RETURN NEW; -- 원본 트랜잭션은 계속 진행
END;
$$ LANGUAGE plpgsql;

-- 트리거 등록
CREATE TRIGGER audit_trigger
AFTER INSERT OR UPDATE OR DELETE ON orders
FOR EACH ROW EXECUTE FUNCTION good_trigger_func();

원인 3 해결: SAVEPOINT를 활용한 중첩 트랜잭션 처리

중첩된 트랜잭션 로직이 필요한 경우 SAVEPOINT를 적절히 활용하세요.

-- ✅ SAVEPOINT를 활용한 안전한 트랜잭션 처리
BEGIN;

SAVEPOINT sp1;
INSERT INTO accounts(user_id, balance) VALUES (1001, 5000);

SAVEPOINT sp2;
INSERT INTO transactions(account_id, amount, type) VALUES (1001, 5000, 'DEPOSIT');

-- sp2 지점까지만 롤백하고 sp1 작업은 유지
ROLLBACK TO SAVEPOINT sp2;
RELEASE SAVEPOINT sp2;

-- sp1의 작업만 커밋
COMMIT;

-- PL/pgSQL 내에서 SAVEPOINT 활용 예시
DO $$
DECLARE
    v_error_count INT := 0;
BEGIN
    FOR i IN 1..5 LOOP
        BEGIN
            SAVEPOINT loop_savepoint;
            INSERT INTO batch_jobs(job_id, status) VALUES (i, 'RUNNING');
            -- 특정 조건에서 이 반복만 롤백
            IF i = 3 THEN
                ROLLBACK TO SAVEPOINT loop_savepoint;
                v_error_count := v_error_count + 1;
            ELSE
                RELEASE SAVEPOINT loop_savepoint;
            END IF;
        EXCEPTION
            WHEN OTHERS THEN
                ROLLBACK TO SAVEPOINT loop_savepoint;
                RAISE NOTICE '배치 작업 % 실패: %', i, SQLERRM;
        END;
    END LOOP;

    RAISE NOTICE '처리 완료. 실패 건수: %', v_error_count;
END;
$$;

예방 방법

1. 함수/프로시저 설계 시 트랜잭션 경계를 명확히 정의하라

코드 작성 전에 트랜잭션이 어디서 시작되고 어디서 끝나야 하는지 명확히 설계해야 합니다. PostgreSQL에서 FUNCTION은 트랜잭션 내부에서 동작하고, PROCEDURE는 자체 트랜잭션 제어가 가능하다는 원칙을 팀 내에서 공유하고 코딩 컨벤션으로 문서화하세요. 트랜잭션 제어가 필요한 비즈니스 로직은 반드시 PROCEDURE로 구현하고, 단순 데이터 조회나 변환 로직은 FUNCTION으로 구분하여 역할을 명확히 합니다.

2. 개발 환경에서 철저한 트랜잭션 테스트 수행

운영 배포 전에 다양한 트랜잭션 시나리오(정상 커밋, 강제 롤백, 중첩 호출, 트리거 동시 발생 등)를 커버하는 통합 테스트를 작성하세요. pgTAP 같은 PostgreSQL 테스트 프레임워크를 활용하거나, 적어도 psql에서 수동으로 트랜잭션 경계 테스트를 실시하는 습관을 들이세요. 특히 트리거가 연쇄적으로 실행되는 복잡한 스키마에서는 트랜잭션 흐름을 다이어그램으로 그려 팀 전체가 이해할 수 있도록 공유하는 것이 장기적으로 유지보수 비용을 크게 줄여줍니다.