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

HV001
2026년 07월 26일 | DBMS Error 가이드

이 글에서 다루는 내용

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

HV001 fdw out of memory 는?

PostgreSQL에서 HV001: fdw out of memory 에러는 Foreign Data Wrapper(FDW)가 외부 데이터 소스와 통신하거나 데이터를 처리하는 과정에서 메모리를 할당하지 못할 때 발생합니다. FDW는 PostgreSQL이 외부 데이터베이스(Oracle, MySQL, 다른 PostgreSQL 인스턴스 등)나 파일 시스템에 접근할 수 있도록 해주는 확장 기능인데, 이 과정에서 시스템 메모리가 부족하거나 메모리 할당 한도를 초과하면 이 에러가 발생합니다. 특히 대용량 데이터를 외부 소스에서 가져오거나, 여러 FDW 연결이 동시에 열려 있을 때 자주 목격되는 에러입니다.

주요 발생 원인

work_mem 또는 서버 메모리 설정 부족

FDW를 통해 외부 테이블에서 대량의 데이터를 읽어올 때, PostgreSQL은 내부적으로 정렬·조인·집계 등의 작업을 위해 work_mem 메모리를 사용합니다. 기본값인 4MB는 수백만 건 이상의 레코드를 처리하기에 턱없이 부족하며, 이 한도를 초과하면 FDW 레이어에서 메모리 할당 실패가 발생합니다. 특히 postgres_fdw나 oracle_fdw를 사용할 때 원격 쿼리 결과를 로컬에서 재처리하는 과정에서 이 문제가 빈번하게 나타납니다.

FDW 연결 누수(Connection Leak) 및 과도한 동시 연결

FDW 연결은 일반 PostgreSQL 연결과 마찬가지로 각각 일정량의 메모리를 점유합니다. 애플리케이션 코드에서 외부 테이블 쿼리 후 트랜잭션을 명시적으로 닫지 않거나, 연결 풀링 없이 다수의 세션이 동시에 FDW를 사용하면 메모리가 빠르게 고갈됩니다. 장기 실행 트랜잭션이 FDW 커서를 열어 둔 채로 유지될 경우 서버 메모리가 점진적으로 소비되어 결국 HV001 에러로 이어집니다.

대용량 결과셋을 한 번에 Fetch하는 쿼리 설계 문제

fetch_size 옵션을 적절히 설정하지 않으면 FDW는 원격 서버의 커서에서 데이터를 한꺼번에 모두 가져오려 시도합니다. 예를 들어 수천만 건의 데이터를 한 번의 쿼리로 읽어오는 경우, 중간 버퍼링에 필요한 메모리가 폭발적으로 증가합니다. 이는 특히 postgres_fdw의 기본 fetch_size가 100으로 작게 설정되어 있음에도 불구하고 복잡한 JOIN이나 서브쿼리로 인해 예상보다 훨씬 많은 메모리를 소비하는 케이스에서 자주 발생합니다.

해결 방법

원인 1: 메모리 설정 조정

현재 메모리 설정을 먼저 확인하고, 세션 또는 서버 레벨에서 조정합니다.

-- 현재 work_mem 설정 확인
SHOW work_mem;

-- 세션 레벨에서 work_mem 증가 (FDW 쿼리 실행 전 적용)
SET work_mem = '256MB';

-- 특정 FDW 쿼리에만 적용 후 복원
BEGIN;
SET LOCAL work_mem = '512MB';
SELECT * FROM foreign_large_table WHERE created_at > NOW() - INTERVAL '7 days';
COMMIT;

-- postgresql.conf에 영구 적용 (서버 재시작 필요)
-- work_mem = 256MB
-- max_connections = 100  -- 연결 수 조절로 총 메모리 사용량 제어

-- 변경 후 설정 반영 (reload로 일부 설정 적용 가능)
SELECT pg_reload_conf();

원인 2: FDW 연결 누수 점검 및 정리

현재 열려 있는 FDW 연결 상태를 모니터링하고 불필요한 연결을 정리합니다.

-- 현재 FDW 관련 활성 연결 확인
SELECT pid, usename, application_name, state, query_start, query
FROM pg_stat_activity
WHERE query ILIKE '%foreign%' OR query ILIKE '%fdw%';

