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

22025 invalid escape sequence 는?

PostgreSQL 에러 코드 22025는 invalid escape sequence로, SQL 문자열 내에서 잘못된 이스케이프 시퀀스를 사용했을 때 발생합니다. 이 에러는 주로 LIKE, SIMILAR TO 연산자와 함께 사용되는 이스케이프 문자가 올바르지 않거나, 문자열 리터럴 내에서 백슬래시(\)를 잘못 사용할 때 발생합니다. PostgreSQL의 표준 SQL 모드와 비표준 이스케이프 처리 방식의 차이로 인해, 특히 다른 데이터베이스에서 마이그레이션한 쿼리에서 이 에러를 자주 만나게 됩니다.

---

주요 발생 원인

1. LIKE 연산자에서 잘못된 ESCAPE 절 사용

LIKE 또는 ILIKE 연산자에서 ESCAPE 절에 두 글자 이상의 문자열이나 아무 의미 없는 이스케이프 문자를 지정할 때 이 에러가 발생합니다. PostgreSQL의 SQL 표준에 따르면 ESCAPE 절에는 반드시 단 한 글자의 문자만 사용할 수 있으며, 이 규칙을 어기면 즉시 22025 에러가 발생합니다. 실무에서는 레거시 코드나 ORM이 자동 생성한 쿼리에서 이 문제가 빈번하게 나타납니다.

2. 표준 문자열에서 잘못된 백슬래시 이스케이프 시퀀스 사용

PostgreSQL의 standard_conforming_strings 설정이 on(기본값, PostgreSQL 9.1 이후)인 상태에서 일반 작은따옴표 문자열('...') 안에 \n, \t 등의 C 스타일 이스케이프 시퀀스를 사용하면 에러 또는 경고가 발생할 수 있습니다. 표준 문자열 모드에서는 백슬래시가 특별한 의미를 갖지 않으므로, E'' 이스케이프 문자열 리터럴 구문을 사용하지 않으면 의도하지 않은 결과나 에러를 초래할 수 있습니다.

3. SIMILAR TO 정규 표현식에서의 잘못된 이스케이프 처리

SIMILAR TO 연산자를 사용할 때 SQL 정규 표현식 내에서 이스케이프 문자를 잘못 정의하거나, 이스케이프 처리가 필요한 특수 문자(%, _, ., * 등)를 올바르지 않은 방법으로 처리할 때 이 에러가 발생합니다. SIMILAR TO는 SQL 표준 정규 표현식을 사용하며, POSIX 정규 표현식과는 문법이 다르기 때문에 혼동하여 잘못된 이스케이프 시퀀스를 사용하는 경우가 많습니다.

---

해결 방법

원인 1 해결: LIKE의 ESCAPE 절 올바르게 사용하기

ESCAPE 절에는 반드시 단 한 글자의 문자만 사용해야 합니다. 아래는 잘못된 예와 올바른 예입니다.

-- ❌ 잘못된 예: ESCAPE에 두 글자 이상 사용
SELECT * FROM products
WHERE product_code LIKE '100\%' ESCAPE '\\';

-- ❌ 잘못된 예: ESCAPE에 빈 문자열 사용 (일부 케이스)
SELECT * FROM products
WHERE product_name LIKE '%sale!%%' ESCAPE '';

-- ✅ 올바른 예: ESCAPE에 단 한 글자 사용
SELECT * FROM products
WHERE product_code LIKE '100!%' ESCAPE '!';

-- ✅ 올바른 예: 언더스코어와 퍼센트를 리터럴로 사용하고 싶을 때
SELECT * FROM orders
WHERE order_ref LIKE '50!_%' ESCAPE '!';
-- 이 쿼리는 '50_'으로 시작하는 모든 order_ref를 검색합니다.

-- ✅ 실무 예: 사용자 입력 값에서 LIKE 특수문자 이스케이프 처리 함수
CREATE OR REPLACE FUNCTION escape_like_pattern(p_input TEXT)
RETURNS TEXT AS $$
BEGIN
    RETURN REPLACE(
        REPLACE(
            REPLACE(p_input, '!', '!!'),
            '%', '!%'
        ),
        '_', '!_'
    );
END;
$$ LANGUAGE plpgsql;

-- 사용 예
SELECT * FROM customers
WHERE customer_name LIKE '%' || escape_like_pattern('John_Doe') || '%' ESCAPE '!';

원인 2 해결: 표준 문자열과 이스케이프 문자열 구분하기

PostgreSQL에서 C 스타일 이스케이프 시퀀스를 사용하려면 반드시 E'' 접두사를 사용해야 합니다.

-- ❌ 잘못된 예: 표준 문자열에서 C 스타일 이스케이프 사용
-- standard_conforming_strings=on 환경에서 경고 또는 에러 발생
INSERT INTO logs (message) VALUES ('첫 번째 줄\n두 번째 줄');

