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

22010
2026년 08월 12일 | DBMS Error 가이드

이 글에서 다루는 내용

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

22010 invalid indicator parameter value 는?

PostgreSQL 에러 코드 22010은 invalid indicator parameter value로, 호스트 변수(host variable)와 함께 사용되는 인디케이터(indicator) 파라미터에 잘못된 값이 전달되었을 때 발생합니다. 인디케이터 파라미터는 주로 ECPG(Embedded SQL in C)나 외부 클라이언트 라이브러리에서 NULL 값 또는 특수 상태를 표현하기 위해 사용되는 특별한 변수입니다. 허용되지 않는 인디케이터 값(예: -2 이하의 음수 또는 규격 외 값)이 전달될 경우 PostgreSQL은 이 에러를 반환하며, 주로 C 임베디드 SQL 환경이나 ODBC/JDBC 드라이버를 통한 연결에서 자주 목격됩니다.

주요 발생 원인

ECPG에서 잘못된 인디케이터 변수 값 사용

ECPG(Embedded C PostgreSQL)를 사용할 때 인디케이터 변수는 반드시 -1(NULL을 의미) 또는 0 이상(유효한 값)이어야 합니다. 인디케이터 변수에 -2나 그보다 작은 값, 또는 표준에서 정의되지 않은 임의의 음수 값을 할당하면 PostgreSQL은 해당 값을 올바른 인디케이터로 인식하지 못하고 22010 에러를 발생시킵니다. 예를 들어, 개발자가 실수로 인디케이터 변수를 초기화하지 않거나, 잘못된 로직으로 음수 값을 할당하는 경우가 대표적입니다.

ODBC 또는 외부 드라이버에서 파라미터 바인딩 오류

ODBC 드라이버나 서드파티 커넥터를 통해 PostgreSQL에 연결할 때, SQL 파라미터에 대한 인디케이터 버퍼(indicator buffer)를 잘못 설정하면 이 에러가 발생할 수 있습니다. 특히 SQLBindParameter 함수에서 StrLen_or_IndPtr 인자에 SQL_NULL_DATA(-1) 또는 SQL_NTS(-3) 등 표준 ODBC 상수 이외의 비정상적인 값을 넣을 경우 드라이버가 PostgreSQL 서버로 잘못된 인디케이터 값을 전달하게 됩니다. 레거시 시스템이나 오래된 드라이버 버전을 사용하는 환경에서 특히 빈번하게 나타납니다.

PL/pgSQL 또는 애플리케이션 레벨에서 NULL 처리 미흡

애플리케이션에서 NULL 값을 처리하는 로직이 부정확하거나 누락된 경우, 인디케이터 파라미터와 실제 데이터 값 간의 불일치가 생겨 이 에러가 발생할 수 있습니다. 특히 동적 쿼리(Dynamic Query)를 사용하는 환경에서 파라미터 바인딩 시 NULL 여부를 명시적으로 처리하지 않으면 잘못된 인디케이터 값이 전달될 가능성이 높습니다. 이 경우 서버 측 로그뿐만 아니라 애플리케이션 로그도 함께 확인해야 문제의 근원을 정확히 파악할 수 있습니다.

해결 방법

원인 1: ECPG 인디케이터 변수 수정

ECPG 코드에서 인디케이터 변수를 올바르게 초기화하고, NULL을 표현할 때는 반드시 -1을 사용해야 합니다.

-- ECPG 예제: 올바른 인디케이터 변수 사용
EXEC SQL BEGIN DECLARE SECTION;
    int id;
    char name[50];
    short name_indicator;  -- 인디케이터 변수 (short 타입 권장)
EXEC SQL END DECLARE SECTION;

-- 잘못된 방법: 임의의 음수 값 사용 (에러 유발)
-- name_indicator = -99;  /* 절대 사용 금지 */

-- 올바른 방법 1: NULL을 표현할 때
name_indicator = -1;  /* NULL 값을 의미 */
EXEC SQL INSERT INTO employees (id, name) VALUES (:id, :name INDICATOR :name_indicator);

-- 올바른 방법 2: 유효한 값을 전달할 때
name_indicator = 0;  /* 유효한 데이터가 있음을 의미 */
strcpy(name, "홍길동");
EXEC SQL INSERT INTO employees (id, name) VALUES (:id, :name INDICATOR :name_indicator);

원인 2: ODBC 파라미터 바인딩 수정

