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

22011 substring error 는?

PostgreSQL 에러 코드 22011은 substring error로, 문자열에서 부분 문자열을 추출하는 SUBSTRING 함수 또는 관련 문자열 함수를 사용할 때 잘못된 인자값이 전달될 경우 발생합니다. 주로 시작 위치(start position)나 길이(length) 파라미터에 음수 또는 허용되지 않는 값이 입력될 때 트리거됩니다. 이 에러는 데이터 처리 파이프라인, ETL 작업, 혹은 동적 SQL을 다루는 애플리케이션에서 예상치 못한 입력값이 들어올 때 특히 자주 나타납니다.

---

주요 발생 원인

• SUBSTRING 함수에 음수 길이(length) 값 전달

SUBSTRING(string FROM start FOR length) 구문에서 length 파라미터에 음수 값이 전달되면 PostgreSQL은 즉시 22011 에러를 발생시킵니다. 이는 SQL 표준에서 부분 문자열의 길이는 반드시 0 이상이어야 한다고 명시하고 있기 때문입니다. 실무에서는 사용자 입력값이나 계산된 값을 그대로 length 인자로 넘길 때 이런 상황이 빈번하게 발생합니다.

“`sql

— 에러 발생 예시: 음수 길이값 전달

SELECT SUBSTRING(‘Hello World’ FROM 1 FOR -3);

— ERROR: negative substring length not allowed

— SQLSTATE: 22011

“`

• 동적으로 계산된 시작 위치 또는 길이 값이 유효하지 않은 경우

애플리케이션 레이어에서 문자열 길이를 계산하여 SUBSTRING의 인자로 사용할 때, 계산 결과가 의도치 않게 음수가 되는 경우가 있습니다. 예를 들어 LENGTH(column) - some_value 형태의 표현식에서 some_value가 컬럼의 실제 길이보다 클 경우 음수가 반환되어 에러가 발생합니다. 이런 패턴은 특히 가변 길이 문자열을 다루는 테이블에서 자주 발견됩니다.

“`sql

— 에러 발생 예시: 계산된 길이가 음수가 되는 경우

SELECT SUBSTRING(name FROM 1 FOR LENGTH(name) – 10)

FROM employees

WHERE LENGTH(name) < 10;

— 이름의 길이가 10보다 짧으면 음수 길이가 되어 에러 발생

“`

• OVERLAY 또는 유사 함수에서 잘못된 파라미터 조합 사용

OVERLAY(string PLACING replacement FROM start FOR length) 함수에서도 동일한 에러가 발생할 수 있습니다. FOR length 부분에 음수 값이 들어오거나, 복합적인 문자열 조작 쿼리에서 중간 계산 결과가 유효하지 않은 범위를 가질 때 이 에러가 트리거됩니다. 외부 데이터 소스로부터 값을 받아 처리하는 데이터 통합 시나리오에서 검증 없이 그대로 사용하면 위험합니다.

“`sql

— 에러 발생 예시: OVERLAY 함수에서 음수 길이

SELECT OVERLAY(‘Hello World’ PLACING ‘PostgreSQL’ FROM 1 FOR -2);

— ERROR: negative substring length not allowed

— SQLSTATE: 22011

“`

---

해결 방법

원인 1 해결: GREATEST 함수를 이용한 음수 방지

가장 간단하고 실용적인 해결책은 GREATEST(value, 0) 패턴을 사용하여 길이값이 절대 음수가 되지 않도록 보장하는 것입니다.

-- 해결책: GREATEST를 사용하여 최솟값을 0으로 보장
SELECT SUBSTRING('Hello World' FROM 1 FOR GREATEST(0, -3));
-- 결과: '' (빈 문자열 반환, 에러 없음)

-- 실무 적용 예시
SELECT SUBSTRING(product_name FROM 1 FOR GREATEST(0, LENGTH(product_name) - 5))
FROM products;

원인 2 해결: CASE 문을 활용한 조건부 처리

계산된 값이 유효한지 먼저 검사한 후 SUBSTRING을 호출하는 방식으로 안전하게 처리할 수 있습니다.

