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

작성자:

22P05
2026년 08월 19일 | DBMS Error 가이드

이 글에서 다루는 내용

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

22P05 untranslatable character 는?

PostgreSQL 에러 코드 22P05 untranslatable character는 데이터베이스 서버의 인코딩(encoding)으로 변환할 수 없는 문자가 입력되었을 때 발생하는 에러입니다. 주로 클라이언트 인코딩과 서버(데이터베이스) 인코딩 간의 불일치, 또는 특정 인코딩 체계에서 표현할 수 없는 특수 문자나 유니코드 문자가 삽입될 때 나타납니다. 예를 들어, 데이터베이스가 LATIN1 인코딩으로 설정되어 있는데 UTF-8 기반의 이모지(emoji)나 한국어 문자를 저장하려 할 때 이 에러가 발생할 수 있습니다.

주요 발생 원인

  • 클라이언트 인코딩과 서버 인코딩의 불일치

가장 흔한 원인으로, 클라이언트(애플리케이션)가 사용하는 인코딩과 PostgreSQL 데이터베이스 서버가 사용하는 인코딩이 서로 다를 때 발생합니다. 예를 들어, 서버는 SQL_ASCII 또는 LATIN1로 설정되어 있지만, 클라이언트가 UTF-8로 멀티바이트 문자를 전송하면 서버는 해당 문자를 자신의 인코딩 체계로 변환하지 못해 이 에러를 발생시킵니다. 특히 레거시 시스템에서 데이터베이스를 마이그레이션하거나, 다국어 지원이 필요한 환경에서 자주 접할 수 있습니다.

  • SQL_ASCII 인코딩 데이터베이스에 멀티바이트 문자 삽입 시도

SQL_ASCII는 PostgreSQL에서 사실상 인코딩 변환을 수행하지 않는 특별한 설정으로, 단순히 0~127 범위의 ASCII 문자만 온전히 표현합니다. 이 설정에서는 128 이상의 바이트 값을 가진 문자(한글, 중국어, 일본어, 이모지 등)를 저장하거나 변환하려 할 때 22P05 에러가 발생할 수 있습니다. 많은 레거시 PostgreSQL 데이터베이스가 SQL_ASCII로 생성되어 있어 실무에서 특히 주의가 필요한 원인입니다.

  • 애플리케이션 또는 ETL 파이프라인에서 잘못된 인코딩 데이터 유입

외부 파일(CSV, JSON, XML 등)을 임포트하거나 ETL(Extract, Transform, Load) 파이프라인을 통해 데이터를 적재할 때, 소스 데이터의 인코딩이 명확하지 않거나 혼재되어 있는 경우 문제가 발생합니다. 특히 Windows 환경에서 생성된 파일(CP949, EUC-KR 등)을 Linux 기반 PostgreSQL 서버에 적재할 때 인코딩 변환 과정에서 표현 불가능한 문자가 포함되면 이 에러가 발생합니다. 자동화된 배치 작업에서 갑자기 실패하는 형태로 나타나므로 디버깅이 까다롭습니다.

해결 방법

원인 1: 클라이언트 인코딩 확인 및 조정

현재 세션의 인코딩 설정을 확인하고, 필요 시 클라이언트 인코딩을 서버와 일치시킵니다.

-- 현재 서버 및 클라이언트 인코딩 확인
SHOW server_encoding;
SHOW client_encoding;

-- 현재 데이터베이스 인코딩 확인
SELECT pg_encoding_to_char(encoding), datname
FROM pg_database
WHERE datname = current_database();

-- 클라이언트 인코딩을 서버와 맞게 변경 (세션 레벨)
SET client_encoding TO 'UTF8';

-- 또는 연결 문자열에서 지정 (예: psql)
-- psql "host=localhost dbname=mydb user=myuser options='-c client_encoding=UTF8'"

원인 2: SQL_ASCII 데이터베이스 문제 해결

SQL_ASCII 인코딩 데이터베이스에서 멀티바이트 문자를 다뤄야 한다면, 장기적으로는 UTF-8 데이터베이스로 마이그레이션하는 것이 권장됩니다.

-- 현재 데이터베이스 인코딩 확인
SELECT datname, pg_encoding_to_char(encoding) AS encoding
FROM pg_database;

-- UTF-8 인코딩으로 새 데이터베이스 생성 (권장)
CREATE DATABASE mydb_utf8
    ENCODING 'UTF8'
    LC_COLLATE 'ko_KR.UTF-8'
    LC_CTYPE 'ko_KR.UTF-8'
    TEMPLATE template0;

-- 기존 데이터를 새 DB로 마이그레이션할 때 pg_dump 활용
-- (터미널에서 실행)
-- pg_dump -Fc mydb_ascii | pg_restore -d mydb_utf8

