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

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

이 글에서 다루는 내용

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

HV00N fdw unable to establish connection 는?

PostgreSQL 에러 코드 HV00N은 Foreign Data Wrapper(FDW)가 외부 데이터 소스에 연결을 수립하지 못할 때 발생하는 에러입니다. 이 에러는 주로 postgres_fdw, oracle_fdw, mysql_fdw 등의 확장 모듈을 통해 외부 서버에 접근하려 할 때 네트워크 문제, 인증 실패, 또는 잘못된 서버 설정으로 인해 발생합니다. 실무 환경에서는 외부 데이터베이스 서버가 다운되거나, 방화벽 정책이 변경되거나, 접속 계정의 비밀번호가 변경된 경우에 빈번하게 나타납니다.

주요 발생 원인

1. 잘못된 서버 연결 정보 (호스트, 포트, 데이터베이스명)

FDW 서버를 생성할 때 지정한 호스트명, 포트 번호, 또는 데이터베이스명이 올바르지 않으면 연결 자체가 이루어지지 않습니다. 특히 클라우드 환경에서 내부 IP 주소나 DNS 이름이 변경되는 경우, 기존에 설정된 SERVER 정의가 더 이상 유효하지 않아 이 에러가 발생합니다. 운영 환경에서 서버 마이그레이션이나 인프라 변경 후에 FDW 설정을 업데이트하지 않는 것이 가장 흔한 원인 중 하나입니다.

2. 사용자 매핑(User Mapping) 인증 실패

CREATE USER MAPPING 으로 지정한 외부 서버의 사용자 이름이나 비밀번호가 잘못되었거나 만료된 경우 연결이 거부됩니다. 외부 데이터베이스의 비밀번호 정책에 따라 주기적으로 비밀번호가 변경되는데, FDW의 사용자 매핑 정보를 동기화하지 않으면 이 에러가 반복적으로 발생합니다. 특히 보안 강화를 위해 외부 DB의 계정 권한을 축소하거나 계정 자체를 삭제했을 때도 동일한 증상이 나타납니다.

3. 네트워크 및 방화벽 차단

PostgreSQL 서버와 외부 데이터 소스 사이의 네트워크 경로가 방화벽, 보안 그룹, 또는 네트워크 ACL에 의해 차단된 경우 연결을 수립할 수 없습니다. 클라우드 환경(AWS, GCP, Azure)에서는 보안 그룹 규칙이 변경되거나, VPC 피어링 설정이 잘못되어 있을 때 이 에러가 자주 발생합니다. 또한 외부 서버의 pg_hba.conf에서 FDW 요청을 차단하고 있는 경우도 이에 해당합니다.

해결 방법

원인 1 해결: 서버 연결 정보 수정

현재 등록된 FDW 서버 정보를 확인하고, 올바른 정보로 업데이트합니다.

-- 현재 등록된 외부 서버 목록 확인
SELECT srvname, srvoptions
FROM pg_foreign_server;

-- 서버 옵션 변경 (호스트, 포트, 데이터베이스명 수정)
ALTER SERVER my_foreign_server
  OPTIONS (
    SET host 'new-db-host.example.com',
    SET port '5432',
    SET dbname 'target_database'
  );

-- 변경 후 연결 테스트 (실제 외부 테이블 조회)
SELECT * FROM foreign_table_name LIMIT 1;

변경 후 반드시 실제 외부 테이블을 조회하여 연결이 정상적으로 이루어지는지 확인하세요.

원인 2 해결: 사용자 매핑 업데이트

-- 현재 사용자 매핑 정보 확인
SELECT umuser::regrole AS local_user,
       srvname AS foreign_server,
       umoptions AS mapping_options
FROM pg_user_mappings;

-- 비밀번호 또는 사용자명 변경
ALTER USER MAPPING FOR current_user
  SERVER my_foreign_server
  OPTIONS (
    SET user 'fdw_readonly_user',
    SET password 'new_secure_password_2024'
  );

-- 만약 사용자 매핑이 없는 경우 새로 생성
CREATE USER MAPPING FOR local_pg_user
  SERVER my_foreign_server
  OPTIONS (
    user 'remote_db_user',
    password 'remote_db_password'
  );

-- PUBLIC 사용자 매핑 설정 (모든 로컬 사용자에게 적용)
CREATE USER MAPPING FOR PUBLIC
  SERVER my_foreign_server
  OPTIONS (
    user 'fdw_service_account',
    password 'service_account_password'
  );

