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

HV001
2026년 09월 29일 | DBMS Error 가이드

이 글에서 다루는 내용

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

HV001 fdw out of memory 는?

PostgreSQL 에러 코드 HV001은 Foreign Data Wrapper(FDW) 작업 수행 중 메모리가 부족할 때 발생하는 오류입니다. FDW는 외부 데이터 소스(다른 PostgreSQL 서버, MySQL, Oracle, CSV 파일 등)에 접근할 수 있도록 해주는 확장 기능인데, 이 과정에서 대용량 데이터를 처리하거나 다수의 원격 연결을 동시에 유지할 때 메모리 한계에 도달하면 이 에러가 트리거됩니다. 특히 postgres_fdw, mysql_fdw, file_fdw 등을 사용하는 환경에서 예상치 못한 대규모 결과셋을 가져오거나 서버의 work_mem, shared_buffers 설정이 낮게 잡혀 있을 때 자주 목격됩니다.

주요 발생 원인

1. work_mem 및 shared_buffers 설정 부족

FDW를 통해 외부 테이블에서 데이터를 가져올 때, PostgreSQL은 정렬, 해시 조인, 집계 연산을 위해 work_mem 메모리 공간을 사용합니다. 기본값인 4MB는 수백만 건의 레코드를 가져오는 FDW 쿼리에는 턱없이 부족하며, 복잡한 JOIN이나 GROUP BY가 포함된 경우 메모리 압박이 더욱 심해집니다. 특히 여러 세션이 동시에 FDW 쿼리를 실행하면 각 세션마다 work_mem이 할당되므로, 시스템 전체 메모리가 순식간에 고갈될 수 있습니다.

2. 외부 테이블에서 과도하게 큰 결과셋 페치

FDW 쿼리에서 WHERE 조건이나 LIMIT 없이 대형 외부 테이블을 전체 스캔(Full Scan)하면, 원격 서버에서 수백만~수억 건의 데이터가 한 번에 로컬 메모리로 올라오게 됩니다. fetch_size 옵션이 너무 크게 설정되어 있거나 기본값을 그대로 사용하는 경우, 하나의 배치에서 처리해야 할 데이터양이 급격히 늘어납니다. 이 상황은 개발 환경에서는 문제없다가 운영 환경에서 데이터가 폭증한 이후에 갑자기 에러로 나타나는 경우가 많아 더욱 주의가 필요합니다.

3. 다수의 FDW 연결 동시 유지 및 커넥션 풀 부재

postgres_fdw는 기본적으로 세션별로 원격 서버에 대한 연결을 유지합니다. 동시 접속자가 많은 환경에서 각 세션이 여러 FDW 서버에 동시 연결을 맺으면, 연결 메타데이터와 결과 버퍼가 메모리를 지속적으로 점유하게 됩니다. 별도의 커넥션 풀(PgBouncer 등) 없이 운영하거나 keep_connections 옵션을 적절히 조율하지 않으면 메모리 소비가 선형 이상으로 증가할 수 있습니다.

해결 방법

원인 1: work_mem 및 shared_buffers 조정

현재 설정을 먼저 확인하고, FDW 세션 또는 역할(Role)에만 한정적으로 메모리를 늘려 시스템 전체 부담을 줄이는 방식을 권장합니다.

-- 현재 메모리 설정 확인
SHOW work_mem;
SHOW shared_buffers;

-- 세션 레벨에서 임시로 work_mem 증가 (해당 세션에만 적용)
SET work_mem = '64MB';

-- 특정 역할(Role)에만 work_mem 적용
ALTER ROLE fdw_user SET work_mem = '128MB';

-- postgresql.conf 영구 변경 (재시작 또는 reload 필요)
-- work_mem = '64MB'
-- shared_buffers = '2GB'   -- 시스템 메모리의 25% 권장

-- 변경 후 reload
SELECT pg_reload_conf();

원인 2: fetch_size 조정 및 쿼리 최적화

외부 테이블 조회 시 한 번에 가져오는 행 수를 줄이고, 반드시 필요한 컬럼과 조건만 사용하도록 쿼리를 개선합니다.

-- 외부 서버의 fetch_size 옵션 확인
SELECT srvname, srvoptions FROM pg_foreign_server;

-- fetch_size를 줄여 메모리 압박 완화 (기본값 100 → 더 작게 조정)
ALTER SERVER remote_pg_server OPTIONS (SET fetch_size '50');

