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

2D000
2026년 06월 27일 | DBMS Error 가이드

이 글에서 다루는 내용

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

2D000 invalid transaction termination 는?

PostgreSQL 에러 코드 2D000 invalid transaction termination은 트랜잭션을 종료하는 명령(COMMIT 또는 ROLLBACK)이 허용되지 않는 컨텍스트에서 실행될 때 발생합니다. 가장 대표적인 사례는 함수(Function) 또는 저장 프로시저(Stored Procedure) 내부에서 직접 COMMIT이나 ROLLBACK을 호출하려 할 때이며, 특히 일반 SQL 함수(LANGUAGE sql)나 PL/pgSQL 함수에서 잘못된 방식으로 트랜잭션을 제어하려 할 때 자주 발생합니다. 이 에러는 PostgreSQL의 트랜잭션 제어 규칙을 위반하는 것으로, 데이터 무결성을 보호하기 위한 엔진 수준의 안전장치입니다.

주요 발생 원인

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

PostgreSQL 11 이전 버전에서는 일반 함수(CREATE FUNCTION) 내부에서 COMMIT이나 ROLLBACK을 직접 사용할 수 없었습니다. 이 제약을 무시하고 함수 안에서 트랜잭션을 종료하려 하면 2D000 에러가 즉시 발생합니다. PostgreSQL 11 이후부터는 CREATE PROCEDURE를 사용하는 경우에 한해 COMMIT/ROLLBACK이 허용되지만, 일반 함수에서는 여전히 금지되어 있습니다.

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

트리거는 이미 진행 중인 트랜잭션의 일부로 실행되기 때문에, 트리거 함수 내에서 COMMIT이나 ROLLBACK을 호출하는 것은 구조적으로 허용되지 않습니다. 트리거 내에서 트랜잭션을 분리하거나 종료하려 할 경우 반드시 2D000 에러가 발생하며, 이는 PostgreSQL의 트리거 실행 모델과 근본적으로 충돌합니다.

3. 중첩된 서브트랜잭션 또는 잘못된 SAVEPOINT 사용

SAVEPOINT를 사용할 때 올바른 순서를 지키지 않거나, RELEASE SAVEPOINT 이후에 해당 세이브포인트로 ROLLBACK TO SAVEPOINT를 시도하는 경우에도 트랜잭션 종료 관련 에러가 발생할 수 있습니다. 특히 복잡한 중첩 트랜잭션 로직에서 COMMIT과 SAVEPOINT가 혼용될 때 컨텍스트 충돌이 일어나 2D000 에러로 이어질 수 있습니다.

해결 방법

원인 1 해결: 함수 대신 프로시저(PROCEDURE) 사용

PostgreSQL 11 이상에서는 트랜잭션 제어가 필요한 경우 CREATE FUNCTION 대신 CREATE PROCEDURE를 사용해야 합니다.

잘못된 예시 (에러 발생):

-- 이 코드는 2D000 에러를 발생시킵니다.
CREATE OR REPLACE FUNCTION process_orders()
RETURNS void AS $$
BEGIN
    UPDATE orders SET status = 'processed' WHERE status = 'pending';
    COMMIT;  -- ❌ 함수 내부에서 COMMIT 불가
END;
$$ LANGUAGE plpgsql;

SELECT process_orders();

올바른 예시 (PROCEDURE 사용):

-- PROCEDURE를 사용하면 COMMIT/ROLLBACK이 가능합니다.
CREATE OR REPLACE PROCEDURE process_orders()
LANGUAGE plpgsql
AS $$
BEGIN
    UPDATE orders SET status = 'processed' WHERE status = 'pending';
    COMMIT;  -- ✅ PROCEDURE 내부에서는 허용됨

    INSERT INTO order_logs(message, created_at)
    VALUES ('Orders processed successfully', NOW());
    COMMIT;  -- ✅ 두 번째 COMMIT도 가능
