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

HV005
2026년 07월 22일 | DBMS Error 가이드

이 글에서 다루는 내용

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

HV005 fdw column name not found 는?

PostgreSQL 에러 코드 HV005 (fdw_column_name_not_found) 는 Foreign Data Wrapper(FDW)를 사용하는 외부 테이블(Foreign Table)에서 특정 컬럼 이름을 찾을 수 없을 때 발생하는 에러입니다. 주로 외부 데이터 소스(원격 PostgreSQL, MySQL, CSV 파일 등)의 실제 스키마와 PostgreSQL에 정의된 외부 테이블(Foreign Table)의 컬럼 정의가 일치하지 않을 때 나타납니다. FDW 레이어에서 컬럼 매핑을 수행하는 과정에서 해당 컬럼 식별자를 찾지 못하면 이 에러가 트리거되며, 운영 환경에서 외부 데이터 소스의 스키마가 변경되었을 때 특히 자주 발생합니다.

주요 발생 원인

1. 외부 데이터 소스의 컬럼명 변경 또는 삭제

운영 중에 원격 서버의 테이블에서 컬럼이 삭제되거나 이름이 변경되면, 로컬 PostgreSQL에 정의된 Foreign Table과의 매핑이 깨져 HV005 에러가 발생합니다. 예를 들어, 원격 서버에서 customer_name 컬럼을 cust_name으로 ALTER TABLE 했는데, 로컬의 Foreign Table 정의에는 여전히 customer_name이 남아 있는 경우가 대표적입니다. 이는 팀 간 협업이 부족하거나 원격 스키마 변경 시 로컬 정의를 함께 업데이트하지 않아 발생하는 가장 흔한 원인입니다.

2. Foreign Table 생성 시 컬럼 옵션(column_name)의 잘못된 설정

postgres_fdw, mysql_fdw 등 다양한 FDW 확장에서는 컬럼 레벨의 OPTIONS (column_name '...') 구문을 통해 로컬 컬럼명과 원격 컬럼명을 다르게 매핑할 수 있습니다. 이 옵션에 오타가 있거나 원격 테이블에 존재하지 않는 컬럼명을 지정하면 FDW가 해당 컬럼을 찾지 못하고 HV005를 발생시킵니다. 특히 대소문자를 구분하는 원격 데이터베이스(예: MySQL의 특정 설정)와 연동할 때 이 문제가 자주 나타납니다.

3. FDW 드라이버 버전 불일치 또는 메타데이터 캐시 문제

FDW 확장 업그레이드 이후 내부 메타데이터 캐시가 갱신되지 않거나, 원격 서버와의 통신 중 스키마 정보가 올바르게 전달되지 않는 경우에도 HV005가 발생할 수 있습니다. 이는 드라이버 버전과 원격 서버 버전 간의 프로토콜 차이로 인해 컬럼 메타데이터 파싱에 실패할 때 나타나며, 일시적인 네트워크 장애 이후 캐시가 오염(stale)된 상태로 남아 있는 경우에도 동일한 증상이 나타날 수 있습니다.

해결 방법

원인 1 해결: 원격 스키마 확인 및 Foreign Table 재정의

먼저 원격 서버의 실제 스키마를 확인하고, 로컬 Foreign Table 정의를 현재 원격 스키마에 맞게 수정합니다.

-- 1단계: 현재 로컬 Foreign Table 정의 확인
SELECT column_name, data_type, column_default, is_nullable
FROM information_schema.columns
WHERE table_name = 'foreign_customers'
ORDER BY ordinal_position;

-- 2단계: 원격 서버의 실제 스키마 확인 (postgres_fdw 사용 시)
-- import_foreign_schema를 활용하여 최신 스키마를 가져옵니다
IMPORT FOREIGN SCHEMA public
    LIMIT TO (customers)
    FROM SERVER remote_pg_server
    INTO staging_schema;

-- 3단계: 기존 Foreign Table 삭제 후 재생성
DROP FOREIGN TABLE IF EXISTS public.foreign_customers;

CREATE FOREIGN TABLE public.foreign_customers (
    id          BIGINT        NOT NULL,
    cust_name   VARCHAR(100),   -- 변경된 컬럼명 반영
    email       VARCHAR(200),
    created_at  TIMESTAMP
)
SERVER remote_pg_server
OPTIONS (schema_name 'public', table_name 'customers');

-- 4단계: 정상 동작 확인
SELECT * FROM public.foreign_customers LIMIT 5;

원인 2 해결: 컬럼 옵션(column_name) 수정

로컬 컬럼명과 원격 컬럼명이 다를 때 OPTIONS 구문을 올바르게 지정합니다.

-- 잘못된 column_name 옵션이 설정된 컬럼 확인
SELECT attname, ftoptions
FROM pg_attribute a
JOIN pg_foreign_table ft ON ft.ftrelid = a.attrelid
JOIN pg_class c ON c.oid = ft.ftrelid
WHERE c.relname = 'foreign_customers';