-- 외부 테이블에서 필요한 컬럼과 조건만 선택
-- 나쁜 예: 전체 스캔
SELECT * FROM foreign_large_table;

-- 좋은 예: 조건과 컬럼 한정
SELECT id, created_at, status
FROM foreign_large_table
WHERE created_at >= NOW() - INTERVAL '7 days'
  AND status = 'active'
LIMIT 10000;

-- 배치 처리: OFFSET + LIMIT 방식으로 분할 처리
DO $$
DECLARE
    batch_size INT := 5000;
    offset_val INT := 0;
    row_count  INT;
BEGIN
    LOOP
        INSERT INTO local_staging_table
        SELECT id, created_at, status
        FROM foreign_large_table
        ORDER BY id
        LIMIT batch_size OFFSET offset_val;

        GET DIAGNOSTICS row_count = ROW_COUNT;
        EXIT WHEN row_count < batch_size;

        offset_val := offset_val + batch_size;
        PERFORM pg_sleep(0.1); -- 부하 분산
    END LOOP;
END;
$$;

원인 3: 연결 관리 최적화

불필요한 FDW 연결을 정리하고, 연결 재사용 정책을 조정합니다.

-- 현재 FDW 연결 현황 확인 (postgres_fdw 사용 시)
SELECT pid, usename, application_name, client_addr, state, query
FROM pg_stat_activity
WHERE query LIKE '%foreign%' OR application_name LIKE '%fdw%';

-- 유휴 FDW 연결 강제 종료
SELECT pg_terminate_backend(pid)
FROM pg_stat_activity
WHERE state = 'idle'
  AND application_name LIKE '%fdw%'
  AND state_change < NOW() - INTERVAL '10 minutes';

-- postgres_fdw에서 연결 유지 비활성화 (메모리 절약)
ALTER SERVER remote_pg_server OPTIONS (ADD keep_connections 'off');

-- 사용자 매핑 및 서버 옵션 확인
SELECT um.srvname, um.umoptions, fs.srvoptions
FROM pg_user_mappings um
JOIN pg_foreign_server fs ON fs.srvname = um.srvname;

-- 연결 수 제한을 위한 resource group 활용 (pg_query_settings 또는 역할 제한)
ALTER ROLE fdw_user CONNECTION LIMIT 5;

예방 방법

1. 정기적인 메모리 사용량 모니터링 및 알림 설정

FDW 관련 쿼리가 얼마나 많은 메모리를 소모하는지 pg_stat_activity와 운영체제 레벨 모니터링 툴(Prometheus + postgres_exporter, pgBadger 등)을 연계하여 지속적으로 추적하십시오. 메모리 사용량이 임계치(예: 시스템 RAM의 70%)를 초과하면 즉시 알림이 발송되도록 설정하고, FDW 쿼리별 실행 계획(EXPLAIN (ANALYZE, BUFFERS))을 주기적으로 검토하여 예상치 못한 Full Scan이 발생하지 않는지 확인하는 습관을 들이는 것이 중요합니다.

-- FDW 관련 장기 실행 쿼리 감지
SELECT pid, now() - query_start AS duration, query
FROM pg_stat_activity
WHERE state = 'active'
  AND now() - query_start > INTERVAL '5 minutes'
  AND query ILIKE '%foreign%'
ORDER BY duration DESC;

2. FDW 쿼리에 statement_timeout 및 fetch_size 가이드라인 적용

모든 FDW 관련 역할(Role)에 statement_timeout을 설정하여 장기 실행 쿼리가 메모리를 무한정 점유하는 상황을 방지하십시오. 또한 신규 외부 서버 등록 시 반드시 fetch_size를 명시하고 이를 팀 내 표준 가이드라인으로 문서화하면, 개발자가 실수로 과도한 데이터를 한 번에 페치하는 상황을 사전에 차단할 수 있습니다.

-- FDW 전용 역할에 타임아웃 적용
ALTER ROLE fdw_user SET statement_timeout = '300000'; -- 5분
ALTER ROLE fdw_user SET work_mem = '64MB';

-- 신규 외부 서버 등록 시 fetch_size 명시 (표준화)
CREATE SERVER new_remote_server
    FOREIGN DATA WRAPPER postgres_fdw
    OPTIONS (host '192.168.1.100', port '5432', dbname 'remote_db', fetch_size '100');