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

00000 successful completion 는?

PostgreSQL에서 에러 코드 00000은 사실 에러가 아니라 성공적인 완료(Successful Completion) 를 나타내는 상태 코드입니다. SQL 쿼리나 명령이 아무런 문제 없이 정상적으로 실행되었을 때 PostgreSQL 내부적으로 반환되는 코드로, SQLSTATE 표준에서 정의한 “성공” 상태를 의미합니다. 일반적인 운영 환경에서 이 코드가 직접적으로 에러처럼 보이는 경우는 드물지만, 애플리케이션 로그나 PL/pgSQL 예외 처리 로직, 또는 모니터링 도구에서 이 코드가 예상치 못하게 등장하여 혼란을 일으키는 경우가 종종 있습니다.

실무에서는 PL/pgSQL 함수 내부에서 예외 처리를 구성하거나, JDBC/ODBC 드라이버를 통해 쿼리 결과를 처리할 때 SQLSTATE 00000을 명시적으로 확인해야 하는 상황이 발생합니다. 이 코드를 올바르게 이해하고 처리하는 것은 안정적인 데이터베이스 애플리케이션을 구축하는 데 있어 매우 중요한 기초 지식입니다.

---

주요 발생 원인

• PL/pgSQL 예외 처리 블록에서의 SQLSTATE 확인

PL/pgSQL 함수나 프로시저 내에서 EXCEPTION 블록을 사용할 때, SQLSTATE 변수를 통해 상태 코드를 확인하는 경우가 있습니다. 이때 정상 흐름에서 00000이 반환되어 혼란을 야기할 수 있으며, 특히 중첩된 예외 처리 구조에서 예상치 못한 분기가 발생할 수 있습니다. 개발자들이 에러 코드로 오해하여 불필요한 디버깅에 시간을 낭비하는 경우가 실무에서 빈번하게 발생합니다.

• 애플리케이션 드라이버 및 ORM 레이어에서의 상태 코드 처리 오류

Java의 JDBC, Python의 psycopg2, 또는 Node.js의 pg 라이브러리 등 다양한 드라이버에서 쿼리 실행 후 반환되는 SQLSTATE를 파싱할 때 00000을 잘못 처리하는 경우가 있습니다. 일부 ORM 프레임워크는 이 성공 코드를 비정상적인 상태로 인식하거나, 예외 처리 로직에서 적절히 걸러내지 못해 불필요한 에러 로그를 생성하기도 합니다. 이러한 경우 애플리케이션 레벨에서 00000을 정상 상태로 명시적으로 처리해 주어야 합니다.

• 모니터링 도구 및 로그 분석 시스템의 오탐(False Positive)

Datadog, Prometheus, pgBadger 등의 모니터링 도구나 커스텀 로그 분석 스크립트에서 SQLSTATE 코드를 기반으로 알림을 설정할 때, 00000을 에러로 분류하는 잘못된 규칙이 설정되는 경우가 있습니다. 이는 실제로 문제가 없는 상황에서 불필요한 알림을 발생시키고, 운영팀의 피로도를 높이는 원인이 됩니다. 특히 PostgreSQL의 log_min_messages 설정이나 log_error_verbosity 옵션과 함께 오해가 발생하는 경우가 많습니다.

---

해결 방법

원인 1: PL/pgSQL 예외 처리에서의 올바른 SQLSTATE 활용

PL/pgSQL에서 예외 처리를 구성할 때, 00000은 절대로 예외 상황이 아님을 명확히 인지하고 코드를 작성해야 합니다.

-- 잘못된 예외 처리 패턴 (00000을 에러로 오해하는 경우)
CREATE OR REPLACE FUNCTION bad_exception_example()
RETURNS TEXT AS $$
DECLARE
    v_sqlstate TEXT;