-- 해결책: CASE 문으로 음수 길이 방지
SELECT 
    name,
    CASE 
        WHEN LENGTH(name) > 10 THEN SUBSTRING(name FROM 1 FOR LENGTH(name) - 10)
        ELSE ''
    END AS trimmed_name
FROM employees;

-- NULLIF와 결합한 방법
SELECT SUBSTRING(
    description 
    FROM 1 
    FOR CASE WHEN LENGTH(description) - 5 > 0 THEN LENGTH(description) - 5 ELSE 0 END
)
FROM articles;

원인 3 해결: 입력값 유효성 검사 함수 생성

재사용 가능한 래퍼 함수를 만들어 안전하게 SUBSTRING을 호출하도록 구성합니다.

-- 안전한 SUBSTRING 래퍼 함수 생성
CREATE OR REPLACE FUNCTION safe_substring(
    p_string TEXT,
    p_start INTEGER,
    p_length INTEGER
) RETURNS TEXT AS $$
BEGIN
    IF p_length < 0 THEN
        RETURN '';
    END IF;
    IF p_start < 1 THEN
        p_start := 1;
    END IF;
    RETURN SUBSTRING(p_string FROM p_start FOR p_length);
END;
$$ LANGUAGE plpgsql IMMUTABLE;

-- 사용 예시
SELECT safe_substring('Hello World', 1, -3);  -- '' 반환
SELECT safe_substring('Hello World', 1, 5);   -- 'Hello' 반환

-- 기존 쿼리를 안전하게 교체
SELECT safe_substring(name, 1, LENGTH(name) - 10)
FROM employees;

---

예방 방법

• CHECK 제약 조건 및 입력 검증 레이어 구축

애플리케이션에서 전달되는 문자열 조작 파라미터에 대해 반드시 사전 검증 로직을 구현하세요. 데이터베이스 레이어에서도 트리거(Trigger)나 CHECK 제약 조건을 활용하여 허용되지 않는 값이 문자열 함수에 전달되지 않도록 방어적 프로그래밍을 적용하는 것이 중요합니다.

“`sql

— 뷰(View)를 통한 안전한 인터페이스 제공

CREATE OR REPLACE VIEW safe_employee_names AS

SELECT

id,

name,

SUBSTRING(name FROM 1 FOR GREATEST(0, LENGTH(name) – 2)) AS short_name

FROM employees;

“`

• NULLIF와 COALESCE를 활용한 방어적 쿼리 작성 습관화

문자열 함수를 사용할 때는 항상 경계값(edge case)을 고려하는 습관을 들이세요. NULLIF, COALESCE, GREATEST, LEAST 같은 PostgreSQL 내장 함수들을 적절히 조합하면 대부분의 22011 에러를 사전에 차단할 수 있습니다. 코드 리뷰 시에도 문자열 함수에 전달되는 수치 인자들을 중점적으로 검토하는 문화를 팀 내에 정착시키는 것을 권장합니다.

“`sql

— 방어적 쿼리 패턴 예시

SELECT

COALESCE(

NULLIF(SUBSTRING(content FROM 1 FOR GREATEST(0, char_limit)), ”),

‘내용 없음’

) AS preview

FROM articles;

“`

---

관련 에러

• 22001 (string_data_right_truncation): 문자열 데이터가 대상 컬럼의 최대 길이를 초과할 때 발생하며, 문자열 조작 결과를 저장할 때 함께 고려해야 합니다.
• 22003 (numeric_value_out_of_range): 수치 연산에서 범위를 초과할 때 발생하며, SUBSTRING의 인자를 계산하는 수식에서 오버플로우가 발생할 경우 22011과 연쇄적으로 나타날 수 있습니다.
• 22027 (trim_error): TRIM 함수 관련 에러로, 문자열 조작 함수군에서 유사한 맥락으로 발생할 수 있습니다.
• 42883 (undefined_function): 잘못된 타입의 인자를 문자열 함수에 전달할 때 발생하며, 22011과 함께 문자열 처리 디버깅 시 자주 마주치는 에러입니다.

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