-- 특정 컬럼의 옵션을 수정하는 방법
-- 기존 잘못된 옵션 제거 후 올바른 옵션으로 재설정
ALTER FOREIGN TABLE public.foreign_customers
    ALTER COLUMN local_name
    OPTIONS (DROP column_name);

ALTER FOREIGN TABLE public.foreign_customers
    ALTER COLUMN local_name
    OPTIONS (ADD column_name 'cust_name');  -- 원격 서버의 실제 컬럼명

-- 컬럼명 매핑 전체 예시: 로컬명(id_no)과 원격명(customer_id)이 다른 경우
CREATE FOREIGN TABLE public.foreign_orders (
    id_no       BIGINT,
    order_date  DATE,
    amount      NUMERIC(10, 2)
)
SERVER remote_pg_server
OPTIONS (table_name 'orders')
-- 컬럼 레벨 옵션으로 원격 컬럼명 명시
;

-- 컬럼 옵션 추가
ALTER FOREIGN TABLE public.foreign_orders
    ALTER COLUMN id_no
    OPTIONS (ADD column_name 'customer_id');

원인 3 해결: FDW 메타데이터 캐시 초기화 및 연결 갱신

-- 1단계: 현재 FDW 연결 정보 확인
SELECT * FROM pg_foreign_servers;
SELECT * FROM pg_user_mappings;

-- 2단계: 원격 연결 캐시를 갱신하기 위해 세션을 재시작하거나
-- pg_terminate_backend으로 해당 연결을 강제 종료
SELECT pg_terminate_backend(pid)
FROM pg_stat_activity
WHERE application_name LIKE '%fdw%'
  AND pid <> pg_backend_pid();

-- 3단계: FDW 확장 버전 확인 및 업그레이드
SELECT name, default_version, installed_version
FROM pg_available_extensions
WHERE name IN ('postgres_fdw', 'mysql_fdw', 'file_fdw');

-- 필요 시 FDW 확장 업그레이드
ALTER EXTENSION postgres_fdw UPDATE;

-- 4단계: IMPORT FOREIGN SCHEMA로 최신 스키마 자동 동기화
-- 기존 테이블을 스테이징으로 이동 후 재임포트
BEGIN;
    DROP FOREIGN TABLE IF EXISTS public.foreign_customers;
    IMPORT FOREIGN SCHEMA public
        LIMIT TO (customers)
        FROM SERVER remote_pg_server
        INTO public;
COMMIT;

예방 방법

1. 원격 스키마 변경 시 자동 감지 및 알림 체계 구축

원격 데이터 소스의 스키마가 변경되더라도 즉시 인지할 수 있도록, 정기적으로 로컬 Foreign Table 정의와 원격 실제 스키마를 비교하는 모니터링 스크립트를 cron job 또는 pg_cron으로 스케줄링하세요. 아래와 같은 SQL을 활용하여 컬럼 불일치를 사전에 감지할 수 있습니다.

-- 로컬 Foreign Table 컬럼과 원격 실제 컬럼을 비교하는 모니터링 쿼리
-- (임시 테이블을 활용한 비교 예시)
CREATE OR REPLACE FUNCTION check_foreign_table_schema(
    p_local_table TEXT,
    p_server_name TEXT,
    p_remote_schema TEXT,
    p_remote_table TEXT
) RETURNS TABLE(issue TEXT) AS $$
DECLARE
    v_staging_schema TEXT := 'fdw_schema_check';
BEGIN
    -- 스테이징 스키마 생성
    EXECUTE format('CREATE SCHEMA IF NOT EXISTS %I', v_staging_schema);

    -- 원격 스키마 임포트
    EXECUTE format(
        'IMPORT FOREIGN SCHEMA %I LIMIT TO (%I) FROM SERVER %I INTO %I',
        p_remote_schema, p_remote_table, p_server_name, v_staging_schema
    );

    -- 컬럼 비교: 로컬에 있지만 원격에 없는 컬럼 탐지
    RETURN QUERY
    SELECT format('컬럼 [%s]가 로컬 Foreign Table에 존재하지만 원격에 없음', column_name) AS issue
    FROM information_schema.columns
    WHERE table_schema = 'public' AND table_name = p_local_table
    EXCEPT
    SELECT format('컬럼 [%s]가 로컬 Foreign Table에 존재하지만 원격에 없음', column_name)
    FROM information_schema.columns
    WHERE table_schema = v_staging_schema AND table_name = p_remote_table;

    -- 스테이징 정리
    EXECUTE format('DROP SCHEMA IF EXISTS %I CASCADE', v_staging_schema);
END;
$$ LANGUAGE plpgsql;

2. IMPORT FOREIGN SCHEMA를 활용한 스키마 자동 동기화 파이프라인 구축

수동으로 Foreign Table을 CREATE/ALTER하는 대신, 배포 파이프라인(CI/CD)에 IMPORT FOREIGN SCHEMA 명령을 포함시켜 항상 원격 스키마와 동기화된 상태를 유지하세요. 스테이징 스키마에 먼저 임포트한 뒤 프로덕션 스키마와 교체하는 방식(Blue-Green 스키마 교체)을 사용하면 다운타임 없이 안전하게 스키마를 갱신할 수 있습니다.