BEGIN
    -- 정상 쿼리 실행
    PERFORM 1;
    
    -- 이 시점에서 SQLSTATE는 '00000' (성공)
    GET DIAGNOSTICS v_sqlstate = RETURNED_SQLSTATE;
    
    -- 잘못된 처리: 00000을 에러로 취급
    IF v_sqlstate != '00000' THEN
        RAISE EXCEPTION '쿼리 실패: %', v_sqlstate;
    END IF;
    
    RETURN '정상 처리됨';
END;
$$ LANGUAGE plpgsql;

-- 올바른 예외 처리 패턴
CREATE OR REPLACE FUNCTION good_exception_example(p_id INTEGER)
RETURNS TEXT AS $$
DECLARE
    v_result TEXT;
    v_sqlstate TEXT;
    v_sqlerrm TEXT;
BEGIN
    -- 정상 비즈니스 로직
    SELECT name INTO STRICT v_result
    FROM users
    WHERE id = p_id;
    
    -- 성공 시 00000이 반환됨을 인지하고 정상 처리
    RETURN '사용자 조회 성공: ' || v_result;

EXCEPTION
    WHEN NO_DATA_FOUND THEN
        -- SQLSTATE: P0002
        GET STACKED DIAGNOSTICS 
            v_sqlstate = RETURNED_SQLSTATE,
            v_sqlerrm = MESSAGE_TEXT;
        RAISE NOTICE 'SQLSTATE: %, 메시지: %', v_sqlstate, v_sqlerrm;
        RETURN '사용자를 찾을 수 없습니다.';
    
    WHEN TOO_MANY_ROWS THEN
        -- SQLSTATE: P0003
        RETURN '복수의 결과가 반환되었습니다.';
    
    WHEN OTHERS THEN
        GET STACKED DIAGNOSTICS 
            v_sqlstate = RETURNED_SQLSTATE,
            v_sqlerrm = MESSAGE_TEXT;
        -- 00000은 OTHERS 블록에 절대 도달하지 않음
        RAISE WARNING '예상치 못한 에러 - SQLSTATE: %, 메시지: %', 
            v_sqlstate, v_sqlerrm;
        RETURN '처리 중 오류 발생';
END;
$$ LANGUAGE plpgsql;

-- 함수 테스트
SELECT good_exception_example(1);

-- DO 블록에서의 올바른 SQLSTATE 확인 방법
DO $$
DECLARE
    v_count INTEGER;
    v_sqlstate TEXT;
BEGIN
    -- 정상 쿼리 실행
    SELECT COUNT(*) INTO v_count FROM pg_tables;
    
    -- 성공 상태(00000) 확인 후 로그 출력
    RAISE NOTICE '쿼리가 성공적으로 완료되었습니다. 테이블 수: %', v_count;
    RAISE NOTICE '현재 SQLSTATE: 00000 (Successful Completion)';

EXCEPTION
    WHEN OTHERS THEN
        GET STACKED DIAGNOSTICS v_sqlstate = RETURNED_SQLSTATE;
        RAISE EXCEPTION '실패 - SQLSTATE: %', v_sqlstate;
END;
$$;

원인 2: 애플리케이션 드라이버에서의 올바른 처리

Python psycopg2를 예로 들어, SQLSTATE 00000을 올바르게 처리하는 패턴을 PostgreSQL 함수로 구현합니다.

-- 애플리케이션과의 연동을 위한 상태 코드 반환 함수
CREATE OR REPLACE FUNCTION get_user_with_status(p_user_id INTEGER)
RETURNS TABLE(
    status_code TEXT,
    status_message TEXT,
    user_id INTEGER,
    user_name TEXT
) AS $$
BEGIN
    RETURN QUERY
    SELECT 
        '00000'::TEXT AS status_code,
        'Successful Completion'::TEXT AS status_message,
        u.id AS user_id,
        u.name AS user_name
    FROM users u
    WHERE u.id = p_user_id;
    
    -- 결과가 없을 경우 명시적 상태 반환
    IF NOT FOUND THEN
        RETURN QUERY
        SELECT 
            'P0002'::TEXT,
            'No Data Found'::TEXT,
            NULL::INTEGER,
            NULL::TEXT;
    END IF;

