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

22026
2026년 08월 16일 | DBMS Error 가이드

이 글에서 다루는 내용

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

22026 string data length mismatch 는?

PostgreSQL 에러 코드 22026 (string data length mismatch)는 문자열 데이터의 길이가 예상되거나 요구되는 길이와 일치하지 않을 때 발생하는 에러입니다. 주로 고정 길이 문자열 타입(CHAR, BIT)을 다루거나, 외부 데이터 포맷(예: 바이너리 프로토콜, COPY 명령, 외부 확장 모듈)과의 데이터 교환 시 실제 데이터 길이가 선언된 길이와 맞지 않을 때 트리거됩니다. 이 에러는 SQL 표준 클래스 22(데이터 예외)에 속하며, 데이터 무결성과 직결되므로 운영 환경에서 반드시 정확히 해결해야 합니다.

주요 발생 원인

1. COPY 명령 또는 바이너리 포맷으로 데이터 적재 시 길이 불일치

COPY 명령을 사용하여 외부 파일에서 데이터를 적재할 때, 특히 바이너리 포맷(BINARY)을 사용하는 경우 파일 내에 인코딩된 문자열 길이 정보가 테이블에 정의된 컬럼의 길이와 다르면 이 에러가 발생합니다. 예를 들어 소스 시스템에서 CHAR(10)으로 내보낸 데이터를 대상 시스템의 CHAR(8) 컬럼에 적재하려 할 때 길이 불일치가 발생합니다. 이는 시스템 간 마이그레이션이나 ETL 파이프라인에서 매우 흔하게 나타나는 문제입니다.

2. 고정 길이 타입(CHAR, BIT(n)) 컬럼에 잘못된 길이의 값 삽입

CHAR(n) 또는 BIT(n)과 같은 고정 길이 타입은 반드시 선언된 길이를 준수해야 합니다. VARCHAR와 달리 BIT(n) 타입은 정확히 n비트의 데이터를 요구하며, 이보다 짧거나 긴 비트 문자열을 삽입하면 22026 에러가 발생합니다. 특히 외부 애플리케이션이나 ORM에서 생성된 쿼리가 길이 검증 없이 값을 전달할 때 이 문제가 자주 발생합니다.

3. 확장 모듈 또는 Foreign Data Wrapper(FDW) 사용 시 타입 매핑 오류

postgres_fdw, oracle_fdw 등 외부 데이터 소스와 연동하는 FDW(Foreign Data Wrapper)나 커스텀 확장 모듈을 사용할 때, 원격 서버의 문자열 컬럼 정의와 로컬 서버의 컬럼 정의 간 길이가 불일치하면 데이터를 가져오거나 밀어넣는 과정에서 22026 에러가 발생할 수 있습니다. 이 경우 에러 메시지만으로는 원인을 파악하기 어려울 수 있으며, FDW 설정 및 원격 테이블 스키마를 면밀히 검토해야 합니다.

해결 방법

원인 1: COPY 바이너리 포맷 길이 불일치 해결

먼저 문제가 되는 컬럼의 정의를 확인하고, 데이터 소스와 길이를 맞추거나 텍스트 포맷으로 전환하는 것이 가장 빠른 해결책입니다.

-- 현재 테이블 컬럼 길이 확인
SELECT column_name, data_type, character_maximum_length
FROM information_schema.columns
WHERE table_name = 'your_table'
  AND table_schema = 'public';

-- 텍스트 포맷으로 COPY 전환 (바이너리 대신)
COPY your_table (col1, col2, fixed_col)
FROM '/data/import_file.csv'
WITH (FORMAT TEXT, DELIMITER ',', NULL '');

-- 컬럼 길이 조정이 필요한 경우 (확장만 가능, 축소는 데이터 손실 위험)
ALTER TABLE your_table
  ALTER COLUMN fixed_col TYPE CHAR(10);

-- 스테이징 테이블을 활용한 안전한 적재
CREATE TEMP TABLE staging_table (
    id          SERIAL,
    fixed_col   TEXT  -- 우선 TEXT로 받은 뒤 검증
);

COPY staging_table (id, fixed_col)
FROM '/data/import_file.csv'
WITH (FORMAT CSV, HEADER true);

-- 길이 검증 후 본 테이블에 삽입
INSERT INTO your_table (id, fixed_col)
SELECT id, fixed_col::CHAR(10)
FROM staging_table
WHERE char_length(trim(fixed_col)) <= 10;

