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

22019
2026년 06월 07일 | DBMS Error 가이드

이 글에서 다루는 내용

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

22019 invalid escape character 는?

PostgreSQL 에러 코드 22019 (invalid escape character) 는 SQL 쿼리에서 LIKE, SIMILAR TO, 또는 정규식 패턴 매칭 연산자를 사용할 때, 지정한 이스케이프 문자가 유효하지 않거나 잘못된 형식으로 사용되었을 때 발생합니다. 특히 ESCAPE 절에 단일 문자가 아닌 두 글자 이상의 문자열을 지정하거나, 허용되지 않는 특수 문자를 이스케이프 문자로 설정할 때 이 에러가 트리거됩니다. 실무 환경에서 동적 SQL을 생성하거나 사용자 입력값을 그대로 패턴 매칭에 사용할 때 자주 목격되는 에러입니다.

주요 발생 원인

ESCAPE 절에 단일 문자가 아닌 값을 지정한 경우

PostgreSQL의 LIKE 연산자에서 ESCAPE 절은 반드시 정확히 하나의 문자(single character)만 허용합니다. 두 글자 이상의 문자열을 ESCAPE 문자로 지정하면 즉시 22019 에러가 발생합니다. 예를 들어 ESCAPE '++' 처럼 두 문자를 지정하면 PostgreSQL은 이를 유효하지 않은 이스케이프 문자로 판단합니다.

동적 SQL 생성 시 이스케이프 문자 처리 누락 또는 오류

애플리케이션 레이어에서 사용자 입력을 기반으로 동적 LIKE 패턴을 구성할 때, 이스케이프 문자가 예상치 못한 형태로 쿼리에 삽입되는 경우가 있습니다. 특히 ORM이나 쿼리 빌더에서 자동으로 이스케이프 처리를 하다가 잘못된 문자가 ESCAPE 절에 들어가는 사례가 실무에서 빈번합니다.

빈 문자열(”)을 ESCAPE 문자로 지정한 경우

일부 개발자들은 이스케이프 기능을 비활성화하고 싶을 때 빈 문자열을 ESCAPE 절에 지정합니다. 그러나 PostgreSQL에서는 빈 문자열을 이스케이프 문자로 허용하지 않으며, 이 경우에도 22019 에러가 발생합니다. 이스케이프를 무력화하려면 올바른 방법을 사용해야 합니다.

해결 방법

원인 1 해결: ESCAPE 절에 단일 문자만 사용

잘못된 예시:

-- 에러 발생: ESCAPE 문자가 두 글자
SELECT *
FROM products
WHERE product_name LIKE '%100\%%' ESCAPE '\\';

-- 에러 발생: ESCAPE 문자가 두 글자 (++)
SELECT *
FROM orders
WHERE description LIKE '%50++%%' ESCAPE '++';

올바른 예시:

-- 올바른 예시: 단일 백슬래시를 이스케이프 문자로 사용
SELECT *
FROM products
WHERE product_name LIKE '%100\%%' ESCAPE '\';

-- 올바른 예시: 느낌표를 이스케이프 문자로 사용
SELECT *
FROM orders
WHERE description LIKE '%50!%%' ESCAPE '!';

-- 올바른 예시: 기본 이스케이프 문자(\) 사용 (ESCAPE 절 생략 가능)
SELECT *
FROM products
WHERE product_name LIKE '%100\%%';

원인 2 해결: 동적 SQL에서 안전한 이스케이프 처리

-- PL/pgSQL에서 동적 LIKE 패턴을 안전하게 구성하는 함수
CREATE OR REPLACE FUNCTION safe_like_search(search_term TEXT)
RETURNS TABLE(id INT, name TEXT) AS $$
DECLARE
    safe_pattern TEXT;
BEGIN
    -- 특수문자(%, _, \)를 이스케이프 처리
    safe_pattern := '%' || replace(replace(replace(search_term, '\', '\\'), '%', '\%'), '_', '\_') || '%';

    RETURN QUERY
    SELECT p.id, p.name
    FROM products p
    WHERE p.name LIKE safe_pattern ESCAPE '\';
END;
$$ LANGUAGE plpgsql;

-- 사용 예시
SELECT * FROM safe_like_search('100% organic');
SELECT * FROM safe_like_search('price_discount');

-- 동적 SQL에서 format() 함수를 활용한 안전한 패턴 생성
DO $$
DECLARE
    user_input TEXT := '50% off';
    safe_input TEXT;
    query TEXT;
BEGIN
    -- 이스케이프 처리
    safe_input := replace(replace(replace(user_input, '!', '!!'), '%', '!%'), '_', '!_');

    query := format(
        'SELECT * FROM promotions WHERE title LIKE %L ESCAPE %L',
        '%' || safe_input || '%',
        '!'
    );

    RAISE NOTICE 'Executing: %', query;
    EXECUTE query;
END;
$$;

원인 3 해결: 빈 문자열 대신 올바른 방법으로 이스케이프 비활성화

-- 잘못된 방법: 빈 문자열로 ESCAPE 지정 (에러 발생)
SELECT *
FROM products
WHERE product_name LIKE '%test%' ESCAPE '';

-- 올바른 방법 1: ESCAPE 절 자체를 생략 (기본 이스케이프 문자 \가 적용됨)
SELECT *
FROM products
WHERE product_name LIKE '%test%';

-- 올바른 방법 2: 이스케이프가 필요 없는 패턴에서는 SIMILAR TO 또는 정규식 사용
SELECT *
FROM products
WHERE product_name SIMILAR TO '%test%';

-- 올바른 방법 3: 정규식 연산자 사용 (이스케이프 문자 개념 없음)
SELECT *
FROM products
WHERE product_name ~ 'test';

예방 방법

입력값 검증 및 이스케이프 헬퍼 함수 표준화

프로젝트 내 모든 LIKE 패턴 생성 로직을 중앙화된 헬퍼 함수로 통일하세요. 아래와 같이 이스케이프 처리를 담당하는 전용 함수를 만들어 팀 전체가 공유하면, 개발자마다 다른 방식으로 이스케이프를 처리하다 발생하는 오류를 원천 차단할 수 있습니다.

“`sql

— 재사용 가능한 표준 이스케이프 함수

CREATE OR REPLACE FUNCTION escape_like_pattern(

input_text TEXT,

escape_char TEXT DEFAULT ‘!’

) RETURNS TEXT AS $$

BEGIN

— escape_char 검증

IF length(escape_char) != 1 THEN

RAISE EXCEPTION ‘escape_char must be exactly one character, got: %’, escape_char;

END IF;

RETURN replace(

replace(

replace(input_text, escape_char, escape_char || escape_char),

‘%’, escape_char || ‘%’

‘_’, escape_char || ‘_’

);

END;

$$ LANGUAGE plpgsql IMMUTABLE STRICT;

— 사용 예시

SELECT *

FROM products

WHERE name LIKE ‘%’ || escape_like_pattern(‘50% discount’) || ‘%’ ESCAPE ‘!’;

“`

코드 리뷰 체크리스트에 ESCAPE 절 검증 항목 추가

팀의 코드 리뷰 프로세스에 LIKE/SIMILAR TO 사용 시 반드시 ESCAPE 문자가 단일 문자인지 확인하는 항목을 추가하세요. 또한 CI/CD 파이프라인에 정적 분석 도구나 pgsanity 같은 SQL 린터를 도입하여 잘못된 ESCAPE 절 사용을 자동으로 감지하도록 구성하면 프로덕션 배포 전에 문제를 조기에 발견할 수 있습니다.