비밀번호는 평문으로 저장되므로, FDW 전용 계정을 생성하고 최소 권한만 부여하는 것이 보안상 안전합니다.

원인 3 해결: 네트워크 연결 진단 및 pg_hba.conf 설정

-- dblink를 이용한 연결 테스트 (postgres_fdw 대신 임시 확인용)
-- 먼저 dblink 확장 설치 확인
CREATE EXTENSION IF NOT EXISTS dblink;

-- 직접 연결 테스트
SELECT dblink_connect(
  'test_conn',
  'host=remote-host port=5432 dbname=mydb user=fdw_user password=mypassword connect_timeout=5'
);

-- 연결 해제
SELECT dblink_disconnect('test_conn');

-- FDW 서버에 연결 옵션 추가 (타임아웃 설정)
ALTER SERVER my_foreign_server
  OPTIONS (
    ADD connect_timeout '10',
    ADD keepalives '1',
    ADD keepalives_idle '60'
  );

-- 외부 서버의 pg_hba.conf에 추가해야 할 내용 (외부 서버에서 실행)
-- host    target_database    fdw_user    192.168.1.0/24    md5
-- 위 내용을 외부 서버의 pg_hba.conf에 추가 후 reload
-- SELECT pg_reload_conf(); -- 외부 서버에서 실행

네트워크 레벨에서는 telnet remote-host 5432 또는 nc -zv remote-host 5432 명령으로 포트 연결 가능 여부를 먼저 확인하세요.

전체 FDW 설정 재구성 예제

-- 1단계: 확장 모듈 설치
CREATE EXTENSION IF NOT EXISTS postgres_fdw;

-- 2단계: 외부 서버 정의
CREATE SERVER remote_postgres_server
  FOREIGN DATA WRAPPER postgres_fdw
  OPTIONS (
    host 'remote-db.example.com',
    port '5432',
    dbname 'production_db',
    connect_timeout '15',
    application_name 'fdw_connection'
  );

-- 3단계: 사용자 매핑 생성
CREATE USER MAPPING FOR CURRENT_USER
  SERVER remote_postgres_server
  OPTIONS (
    user 'fdw_reader',
    password 'strong_password_here'
  );

-- 4단계: 외부 테이블 생성
CREATE FOREIGN TABLE remote_orders (
  order_id    BIGINT,
  customer_id BIGINT,
  order_date  TIMESTAMP,
  total_amount NUMERIC(15, 2)
)
SERVER remote_postgres_server
OPTIONS (schema_name 'public', table_name 'orders');

-- 5단계: 연결 테스트
SELECT COUNT(*) FROM remote_orders;

예방 방법

1. FDW 연결 상태 주기적 모니터링 자동화

운영 환경에서 FDW 연결 상태를 주기적으로 점검하는 모니터링 스크립트를 구성하면 장애를 사전에 감지할 수 있습니다. pg_stat_activity 뷰와 외부 테이블 조회를 조합하여 Cron 또는 pg_cron 확장을 통해 주기적으로 헬스체크를 수행하고, 실패 시 알림을 발송하는 체계를 갖추는 것이 Best Practice입니다.

-- pg_cron을 이용한 FDW 연결 헬스체크 등록 예시
-- (pg_cron 확장이 설치된 경우)
SELECT cron.schedule(
  'fdw_health_check',
  '*/5 * * * *',  -- 5분마다 실행
  $$
    DO $$
    BEGIN
      PERFORM * FROM remote_orders LIMIT 1;
    EXCEPTION WHEN OTHERS THEN
      INSERT INTO fdw_error_log (error_time, error_message)
      VALUES (NOW(), SQLERRM);
    END;
    $$ LANGUAGE plpgsql;
  $$
);

2. FDW 전용 서비스 계정 및 비밀번호 관리 정책 수립

FDW 연결에 사용하는 외부 DB 계정은 일반 애플리케이션 계정과 분리하여 관리하고, 비밀번호 변경 시 FDW 사용자 매핑도 함께 업데이트하는 프로세스를 문서화해야 합니다. HashiCorp Vault나 AWS Secrets Manager 같은 비밀 관리 도구를 사용하여 비밀번호를 중앙 관리하면 동기화 누락으로 인한 에러를 크게 줄일 수 있습니다. 또한 FDW 전용 계정에는 SELECT 권한만 부여하는 최소 권한 원칙을 적용하여 보안 위험을 최소화하세요.