EXCEPTION
    WHEN OTHERS THEN
        RETURN QUERY
        SELECT 
            SQLSTATE::TEXT,
            SQLERRM::TEXT,
            NULL::INTEGER,
            NULL::TEXT;
END;
$$ LANGUAGE plpgsql;

-- 함수 호출 예시
SELECT * FROM get_user_with_status(1);
SELECT * FROM get_user_with_status(99999);

-- SQLSTATE 코드 참조 테이블 생성 (운영 실무용)
CREATE TABLE IF NOT EXISTS sqlstate_reference (
    sqlstate_code CHAR(5) PRIMARY KEY,
    category TEXT NOT NULL,
    description TEXT NOT NULL,
    is_error BOOLEAN NOT NULL DEFAULT TRUE,
    created_at TIMESTAMPTZ DEFAULT NOW()
);

INSERT INTO sqlstate_reference (sqlstate_code, category, description, is_error)
VALUES 
    ('00000', 'Success', 'Successful Completion - 정상 완료 상태', FALSE),
    ('01000', 'Warning', 'General Warning - 일반 경고', FALSE),
    ('02000', 'No Data', 'No Data Found - 데이터 없음', FALSE),
    ('08000', 'Connection', 'Connection Exception - 연결 오류', TRUE),
    ('23000', 'Integrity', 'Integrity Constraint Violation - 무결성 위반', TRUE),
    ('42000', 'Syntax', 'Syntax Error - 구문 오류', TRUE),
    ('P0001', 'PL/pgSQL', 'Raise Exception - 사용자 정의 예외', TRUE),
    ('P0002', 'PL/pgSQL', 'No Data Found - PL/pgSQL 데이터 없음', TRUE),
    ('P0003', 'PL/pgSQL', 'Too Many Rows - 복수 행 반환', TRUE)
ON CONFLICT (sqlstate_code) DO NOTHING;

-- 특정 SQLSTATE가 에러인지 확인하는 함수
CREATE OR REPLACE FUNCTION is_error_state(p_sqlstate TEXT)
RETURNS BOOLEAN AS $$
    SELECT COALESCE(is_error, TRUE)
    FROM sqlstate_reference
    WHERE sqlstate_code = p_sqlstate;
$$ LANGUAGE sql STABLE;

-- 활용 예시
SELECT is_error_state('00000');  -- FALSE 반환
SELECT is_error_state('23000');  -- TRUE 반환

원인 3: 모니터링 및 로그 설정 최적화

-- PostgreSQL 로그 레벨 및 SQLSTATE 필터링 확인
-- postgresql.conf 설정 확인 쿼리
SELECT 
    name,
    setting,
    unit,
    short_desc
FROM pg_settings
WHERE name IN (
    'log_min_messages',
    'log_error_verbosity',
    'log_min_error_statement',
    'log_statement'
)
ORDER BY name;

-- 현재 세션의 로그 설정 임시 변경 (테스트용)
SET log_min_messages = 'WARNING';
SET log_error_verbosity = 'DEFAULT';

-- SQLSTATE 00000 관련 쿼리 실행 현황 모니터링
SELECT 
    pid,
    usename,
    application_name,
    state,
    query_start,
    state_change,
    LEFT(query, 100) AS query_preview
FROM pg_stat_activity
WHERE state = 'active'
  AND pid != pg_backend_pid()
ORDER BY query_start;

-- 성공적으로 완료된 트랜잭션 통계 확인
SELECT 
    datname AS database_name,
    xact_commit AS successful_transactions,
    xact_rollback AS rolled_back_transactions,
    ROUND(
        xact_commit::NUMERIC / NULLIF(xact_commit + xact_rollback, 0) * 100, 2
    ) AS success_rate_percent