-- 임시 방편: 특정 문자를 제거하거나 대체하는 쿼리
-- 변환 불가 문자를 제거하고 삽입하는 예시
INSERT INTO my_table (text_column)
VALUES (
    convert_to(
        regexp_replace('안녕하세요 Hello 🎉', '[^\x00-\x7F]', '', 'g'),
        'UTF8'
    )
);

-- convert 함수를 사용한 인코딩 변환 시도
SELECT convert('한글 텍스트'::bytea, 'UTF8', 'LATIN1');

원인 3: ETL 파이프라인 및 파일 임포트 문제 해결

외부 데이터를 임포트하기 전에 인코딩을 명시적으로 지정하거나, 문제가 되는 문자를 사전에 필터링합니다.

-- COPY 명령어에서 인코딩 명시
COPY my_table (col1, col2, col3)
FROM '/path/to/data.csv'
WITH (
    FORMAT CSV,
    HEADER true,
    ENCODING 'UTF8'
);

-- EUC-KR 인코딩 파일 임포트 예시
COPY my_table (col1, col2)
FROM '/path/to/korean_data.csv'
WITH (
    FORMAT CSV,
    HEADER true,
    ENCODING 'EUC_KR'
);

-- 변환 불가 문자가 포함된 데이터를 확인하는 쿼리
-- (저장된 데이터에서 비ASCII 문자 탐지)
SELECT id, text_column
FROM my_table
WHERE text_column ~ '[^\x00-\x7F]';

-- 특정 컬럼에서 문제 문자를 치환하여 업데이트
UPDATE my_table
SET text_column = regexp_replace(text_column, '[^\x00-\x7F]', '?', 'g')
WHERE text_column ~ '[^\x00-\x7F]';

-- bytea로 원시 바이트를 다루는 방법
SELECT encode(convert_to('테스트', 'UTF8'), 'hex');
SELECT convert_from('\xed979cec8ab8'::bytea, 'UTF8');

예방 방법

  • 신규 데이터베이스는 반드시 UTF-8 인코딩으로 생성하고, 인코딩 정책을 표준화하세요.

모든 신규 데이터베이스는 UTF8 인코딩으로 생성하는 것을 조직의 표준으로 삼아야 합니다. 애플리케이션 연결 설정(JDBC, psycopg2, node-postgres 등)에서도 client_encoding=UTF8을 명시적으로 지정하여 인코딩 불일치가 원천적으로 발생하지 않도록 합니다. 또한 PostgreSQL 설정 파일(postgresql.conf)에서 client_encoding 기본값을 UTF8로 설정해 두면, 클라이언트가 별도로 인코딩을 지정하지 않더라도 안전하게 동작합니다.

“`sql

— postgresql.conf 또는 ALTER SYSTEM으로 기본 클라이언트 인코딩 설정

ALTER SYSTEM SET client_encoding = ‘UTF8’;

SELECT pg_reload_conf();

— 특정 데이터베이스 기본 인코딩 설정

ALTER DATABASE mydb SET client_encoding TO ‘UTF8’;

“`

  • 데이터 입력 단계에서 인코딩 유효성 검사를 수행하고, 모니터링을 구축하세요.

데이터가 데이터베이스에 유입되기 전, 애플리케이션 레이어나 ETL 파이프라인에서 인코딩 유효성 검사를 수행하는 로직을 추가합니다. Python의 경우 str.encode('utf-8', errors='replace')와 같은 방식으로 변환 불가 문자를 사전에 처리하고, PostgreSQL 로그에서 22P05 에러를 모니터링하여 조기에 문제를 감지하는 체계를 갖춥니다.

관련 에러

  • 22021 character_not_in_repertoire: 지정된 문자 레퍼토리(repertoire)에 속하지 않는 문자가 사용되었을 때 발생하며, 22P05와 유사하게 인코딩 관련 문제에서 나타납니다.
  • 22000 data_exception: 데이터 관련 일반 에러로, 인코딩 문제를 포함한 다양한 데이터 예외 상황의 상위 범주입니다.
  • 42846 cannot_coerce: 서로 호환되지 않는 타입 간 변환 시도 시 발생하며, 인코딩 변환 실패와 함께 나타날 수 있습니다.
  • 22P06 nonstandard_use_of_escape_character: 이스케이프 문자의 비표준 사용으로 인한 에러로, 특수 문자 처리 문제와 연관될 수 있습니다.
DBMS 에러 코드 시리즈

주요 DBMS error code를 정리하는 시리즈입니다.
블로그 홈에서 다른 에러도 확인하세요.

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

댓글 남기기