ODBC를 사용할 경우 SQLBindParameter에서 인디케이터 값을 표준 상수로 정확히 설정해야 합니다.

-- PostgreSQL 서버 측에서 파라미터 수신 확인용 테스트 쿼리
-- (ODBC 클라이언트에서 아래와 같이 파라미터를 바인딩해야 함)

-- 정상적인 NULL 파라미터 처리 테스트
SELECT * FROM employees WHERE name = $1;

-- NULL 값을 명시적으로 전달하는 올바른 방법 (psql 기준)
SELECT * FROM employees WHERE name IS NOT DISTINCT FROM NULL;

-- ODBC StrLen_or_IndPtr 올바른 상수 값 참고
-- SQL_NULL_DATA  = -1  (NULL 값)
-- SQL_NTS        = -3  (Null-Terminated String)
-- SQL_NO_TOTAL   = -4  (길이 불명)
-- 위 상수 외의 임의 음수 값은 사용 금지

-- 파라미터 바인딩 디버깅을 위한 서버 로그 활성화
-- postgresql.conf 설정:
-- log_min_messages = DEBUG1
-- log_min_error_statement = DEBUG1

원인 3: 애플리케이션 레벨 NULL 처리 보완

-- NULL 처리 로직을 명확히 하기 위한 서버 측 함수 예제
CREATE OR REPLACE FUNCTION safe_insert_employee(
    p_id INTEGER,
    p_name VARCHAR(50),
    p_department VARCHAR(50)
)
RETURNS VOID AS $$
BEGIN
    -- NULL 값을 명시적으로 처리
    INSERT INTO employees (id, name, department)
    VALUES (
        p_id,
        COALESCE(p_name, 'Unknown'),       -- NULL이면 기본값 사용
        NULLIF(p_department, '')            -- 빈 문자열은 NULL로 처리
    );
EXCEPTION
    WHEN SQLSTATE '22010' THEN
        RAISE WARNING '인디케이터 파라미터 오류 발생: id=%, name=%', p_id, p_name;
        -- 안전한 fallback 처리
        INSERT INTO employees (id, name, department)
        VALUES (p_id, 'Unknown', NULL);
END;
$$ LANGUAGE plpgsql;

-- 동적 쿼리에서 NULL 안전 처리 예제
DO $$
DECLARE
    v_name TEXT := NULL;
    v_sql TEXT;
BEGIN
    -- 파라미터가 NULL인 경우를 명시적으로 분기 처리
    IF v_name IS NULL THEN
        v_sql := 'SELECT * FROM employees WHERE name IS NULL';
    ELSE
        v_sql := format('SELECT * FROM employees WHERE name = %L', v_name);
    END IF;
    
    EXECUTE v_sql;
END;
$$;

-- 인디케이터 관련 에러를 모니터링하는 뷰 생성
CREATE OR REPLACE VIEW error_monitor AS
SELECT
    datname,
    usename,
    query_start,
    state,
    query
FROM pg_stat_activity
WHERE state = 'active'
  AND query ILIKE '%indicator%';

예방 방법

인디케이터 변수의 명시적 초기화 및 코드 리뷰 체계화

ECPG나 ODBC를 사용하는 모든 코드에서 인디케이터 변수는 반드시 선언 즉시 초기화하고, NULL을 나타낼 때는 표준 값(-1)만 사용하도록 코딩 가이드라인을 수립하세요. 코드 리뷰 체크리스트에 “인디케이터 변수 초기화 여부”와 “표준 외 음수 값 사용 여부”를 반드시 포함시키고, 정적 분석 도구(Cppcheck, Coverity 등)를 CI/CD 파이프라인에 통합하여 잘못된 인디케이터 사용을 자동으로 감지하도록 구성하면 효과적입니다.

PostgreSQL 서버 로그 레벨 상향 및 에러 모니터링 자동화

postgresql.conf에서 log_min_error_statement = ERROR 이상으로 설정하고, log_line_prefix에 클라이언트 정보를 포함시켜 22010 에러 발생 시 즉시 알림을 받을 수 있는 모니터링 체계를 구축하세요. Prometheus + pg_stat_statements 조합이나 pgBadger 같은 로그 분석 도구를 활용하면 특정 에러 코드의 발생 빈도와 패턴을 추적할 수 있으며, 이를 통해 문제가 되는 쿼리나 애플리케이션 모듈을 신속하게 식별하고 사전에 차단할 수 있습니다.