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

22025 invalid escape sequence 는?

PostgreSQL 에러 코드 22025는 invalid escape sequence로, SQL 문자열 내에서 잘못된 이스케이프 시퀀스가 사용되었을 때 발생합니다. 주로 LIKE 절이나 SIMILAR TO 절, 또는 문자열 리터럴에서 백슬래시(\)를 이스케이프 문자로 사용할 때 PostgreSQL의 이스케이프 규칙을 위반하면 트리거됩니다. 이 에러는 PostgreSQL 9.x 이후 표준 SQL 준수 강화와 standard_conforming_strings 설정 변경으로 인해 더욱 자주 목격되는 에러입니다.

---

주요 발생 원인

1. LIKE 절에서 잘못된 이스케이프 문자 사용

LIKE 패턴 매칭에서 \(백슬래시)를 이스케이프 문자로 사용할 때 발생하는 가장 흔한 원인입니다. PostgreSQL은 기본적으로 standard_conforming_strings = on 설정에서 백슬래시를 일반 문자로 취급하지만, LIKE 절에서는 별도의 이스케이프 처리를 요구하기 때문에 혼란이 생깁니다. 특히 레거시 코드나 다른 데이터베이스(MySQL, Oracle 등)에서 마이그레이션된 코드에서 이 문제가 자주 발생합니다.

2. E” 문자열(이스케이프 문자열)에서 유효하지 않은 시퀀스 사용

E'...' 형식의 이스케이프 문자열 리터럴 안에서 PostgreSQL이 인식하지 못하는 이스케이프 시퀀스를 사용할 때 발생합니다. 예를 들어 E'\q'와 같이 정의되지 않은 이스케이프 문자를 사용하면 PostgreSQL은 이를 유효하지 않은 시퀀스로 판단합니다. 이 경우 \n, \t, \r, \\ 등 PostgreSQL이 공식 지원하는 이스케이프 시퀀스만 사용해야 합니다.

3. ESCAPE 절 없이 특수 문자 처리 시도

LIKE 또는 SIMILAR TO 절에서 %, _, \ 등의 특수 문자를 리터럴로 검색하려 할 때 ESCAPE 절을 명시하지 않고 임의의 이스케이프 처리를 시도하면 에러가 발생합니다. 표준 SQL에서는 이러한 특수 문자를 리터럴로 사용하려면 반드시 ESCAPE 절을 명시적으로 지정해야 합니다. 이를 누락하면 PostgreSQL 파서가 해당 문자열을 올바르게 해석하지 못해 22025 에러를 반환합니다.

---

해결 방법

원인 1 해결: LIKE 절의 올바른 이스케이프 처리

잘못된 예시:

-- 에러 발생: 백슬래시를 이스케이프 문자로 잘못 사용
SELECT * FROM products WHERE name LIKE '%100\%off%';

올바른 방법 1 – ESCAPE 절 명시:

-- ESCAPE 절을 명시적으로 지정
SELECT * FROM products WHERE name LIKE '%100!%off%' ESCAPE '!';

올바른 방법 2 – 표준 방식으로 백슬래시 사용:

-- 백슬래시를 이스케이프 문자로 사용할 경우 명시적으로 선언
SELECT * FROM products WHERE name LIKE '%100\%off%' ESCAPE '\';

올바른 방법 3 – ILIKE와 함께 안전한 특수 문자 검색:

-- 특수 문자를 포함한 LIKE 검색 시 함수 활용
SELECT * FROM products
WHERE name LIKE '%' || replace(replace('100%off', '%', '!%'), '_', '!_') || '%'
ESCAPE '!';

---

원인 2 해결: E” 문자열 내 올바른 이스케이프 시퀀스 사용

잘못된 예시:

-- 에러 발생: \q는 유효하지 않은 이스케이프 시퀀스
SELECT E'\q test string';

-- 에러 발생: \s도 PostgreSQL에서 인식하지 못함
INSERT INTO logs (message) VALUES (E'Error\s occurred');

올바른 방법:

-- PostgreSQL이 지원하는 유효한 이스케이프 시퀀스 목록
-- \n: 줄바꿈, \t: 탭, \r: 캐리지 리턴, \\: 백슬래시, \': 작은따옴표

SELECT E'\n test string';           -- 줄바꿈
SELECT E'\t test string';           -- 탭 문자
SELECT E'Error\\ occurred';         -- 리터럴 백슬래시
INSERT INTO logs (message) VALUES (E'Error\nStack trace:\n...');

-- 불필요한 E'' 형식 대신 일반 문자열 리터럴 사용 권장
INSERT INTO logs (message) VALUES ('Error occurred');

---

원인 3 해결: 특수 문자 검색 시 ESCAPE 절 명시

잘못된 예시:

-- 언더스코어(_)를 리터럴로 검색하려는 잘못된 시도
SELECT * FROM users WHERE username LIKE 'admin\_user';

-- % 기호를 리터럴로 검색하는 잘못된 시도
SELECT * FROM discounts WHERE code LIKE '50\%';

올바른 방법:

-- 명시적인 ESCAPE 절로 언더스코어 리터럴 검색
SELECT * FROM users WHERE username LIKE 'admin|_user' ESCAPE '|';

-- 명시적인 ESCAPE 절로 % 리터럴 검색
SELECT * FROM discounts WHERE code LIKE '50|%' ESCAPE '|';

-- 실무에서 자주 쓰는 함수로 특수 문자 이스케이프 처리
CREATE OR REPLACE FUNCTION escape_like(text) RETURNS text AS $$
  SELECT replace(replace(replace($1, '!', '!!'), '%', '!%'), '_', '!_');
$$ LANGUAGE sql IMMUTABLE STRICT;

-- 위 함수를 활용한 안전한 동적 LIKE 검색
SELECT * FROM users
WHERE username LIKE '%' || escape_like('admin_user') || '%' ESCAPE '!';

---

빠른 진단을 위한 세션 설정 확인

-- 현재 세션의 escape 관련 설정 확인
SHOW standard_conforming_strings;
SHOW escape_string_warning;

-- 이스케이프 경고 활성화 (개발 환경 권장)
SET escape_string_warning = on;

-- standard_conforming_strings 설정 확인 및 변경
-- on: 백슬래시를 일반 문자로 처리 (권장, PostgreSQL 9.1+ 기본값)
-- off: 백슬래시를 이스케이프 문자로 처리 (레거시 동작)
SET standard_conforming_strings = on;

---

예방 방법

1. 파라미터 바인딩(Prepared Statement) 적극 활용

애플리케이션 코드에서 SQL을 동적으로 생성할 때 문자열 연결 대신 파라미터 바인딩을 사용하면 이스케이프 관련 에러를 근본적으로 차단할 수 있습니다. 대부분의 PostgreSQL 드라이버(psycopg2, pg, JDBC 등)는 파라미터 바인딩을 지원하며, 이를 통해 SQL 인젝션 방지와 함께 22025 에러도 예방할 수 있습니다.

-- Python psycopg2 예시 (애플리케이션 레벨)
-- 잘못된 방법 (문자열 연결)
-- query = "SELECT * FROM users WHERE name LIKE '%" + user_input + "%'"

-- 올바른 방법 (파라미터 바인딩)
-- cursor.execute("SELECT * FROM users WHERE name LIKE %s", ('%' + user_input + '%',))

-- PostgreSQL Prepared Statement 직접 사용
PREPARE user_search(text) AS
  SELECT * FROM users WHERE username LIKE '%' || $1 || '%';

EXECUTE user_search('john');

2. escape_string_warning 설정 활성화 및 코드 리뷰 프로세스 구축

postgresql.conf에 escape_string_warning = on을 설정하면 잠재적으로 문제가 될 수 있는 이스케이프 시퀀스를 경고 로그로 남겨 사전에 감지할 수 있습니다. 또한 개발 팀 내 SQL 코드 리뷰 시 LIKE 절과 이스케이프 처리 부분을 중점 검토 항목으로 지정하고, E'' 형식의 문자열 리터럴 사용 시 반드시 유효성 검증을 거치는 프로세스를 도입하는 것이 좋습니다.

-- postgresql.conf 또는 세션 레벨 설정
-- escape_string_warning = on   -- postgresql.conf에 추가

-- 세션 레벨에서 즉시 적용
SET escape_string_warning = on;

-- 데이터베이스 레벨에서 설정 (모든 연결에 적용)
ALTER DATABASE mydb SET escape_string_warning = on;
ALTER DATABASE mydb SET standard_conforming_strings = on;

---

관련 에러

• 22019 invalid_escape_character: LIKE 또는 SIMILAR TO에서 ESCAPE 절에 지정된 이스케이프 문자 자체가 유효하지 않을 때 발생합니다. 단일 문자가 아닌 문자열을 이스케이프 문자로 지정하거나 빈 문자열을 사용하면 이 에러가 트리거됩니다.

• 22021 character_not_in_repertoire: 지정된 인코딩에서 표현할 수 없는 문자를 사용할 때 발생하며, 이스케이프 처리 과정에서 함께 나타나는 경우가 있습니다.

• 42601 syntax_error: 이스케이프 시퀀스 오류가 심각한 경우 파서 단계에서 구문 에러로 변환되어 나타날 수 있습니다.

• 22P06 nonstandard_use_of_escape_character: standard_conforming_strings = off 환경에서 비표준 이스케이프 문자 사용 시 발생하며, 22025와 함께 레거시 코드 마이그레이션 시 자주 등장합니다.

---

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