FROM pg_stat_database
WHERE datname NOT IN ('template0', 'template1')
ORDER BY xact_commit DESC;

---

예방 방법

• PL/pgSQL 함수에서 명시적인 SQLSTATE 처리 가이드라인 수립

팀 내 코딩 표준에 SQLSTATE 00000은 성공 상태임을 명확히 문서화하고, 모든 예외 처리 블록에서 WHEN OTHERS 절이 00000을 포함하지 않는다는 것을 교육합니다. 또한 코드 리뷰 시 SQLSTATE 처리 로직을 필수 검토 항목으로 포함시켜, 오해로 인한 잘못된 예외 처리가 프로덕션에 배포되지 않도록 합니다.

“`sql

— 팀 표준 예외 처리 템플릿

CREATE OR REPLACE FUNCTION template_function(p_param TEXT)

RETURNS JSONB AS $$

DECLARE

v_result JSONB;

v_sqlstate TEXT;

v_sqlerrm TEXT;

v_context TEXT;

BEGIN

— 비즈니스 로직 실행

— 성공 시 SQLSTATE는 자동으로 ‘00000’

v_result = jsonb_build_object(

‘status’, ‘00000’,

‘message’, ‘Successful Completion’,

‘data’, NULL

);

RETURN v_result;

EXCEPTION

WHEN OTHERS THEN

— 00000은 여기 절대 도달 불가

GET STACKED DIAGNOSTICS

v_sqlstate = RETURNED_SQLSTATE,

v_sqlerrm = MESSAGE_TEXT,

v_context = PG_EXCEPTION_CONTEXT;

RAISE LOG ‘함수 오류 발생 – SQLSTATE: %, 메시지: %, 컨텍스트: %’,

v_sqlstate, v_sqlerrm, v_context;

RETURN jsonb_build_object(

‘status’, v_sqlstate,

‘message’, v_sqlerrm,

‘data’, NULL

);

END;

$$ LANGUAGE plpgsql;

“`

• 모니터링 도구의 SQLSTATE 필터링 규칙 정기 점검

Prometheus, pgBadger, 또는 자체 모니터링 스크립트에서 PostgreSQL SQLSTATE를 기반으로 알림을 설정할 때는 반드시 00000(성공), 01xxx(경고), 02xxx(데이터 없음) 클래스를 에러 필터에서 제외해야 합니다. 분기별로 모니터링 규칙을 검토하는 정기 점검 프로세스를 운영팀 내에 도입하여, 오탐으로 인한 알림 피로도를 줄이고 실제 에러에 집중할 수 있는 환경을 조성합니다.

---

관련 에러

• 01000 (Warning): 성공적으로 완료되었지만 경고 메시지가 있는 경우. RAISE WARNING 또는 암묵적 데이터 타입 변환 등에서 발생.
• 02000 (No Data): SELECT INTO에서 결과가 없을 때 발생하며, PL/pgSQL에서는 NO_DATA_FOUND 예외로 처리됨.
• P0000 (PL/pgSQL Error): PL/pgSQL 런타임에서 발생하는 일반적인 오류 클래스.
• P0001 (Raise Exception): RAISE EXCEPTION 명령으로 사용자가 명시적으로 발생시킨 예외.
• P0002 (No Data Found): PL/pgSQL의 SELECT INTO STRICT에서 데이터가 없을 때 발생하는 NO_DATA_FOUND 예외.
• P0003 (Too Many Rows): SELECT INTO STRICT에서 복수의 행이 반환될 때 발생하는 TOO_MANY_ROWS 예외.

이 코드들은 모두 PostgreSQL의 SQLSTATE 체계 안에서 서로 밀접하게 연관되어 있으며, PL/pgSQL 함수 개발 시 반드시 함께 이해하고 처리해야 합니다.

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