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

HV00R
2026년 07월 28일 | DBMS Error 가이드

이 글에서 다루는 내용

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

HV00R fdw table not found 는?

HV00R: fdw table not found 에러는 PostgreSQL의 Foreign Data Wrapper(FDW) 기능을 사용할 때, 외부 서버(Foreign Server)에서 참조하려는 외부 테이블(Foreign Table)이 존재하지 않거나 접근할 수 없을 때 발생하는 에러입니다. FDW는 PostgreSQL이 외부 데이터 소스(다른 PostgreSQL 인스턴스, MySQL, Oracle, CSV 파일 등)에 연결하여 데이터를 조회하거나 조작할 수 있게 해주는 강력한 기능인데, 이 과정에서 원격 테이블 매핑이 올바르지 않으면 이 에러가 발생합니다. 주로 postgres_fdw, mysql_fdw, oracle_fdw 등의 FDW 익스텐션 환경에서 자주 나타나며, 운영 환경에서 원격 스키마 변경이나 테이블 삭제 후 로컬 Foreign Table 정의가 동기화되지 않았을 때 가장 빈번하게 발생합니다.

주요 발생 원인

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

FDW로 연결된 원격 PostgreSQL 또는 다른 DB에서 해당 테이블이 DROP TABLE 또는 ALTER TABLE ... RENAME TO로 변경되었을 때, 로컬 PostgreSQL에 정의된 Foreign Table은 여전히 이전 테이블 이름을 참조하고 있어 에러가 발생합니다. 특히 운영 환경에서 DBA 간 소통 없이 원격 스키마 변경이 이루어지면 이 문제가 갑작스럽게 발생하여 서비스 장애로 이어질 수 있습니다.

2. Foreign Table 생성 시 OPTIONS에 잘못된 테이블명 또는 스키마명 지정

CREATE FOREIGN TABLE 구문에서 OPTIONS (schema_name '...', table_name '...') 을 명시할 때 오탈자가 있거나, 원격 서버의 실제 테이블 이름/스키마 이름과 일치하지 않으면 FDW 드라이버가 원격 테이블을 찾지 못해 HV00R 에러가 발생합니다. 로컬 Foreign Table 이름과 원격 테이블 이름이 다를 수 있다는 점을 간과하거나, 대소문자 구분 문제로 인해 발생하는 경우도 많습니다.

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

IMPORT FOREIGN SCHEMA 명령어로 원격 스키마 전체를 한 번에 가져온 후, 원격 서버에서 새로운 테이블 추가/삭제/컬럼 변경이 발생했을 때 로컬 Foreign Table 정의가 자동으로 갱신되지 않습니다. 이 경우 삭제된 원격 테이블을 참조하는 Foreign Table에 쿼리를 실행하면 HV00R 에러가 발생하며, 반대로 새로 추가된 원격 테이블은 로컬에서 전혀 보이지 않는 문제도 동시에 발생합니다.

해결 방법

원인 1 해결: 원격 테이블 존재 여부 확인 후 Foreign Table 재정의

먼저 원격 서버에 실제로 어떤 테이블이 있는지 확인합니다.

-- 원격 서버에 연결하여 테이블 목록 확인 (dblink 또는 직접 psql 접속 후)
-- 로컬에서 현재 등록된 Foreign Table 목록 확인
SELECT foreign_table_schema,
       foreign_table_name,
       ft.srvname AS foreign_server
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 pfs ON pfs.oid = pft.ftserver
ORDER BY foreign_table_schema, foreign_table_name;

원격 테이블 이름이 변경되었다면, 기존 Foreign Table을 삭제하고 새 이름으로 재생성합니다.

-- 기존 Foreign Table 삭제
DROP FOREIGN TABLE IF EXISTS local_schema.old_foreign_table_name;

-- 변경된 원격 테이블 이름으로 Foreign Table 재생성
CREATE FOREIGN TABLE local_schema.new_foreign_table_name (
    id          BIGINT,
    name        VARCHAR(255),
    created_at  TIMESTAMP
)
SERVER remote_pg_server
OPTIONS (schema_name 'public', table_name 'new_remote_table_name');

원인 2 해결: OPTIONS 값 검증 및 수정

현재 Foreign Table에 설정된 OPTIONS를 확인하고 올바르게 수정합니다.

-- Foreign Table의 현재 OPTIONS 확인
SELECT ft.foreign_table_name,
       fto.option_name,
       fto.option_value
FROM information_schema.foreign_tables ft
JOIN pg_foreign_table pft ON pft.ftrelid = (
    SELECT c.oid FROM pg_class c
    JOIN pg_namespace n ON n.oid = c.relnamespace
    WHERE c.relname = ft.foreign_table_name
      AND n.nspname = ft.foreign_table_schema
)
JOIN pg_options_to_table(pft.ftoptions) fto ON TRUE
WHERE ft.foreign_table_name = 'your_foreign_table';

