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

HV00R
2026년 10월 01일 | DBMS Error 가이드

이 글에서 다루는 내용

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

HV00R fdw table not found 는?

PostgreSQL 에러 코드 HV00R은 Foreign Data Wrapper(FDW) 환경에서 외부 테이블(Foreign Table)을 찾을 수 없을 때 발생하는 오류입니다. 이 에러는 주로 외부 서버(Foreign Server)에 연결된 외부 테이블이 실제 원격 데이터베이스 또는 파일 시스템에 존재하지 않거나, 이름이 일치하지 않을 때 트리거됩니다. FDW를 통해 원격 PostgreSQL, MySQL, Oracle, CSV 파일 등 다양한 외부 데이터 소스에 접근하는 환경에서 빈번하게 발생하며, 운영 중인 시스템에서 갑작스럽게 나타날 경우 데이터 파이프라인 전체에 영향을 줄 수 있는 심각한 오류입니다.

주요 발생 원인

1. 원격 서버에서 테이블이 삭제되거나 이름이 변경된 경우

FDW로 연결된 외부 테이블은 로컬 PostgreSQL의 카탈로그에 메타데이터만 등록되어 있으며, 실제 데이터는 원격 서버에 존재합니다. 원격 서버 관리자가 해당 테이블을 DROP 하거나 ALTER TABLE ... RENAME 으로 이름을 변경하면, 로컬 FDW 정의와 실제 테이블 간의 불일치가 발생하여 HV00R 에러가 발생합니다.

2. CREATE FOREIGN TABLE 시 잘못된 테이블 이름 또는 스키마 지정

외부 테이블을 생성할 때 OPTIONS 절에 지정하는 schema_name 또는 table_name이 원격 서버의 실제 객체와 다른 경우에도 이 에러가 발생합니다. 대소문자 구분, 오타, 스키마 경로 누락 등 사소한 실수가 원인이 될 수 있으며, 특히 postgres_fdw 또는 mysql_fdw처럼 원격 DB에 직접 접속하는 FDW에서 자주 목격됩니다.

3. IMPORT FOREIGN SCHEMA 이후 원격 스키마 구조 변경

IMPORT FOREIGN SCHEMA 명령으로 외부 스키마를 일괄 가져온 이후, 원격 서버에서 테이블이 추가되거나 삭제된 경우 로컬의 외부 테이블 정의와 원격 실제 구조 사이에 불일치가 발생합니다. 이 상태에서 삭제된 원격 테이블에 쿼리를 실행하면 HV00R 에러가 즉시 발생하며, 정기적인 스키마 동기화가 이루어지지 않는 환경에서 특히 위험합니다.

해결 방법

원인 1 해결: 원격 테이블 존재 여부 확인 및 외부 테이블 재정의

먼저 원격 서버에서 해당 테이블이 실제로 존재하는지 확인합니다.

-- 원격 서버에 직접 접속하여 테이블 존재 여부 확인 (dblink 사용 예시)
SELECT *
FROM dblink(
    'host=remote_host port=5432 dbname=remote_db user=myuser password=mypassword',
    'SELECT tablename FROM pg_tables WHERE schemaname = ''public'''
) AS remote_tables(tablename TEXT);

원격 테이블이 이름이 변경된 경우, 로컬의 외부 테이블을 삭제하고 새 이름으로 재생성합니다.

-- 기존 외부 테이블 삭제
DROP FOREIGN TABLE IF EXISTS local_schema.old_foreign_table;

-- 변경된 이름으로 외부 테이블 재생성
CREATE FOREIGN TABLE local_schema.new_foreign_table (
    id          BIGINT,
    name        TEXT,
    created_at  TIMESTAMP
)
SERVER my_foreign_server
OPTIONS (schema_name 'public', table_name 'new_remote_table_name');

원인 2 해결: OPTIONS 절의 테이블 이름 및 스키마 정확히 수정

현재 외부 테이블의 옵션 정보를 확인하고 잘못된 값을 수정합니다.

-- 현재 등록된 외부 테이블 옵션 확인
SELECT ft.foreign_table_name,
       fs.srvname AS server_name,
       fto.option_name,
       fto.option_value
FROM information_schema.foreign_tables ft
JOIN pg_foreign_table pft ON pft.ftrelid = (
    SELECT oid FROM pg_class WHERE relname = ft.foreign_table_name
)
JOIN pg_foreign_server fs ON fs.oid = pft.ftserver
JOIN LATERAL unnest(pft.ftoptions) AS fto_raw ON TRUE
JOIN LATERAL (
    SELECT split_part(fto_raw, '=', 1) AS option_name,
           split_part(fto_raw, '=', 2) AS option_value
) fto ON TRUE
WHERE ft.foreign_table_name = 'my_foreign_table';