원인 2: BIT(n) 타입 길이 불일치 해결

BIT(n) 타입은 정확한 비트 수를 요구하므로, 삽입 전 길이를 반드시 맞춰야 합니다.

-- 문제 발생 예시
CREATE TABLE bit_test (
    id      SERIAL PRIMARY KEY,
    flags   BIT(8)
);

-- 아래는 에러 발생: BIT(8)에 5비트 삽입 시도
-- INSERT INTO bit_test (flags) VALUES (B'10101');
-- ERROR: 22026 string data length mismatch

-- 해결: lpad를 활용하여 정확한 길이로 패딩
INSERT INTO bit_test (flags)
VALUES (lpad('10101', 8, '0')::BIT(8));

-- 또는 BIT VARYING(n)으로 타입 변경 (유연한 길이 허용)
ALTER TABLE bit_test
  ALTER COLUMN flags TYPE BIT VARYING(8);

-- 변경 후 정상 삽입
INSERT INTO bit_test (flags)
VALUES (B'10101');   -- BIT VARYING은 최대 8비트 이하 허용

-- 기존 BIT(n) 데이터를 검증하는 쿼리
SELECT id, flags, length(flags::TEXT) AS bit_length
FROM bit_test
WHERE length(flags::TEXT) != 8;

원인 3: FDW 타입 매핑 오류 해결

-- 원격 테이블의 컬럼 정의 확인
SELECT srvname, ft.ftrelid::regclass AS foreign_table
FROM pg_foreign_table ft
JOIN pg_foreign_server fs ON ft.ftserver = fs.oid;

-- FDW 외부 테이블 컬럼 정의 재확인
\d+ your_foreign_table

-- 외부 테이블 컬럼 타입을 TEXT로 완화하여 우선 데이터 수집
ALTER FOREIGN TABLE your_foreign_table
  ALTER COLUMN problem_col TYPE TEXT;

-- 로컬 테이블로 가져올 때 명시적 캐스팅 및 길이 검증
INSERT INTO local_table (id, problem_col)
SELECT id,
       CASE
           WHEN char_length(problem_col) > 10 THEN LEFT(problem_col, 10)
           ELSE RPAD(problem_col, 10)  -- CHAR 타입의 경우 패딩 처리
       END::CHAR(10)
FROM your_foreign_table;

-- FDW 컬럼 옵션으로 원격 컬럼명 명시 매핑
ALTER FOREIGN TABLE your_foreign_table
  ALTER COLUMN local_col OPTIONS (column_name 'remote_col_name');

예방 방법

1. 스테이징 테이블과 데이터 검증 파이프라인 구축

운영 테이블에 직접 외부 데이터를 적재하지 말고, 항상 스테이징(임시) 테이블에 TEXT 타입으로 먼저 수집한 뒤 길이 및 포맷 검증을 거쳐 본 테이블에 삽입하는 파이프라인을 구축하세요. 아래와 같이 CHECK 제약 조건과 트리거를 활용하면 데이터 품질을 사전에 보장할 수 있습니다.

-- 검증용 함수 생성
CREATE OR REPLACE FUNCTION validate_fixed_length(val TEXT, expected_len INT)
RETURNS BOOLEAN AS $$
BEGIN
    RETURN char_length(trim(val)) <= expected_len;
END;
$$ LANGUAGE plpgsql IMMUTABLE;

-- CHECK 제약조건으로 길이 사전 검증
ALTER TABLE your_table
  ADD CONSTRAINT chk_fixed_col_length
  CHECK (validate_fixed_length(fixed_col::TEXT, 10));

2. 스키마 변경 관리 프로세스와 컬럼 길이 문서화

여러 시스템 간 데이터를 주고받는 환경에서는 컬럼 길이 정의를 중앙에서 관리하고, 스키마 변경 시 반드시 연관 시스템의 영향도를 분석해야 합니다. information_schema 또는 pg_catalog를 활용한 스키마 문서 자동화를 도입하여 컬럼 정의 불일치를 사전에 탐지하는 것이 Best Practice입니다.

-- 전체 고정 길이 컬럼 현황 파악 쿼리
SELECT table_schema, table_name, column_name,
       data_type, character_maximum_length
FROM information_schema.columns
WHERE table_schema NOT IN ('pg_catalog', 'information_schema')
  AND data_type IN ('character', 'bit')
ORDER BY table_schema, table_name, ordinal_position;