-- OPTIONS 수정 (잘못된 테이블명 교정)
ALTER FOREIGN TABLE local_schema.your_foreign_table
OPTIONS (SET table_name 'correct_remote_table_name',
         SET schema_name 'correct_remote_schema');

원격 서버에서 실제 테이블 목록을 직접 조회하여 정확한 이름을 확인합니다.

-- postgres_fdw 사용 시 원격 서버의 테이블 목록 조회
-- (임시 IMPORT를 통해 원격 스키마 구조 파악)
-- 원격 서버에 직접 연결할 수 있는 권한이 있는 경우
DO $$
DECLARE
    conn text;
BEGIN
    -- 원격 서버 접속 정보 확인
    SELECT srvoptions::text INTO conn
    FROM pg_foreign_server
    WHERE srvname = 'remote_pg_server';
    RAISE NOTICE 'Server options: %', conn;
END;
$$;

원인 3 해결: IMPORT FOREIGN SCHEMA 재실행

원격 스키마 변경 후 Foreign Table 정의를 최신 상태로 동기화합니다.

-- 기존 Foreign Table 전체 삭제 (스키마 단위)
DROP SCHEMA IF EXISTS imported_remote_schema CASCADE;
CREATE SCHEMA imported_remote_schema;

-- 원격 스키마 전체 재임포트
IMPORT FOREIGN SCHEMA public
FROM SERVER remote_pg_server
INTO imported_remote_schema;

-- 특정 테이블만 선택적으로 임포트
IMPORT FOREIGN SCHEMA public
LIMIT TO (orders, customers, products)
FROM SERVER remote_pg_server
INTO imported_remote_schema;

-- 특정 테이블을 제외하고 임포트
IMPORT FOREIGN SCHEMA public
EXCEPT (temp_table, staging_data)
FROM SERVER remote_pg_server
INTO imported_remote_schema;

Foreign Table이 실제로 원격 테이블에 접근 가능한지 최종 검증합니다.

-- Foreign Table 접근 테스트
SELECT COUNT(*) FROM imported_remote_schema.orders LIMIT 1;

-- Foreign Table 상세 정보 확인
\d+ imported_remote_schema.orders

예방 방법

1. 원격 스키마 변경 시 변경 관리 프로세스 수립

원격 데이터베이스에서 테이블 구조 변경(DDL)이 발생할 경우, 반드시 해당 테이블을 참조하는 모든 PostgreSQL 인스턴스의 Foreign Table 정의도 함께 갱신하는 절차를 표준화해야 합니다. 이를 위해 다음과 같은 모니터링 쿼리를 주기적으로 실행하거나, 배포 파이프라인에 Foreign Table 검증 단계를 포함시키는 것을 권장합니다.

-- Foreign Table 유효성 주기적 점검 스크립트
-- 각 Foreign Table에 대해 접근 가능 여부를 확인
DO $$
DECLARE
    r RECORD;
    v_count BIGINT;
    v_sql TEXT;
BEGIN
    FOR r IN
        SELECT foreign_table_schema, foreign_table_name
        FROM information_schema.foreign_tables
        ORDER BY foreign_table_schema, foreign_table_name
    LOOP
        v_sql := format('SELECT COUNT(*) FROM %I.%I',
                        r.foreign_table_schema,
                        r.foreign_table_name);
        BEGIN
            EXECUTE v_sql INTO v_count;
            RAISE NOTICE '[OK] %.% - % rows accessible',
                r.foreign_table_schema,
                r.foreign_table_name,
                v_count;
        EXCEPTION WHEN OTHERS THEN
            RAISE WARNING '[FAIL] %.% - Error: %',
                r.foreign_table_schema,
                r.foreign_table_name,
                SQLERRM;
        END;
    END LOOP;
END;
$$;

2. Foreign Table 메타데이터 문서화 및 네이밍 컨벤션 통일

Foreign Table 생성 시 COMMENT를 반드시 추가하여 원격 서버 정보, 원본 테이블명, 최종 동기화 일자를 기록해두는 습관을 들이면 장애 시 빠른 원인 파악이 가능합니다. 또한 로컬 Foreign Table 이름과 원격 테이블 이름을 동일하게 유지하는 네이밍 컨벤션을 팀 내에서 합의하면 혼선을 크게 줄일 수 있습니다.

-- Foreign Table에 메타데이터 주석 추가
COMMENT ON FOREIGN TABLE local_schema.orders IS
'Remote server: remote_pg_server | Remote schema: public | Remote table: orders | Last synced: 2024-01-15 | Owner: DBA Team';

-- 메타데이터 조회
SELECT c.relname AS foreign_table,
       obj_description(c.oid, 'pg_class') AS comment
FROM pg_class c
JOIN pg_namespace n ON n.oid = c.relnamespace
WHERE c.relkind = 'f'
ORDER BY c.relname;