-- 외부 테이블 옵션 수정 (table_name 변경)
ALTER FOREIGN TABLE local_schema.my_foreign_table
OPTIONS (SET table_name 'correct_remote_table_name');

-- 스키마도 잘못된 경우
ALTER FOREIGN TABLE local_schema.my_foreign_table
OPTIONS (SET schema_name 'correct_schema');

원인 3 해결: 외부 스키마 재동기화

IMPORT FOREIGN SCHEMA를 재실행하여 최신 원격 스키마 구조를 반영합니다.

-- 기존 외부 테이블 일괄 삭제 (주의: CASCADE 옵션 신중히 사용)
DROP FOREIGN TABLE IF EXISTS local_schema.old_table1 CASCADE;
DROP FOREIGN TABLE IF EXISTS local_schema.old_table2 CASCADE;

-- 원격 스키마를 다시 가져와서 동기화
IMPORT FOREIGN SCHEMA public
    LIMIT TO (table1, table2, table3)  -- 필요한 테이블만 선택적으로 가져오기
    FROM SERVER my_foreign_server
    INTO local_schema;

-- 전체 스키마를 가져오는 경우
IMPORT FOREIGN SCHEMA public
    FROM SERVER my_foreign_server
    INTO local_schema;

외부 테이블 정의가 올바른지 테스트 쿼리로 검증합니다.

-- 외부 테이블 접근 테스트
SELECT COUNT(*) FROM local_schema.my_foreign_table LIMIT 1;

-- FDW 연결 상태 및 외부 테이블 목록 전체 확인
SELECT n.nspname AS schema,
       c.relname AS table_name,
       fs.srvname AS foreign_server,
       s.srvoptions AS server_options
FROM pg_class c
JOIN pg_namespace n ON n.oid = c.relnamespace
JOIN pg_foreign_table ft ON ft.ftrelid = c.oid
JOIN pg_foreign_server fs ON fs.oid = ft.ftserver
LEFT JOIN pg_foreign_server s ON s.oid = ft.ftserver
WHERE c.relkind = 'f'
ORDER BY n.nspname, c.relname;

예방 방법

1. 원격 테이블 변경 감지를 위한 주기적인 헬스체크 스크립트 운영

운영 환경에서는 FDW로 연결된 외부 테이블이 실제로 접근 가능한지 주기적으로 검증하는 모니터링 스크립트를 작성하고 cron 등으로 자동화해야 합니다. 아래와 같은 방어적 쿼리를 활용하면 HV00R 에러가 발생하기 전에 문제를 사전에 탐지할 수 있습니다.

-- 모든 외부 테이블에 대해 접근 가능 여부를 확인하는 함수 예시
CREATE OR REPLACE FUNCTION check_foreign_tables()
RETURNS TABLE(table_name TEXT, status TEXT) AS $$
DECLARE
    ft_rec RECORD;
    query  TEXT;
BEGIN
    FOR ft_rec IN
        SELECT n.nspname || '.' || c.relname AS full_table_name
        FROM pg_class c
        JOIN pg_namespace n ON n.oid = c.relnamespace
        WHERE c.relkind = 'f'
    LOOP
        BEGIN
            query := 'SELECT 1 FROM ' || ft_rec.full_table_name || ' LIMIT 1';
            EXECUTE query;
            RETURN QUERY SELECT ft_rec.full_table_name, 'OK'::TEXT;
        EXCEPTION WHEN OTHERS THEN
            RETURN QUERY SELECT ft_rec.full_table_name, SQLERRM::TEXT;
        END;
    END LOOP;
END;
$$ LANGUAGE plpgsql;

-- 실행
SELECT * FROM check_foreign_tables();

2. 원격 서버 DDL 변경 시 로컬 FDW 정의 동시 업데이트 프로세스 수립

원격 데이터베이스의 테이블 구조 변경(이름 변경, 삭제, 컬럼 수정 등)은 반드시 로컬 PostgreSQL의 외부 테이블 정의 업데이트와 동시에 진행되는 변경 관리 프로세스를 수립해야 합니다. 형상관리 도구(Git 등)를 사용하여 FDW 관련 DDL 스크립트를 버전 관리하고, 원격 서버 변경 시 반드시 FDW 측 담당자에게도 공지하는 협업 체계를 구축하는 것이 장기적으로 가장 효과적인 예방책입니다.