-- 장기 실행 중인 유휴 연결 강제 종료 (30분 이상 idle인 세션)
SELECT pg_terminate_backend(pid)
FROM pg_stat_activity
WHERE state = 'idle'
  AND query_start < NOW() - INTERVAL '30 minutes'
  AND usename != 'postgres';

-- FDW 서버의 연결 옵션에 keep_connections 설정 확인
SELECT srvname, srvoptions
FROM pg_foreign_server;

-- keep_connections 비활성화로 트랜잭션 종료 시 연결 해제
ALTER SERVER my_foreign_server OPTIONS (SET keep_connections 'false');

-- 특정 사용자의 FDW 연결 옵션 확인
SELECT umuser::regrole, umoptions
FROM pg_user_mappings
WHERE srvid = (SELECT oid FROM pg_foreign_server WHERE srvname = 'my_foreign_server');

원인 3: fetch_size 및 쿼리 최적화

외부 테이블 쿼리 시 데이터를 나눠서 가져오도록 설정을 최적화합니다.

-- 외부 테이블의 fetch_size 확인
SELECT relname, ftoptions
FROM pg_foreign_table ft
JOIN pg_class c ON ft.ftrelid = c.oid;

-- 외부 테이블 레벨에서 fetch_size 조정
ALTER FOREIGN TABLE foreign_orders OPTIONS (SET fetch_size '1000');

-- 또는 서버 레벨에서 기본 fetch_size 설정
ALTER SERVER my_foreign_server OPTIONS (SET fetch_size '500');

-- 대용량 데이터 처리 시 페이지네이션 쿼리로 분할 처리
DO $$
DECLARE
    v_offset INT := 0;
    v_limit  INT := 10000;
    v_count  INT;
BEGIN
    LOOP
        -- 청크 단위로 외부 데이터 가져와서 로컬 테이블에 삽입
        INSERT INTO local_orders_staging
        SELECT *
        FROM foreign_orders
        LIMIT v_limit OFFSET v_offset;

        GET DIAGNOSTICS v_count = ROW_COUNT;
        EXIT WHEN v_count < v_limit;

        v_offset := v_offset + v_limit;
        RAISE NOTICE 'Processed % rows so far...', v_offset;
    END LOOP;
END;
$$;

-- EXPLAIN으로 FDW 쿼리 실행 계획 확인 (원격 push-down 여부 확인)
EXPLAIN (VERBOSE, ANALYZE)
SELECT o.order_id, c.customer_name
FROM foreign_orders o
JOIN local_customers c ON o.customer_id = c.id
WHERE o.status = 'PENDING';

예방 방법

정기적인 FDW 메모리 사용량 모니터링 및 work_mem 튜닝 자동화

Prometheus + postgres_exporter를 활용하여 FDW 관련 세션의 메모리 사용량과 연결 수를 지속적으로 추적하는 것이 좋습니다. 아래 쿼리를 cron 또는 모니터링 도구에 등록하여 임계치를 초과하면 알림을 받도록 설정하면, 메모리 고갈 이전에 선제적으로 대응할 수 있습니다.

“`sql

— FDW 연결 수 및 상태 주기적 모니터링 쿼리

SELECT

count(*) FILTER (WHERE state = ‘active’) AS active_fdw_sessions,

count(*) FILTER (WHERE state = ‘idle’) AS idle_fdw_sessions,

max(now() – query_start) AS longest_running

FROM pg_stat_activity

WHERE backend_type = ‘client backend’

AND query ~* ‘foreign|fdw’;

“`

외부 테이블 접근 시 트랜잭션 범위 최소화 및 Connection Pooling 적용

PgBouncer와 같은 커넥션 풀러를 도입하여 FDW 연결이 불필요하게 장시간 유지되지 않도록 관리하는 것이 핵심입니다. 또한 외부 테이블을 쿼리하는 코드는 반드시 명시적인 트랜잭션 블록 안에서 실행하고, 완료 즉시 COMMIT 또는 ROLLBACK을 호출하여 FDW 커서와 메모리가 즉시 해제되도록 설계해야 합니다. 특히 배치 작업에서는 청크 단위 처리와 함께 각 청크마다 트랜잭션을 완결시켜 메모리 누적을 방지하세요.