-- ✅ 올바른 예: E'' 이스케이프 문자열 리터럴 사용
INSERT INTO logs (message) VALUES (E'첫 번째 줄\n두 번째 줄');

-- ✅ 올바른 예: 탭 문자 포함
INSERT INTO logs (message) VALUES (E'열1\t열2\t열3');

-- ✅ 올바른 예: 백슬래시 자체를 포함하려면
INSERT INTO file_paths (path) VALUES (E'C:\\Users\\PostgreSQL\\data');

-- 현재 설정 확인
SHOW standard_conforming_strings;

-- 세션 레벨에서 비표준 모드로 변경 (권장하지 않음, 임시 디버깅 용도)
SET standard_conforming_strings = off;

-- ✅ 권장: dollar quoting으로 백슬래시 문제 우회
INSERT INTO scripts (code) VALUES ($$C:\Users\PostgreSQL\data$$);

원인 3 해결: SIMILAR TO에서 올바른 이스케이프 처리

-- ❌ 잘못된 예: SIMILAR TO에서 잘못된 이스케이프 사용
SELECT * FROM products
WHERE product_code SIMILAR TO '(ABC\-DEF)';

-- ✅ 올바른 예: SIMILAR TO에서 특수 문자 이스케이프
-- 하이픈(-)을 리터럴로 사용
SELECT * FROM products
WHERE product_code SIMILAR TO '(ABC[-]DEF)%';

-- ✅ 올바른 예: ESCAPE 절을 명시적으로 지정
SELECT * FROM products
WHERE product_code SIMILAR TO 'ABC!-DEF%' ESCAPE '!';

-- ✅ 실무 권장: SIMILAR TO 대신 POSIX 정규식 사용 (더 강력하고 직관적)
SELECT * FROM products
WHERE product_code ~ '^ABC-DEF';

-- ✅ 대소문자 무시 POSIX 정규식
SELECT * FROM products
WHERE product_code ~* '^abc-def';

-- 에러 발생 시 디버깅용: 이스케이프 처리 테스트
SELECT 'ABC-DEF' SIMILAR TO 'ABC!-DEF' ESCAPE '!';  -- true 반환 확인

---

예방 방법

1. 이스케이프 처리 전용 함수와 파라미터 바인딩 사용

실무에서 사용자 입력을 받아 동적 쿼리를 구성할 때는 반드시 이스케이프 처리 함수를 별도로 만들어 사용하고, 가능하면 파라미터 바인딩(Prepared Statement)을 통해 SQL 인젝션과 이스케이프 문제를 동시에 예방해야 합니다. 특히 애플리케이션 레벨의 ORM을 사용하더라도, LIKE 패턴 처리 시에는 ORM의 이스케이프 처리 방식을 반드시 확인하고 테스트해야 합니다.

-- 애플리케이션에서 파라미터 바인딩 예 (Python psycopg2 스타일 주석)
-- cursor.execute("SELECT * FROM t WHERE name LIKE %s ESCAPE '!'", (escape_like(user_input),))

-- DB 레벨에서 범용 LIKE 이스케이프 함수 등록
CREATE OR REPLACE FUNCTION safe_like_escape(input_text TEXT, escape_char TEXT DEFAULT '!')
RETURNS TEXT AS $$
BEGIN
    RETURN REPLACE(
        REPLACE(
            REPLACE(input_text, escape_char, escape_char || escape_char),
            '%', escape_char || '%'
        ),
        '_', escape_char || '_'
    );
END;
$$ LANGUAGE plpgsql IMMUTABLE STRICT;

2. standard_conforming_strings 설정 명시적 관리 및 코드 리뷰 기준 수립

PostgreSQL 9.1 이후 standard_conforming_strings의 기본값은 on이며, 이를 전제로 코드를 작성해야 합니다. 팀 내 코딩 컨벤션에 “백슬래시 이스케이프가 필요할 경우 반드시 E'' 접두사를 사용한다”, “ESCAPE 절에는 단 한 글자의 이스케이프 문자만 사용한다”는 규칙을 명시적으로 포함시키고, 코드 리뷰 체크리스트에 이스케이프 처리 검증 항목을 추가하는 것이 좋습니다.

---

관련 에러

• 22019 invalid_escape_character: ESCAPE 절에 지정한 문자 자체가 유효하지 않을 때 발생하며, 22025와 함께 자주 발생하는 에러입니다.
• 22021 character_not_in_repertoire: 문자 집합에 포함되지 않는 문자를 이스케이프 시퀀스로 표현하려 할 때 발생합니다.
• 42601 syntax_error: 이스케이프 시퀀스 문법 오류가 SQL 파서 단계에서 잡힐 때 발생하며, 22025와 혼동되는 경우가 있습니다.
• 22P02 invalid_text_representation: 잘못된 문자 표현과 관련된 에러로, 이스케이프 처리 문제와 함께 나타날 수 있습니다.

---

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