EXCEPTION
    WHEN OTHERS THEN
        ROLLBACK;  -- ✅ 에러 발생 시 롤백
        RAISE;
END;
$$;

-- 호출 방법
CALL process_orders();

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

트리거 함수에서는 절대 COMMIT/ROLLBACK을 사용하지 말고, 대신 예외 처리를 통해 트랜잭션을 간접적으로 제어해야 합니다.

잘못된 예시 (에러 발생):

-- 트리거 함수 내 COMMIT은 2D000 에러를 발생시킵니다.
CREATE OR REPLACE FUNCTION trg_after_insert()
RETURNS trigger AS $$
BEGIN
    INSERT INTO audit_log(table_name, action, changed_at)
    VALUES (TG_TABLE_NAME, TG_OP, NOW());
    COMMIT;  -- ❌ 트리거 내부에서 COMMIT 불가
    RETURN NEW;
END;
$$ LANGUAGE plpgsql;

올바른 예시:

-- 트리거 함수에서는 COMMIT 없이 로직만 처리합니다.
CREATE OR REPLACE FUNCTION trg_after_insert()
RETURNS trigger AS $$
BEGIN
    INSERT INTO audit_log(table_name, action, changed_at)
    VALUES (TG_TABLE_NAME, TG_OP, NOW());
    -- ✅ COMMIT 없이 반환 - 트랜잭션은 호출 측에서 관리됩니다.
    RETURN NEW;
EXCEPTION
    WHEN OTHERS THEN
        -- 에러 로깅 후 예외를 다시 발생시킵니다.
        RAISE WARNING 'Audit log insert failed: %', SQLERRM;
        RETURN NEW;  -- 또는 RETURN NULL (트리거 동작에 따라 선택)
END;
$$ LANGUAGE plpgsql;

CREATE TRIGGER after_insert_trigger
AFTER INSERT ON orders
FOR EACH ROW EXECUTE FUNCTION trg_after_insert();

원인 3 해결: SAVEPOINT 올바른 사용

-- SAVEPOINT를 활용한 올바른 중첩 트랜잭션 처리
BEGIN;

    INSERT INTO accounts(name, balance) VALUES ('Alice', 1000);

    SAVEPOINT sp1;  -- 세이브포인트 설정

    INSERT INTO accounts(name, balance) VALUES ('Bob', 2000);

    -- 특정 조건에서 sp1으로 롤백
    ROLLBACK TO SAVEPOINT sp1;  -- ✅ sp1 이후 작업만 취소

    -- sp1은 ROLLBACK TO 후에도 유효합니다.
    INSERT INTO accounts(name, balance) VALUES ('Charlie', 1500);

    RELEASE SAVEPOINT sp1;  -- ✅ 세이브포인트 해제

    -- RELEASE 이후에는 해당 SAVEPOINT로 ROLLBACK 불가
    -- ROLLBACK TO SAVEPOINT sp1;  -- ❌ 이미 해제된 SAVEPOINT

COMMIT;

예방 방법

1. 트랜잭션 제어가 필요한 로직은 PROCEDURE로 설계

프로젝트 초기 설계 단계부터 트랜잭션을 직접 제어해야 하는 비즈니스 로직은 반드시 CREATE PROCEDURE로 작성하는 규칙을 팀 내에 공유하고 코드 리뷰에서 확인하십시오. CREATE FUNCTION과 CREATE PROCEDURE의 차이를 명확히 구분하는 개발 가이드라인을 문서화하면 신규 개발자의 실수를 크게 줄일 수 있습니다.

2. CI/CD 파이프라인에 정적 분석 도구 도입

pgTAP, plpgsql_check 같은 정적 분석 도구를 CI/CD 파이프라인에 통합하여, 배포 전 함수나 트리거 내에서 COMMIT/ROLLBACK이 잘못 사용되고 있는지 자동으로 감지하도록 설정하십시오. 이를 통해 운영 환경에서 2D000 에러가 발생하기 전에 코드 단계에서 사전 차단할 수 있습니다.