DEV Community

umzzil nng
umzzil nng

Posted on • Originally published at oraerror.com

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

#postgres #database #dba #sql

08000 connection exception 는?

PostgreSQL 에러 코드 08000은 Connection Exception 으로, 데이터베이스 서버와 클라이언트 간의 네트워크 연결 과정에서 예기치 않은 문제가 발생했을 때 나타나는 에러입니다. 이 에러는 단순한 쿼리 오류가 아니라 물리적·논리적 연결 레이어에서 발생하기 때문에, 애플리케이션이 DB에 접근 자체를 못하게 되는 치명적인 상황으로 이어질 수 있습니다. 일반적으로 08000 계열의 에러는 08001(연결 실패), 08006(연결 단절) 등 더 구체적인 하위 에러와 함께 등장하는 경우가 많으며, 에러 로그를 통해 정확한 원인을 파악하는 것이 중요합니다.

주요 발생 원인

1. PostgreSQL 서버의 pg_hba.conf 인증 설정 오류

pg_hba.conf는 어떤 호스트, 어떤 사용자, 어떤 데이터베이스에 대한 접속을 허용할지 정의하는 핵심 설정 파일입니다. 클라이언트 IP가 허용 목록에 없거나, 인증 방식(md5, scram-sha-256 등)이 클라이언트 설정과 맞지 않으면 연결 자체가 거부되며 08000 에러가 발생합니다. 특히 운영 서버 마이그레이션이나 IP 변경 후 이 설정을 업데이트하지 않아 발생하는 경우가 실무에서 매우 빈번합니다.

2. 네트워크 방화벽 또는 포트 차단 문제

PostgreSQL 기본 포트인 5432가 방화벽 또는 보안 그룹(AWS Security Group, iptables 등)에 의해 차단되어 있으면, 클라이언트는 서버에 TCP 연결 자체를 맺을 수 없습니다. 클라우드 환경(AWS RDS, GCP Cloud SQL 등)에서 인바운드 규칙을 잘못 설정하거나, 온프레미스 환경에서 OS 방화벽 설정이 변경된 경우 이 문제가 나타납니다. 연결 타임아웃이 발생하거나 "Connection refused" 메시지가 함께 출력된다면 이 원인을 가장 먼저 의심해야 합니다.

3. postgresql.conf의 listen_addresses 및 max_connections 설정 문제

listen_addresses가 localhost로만 설정되어 있으면, 외부 IP에서의 모든 연결 시도는 거부됩니다. 또한 max_connections 한도에 도달했을 경우, 새로운 클라이언트 연결이 수립되지 못하고 연결 예외가 발생할 수 있습니다. 특히 커넥션 풀 없이 운영하는 애플리케이션에서 트래픽이 급증할 때 이 상황이 자주 발생하며, 운영 중 갑작스러운 연결 실패의 주요 원인 중 하나입니다.

해결 방법

원인 1: pg_hba.conf 설정 수정

현재 pg_hba.conf 파일의 내용을 확인하고, 접속을 허용할 클라이언트 IP와 인증 방식을 추가합니다.

-- pg_hba.conf 현재 설정 내용 확인 (PostgreSQL 10 이상)
SELECT * FROM pg_hba_file_rules;
Enter fullscreen mode Exit fullscreen mode 
-- pg_hba.conf 파일 경로 확인
SHOW hba_file;
Enter fullscreen mode Exit fullscreen mode

pg_hba.conf 파일을 직접 편집합니다 (OS 레벨):

# /etc/postgresql/15/main/pg_hba.conf 예시

# 특정 IP에서 특정 DB/유저 접속 허용 (scram-sha-256 인증)
host    mydb        myuser      192.168.1.100/32    scram-sha-256

# 특정 서브넷 전체 허용
host    all         all         10.0.0.0/8          scram-sha-256

# 로컬 소켓 접속 허용
local   all         all                             peer
Enter fullscreen mode Exit fullscreen mode

설정 변경 후 PostgreSQL을 재로드합니다 (재시작 없이 적용 가능):

-- PostgreSQL 내부에서 설정 리로드
SELECT pg_reload_conf();
Enter fullscreen mode Exit fullscreen mode 
# OS 레벨에서 리로드
sudo systemctl reload postgresql
# 또는
sudo pg_ctlcluster 15 main reload
Enter fullscreen mode Exit fullscreen mode

원인 2: 방화벽 및 포트 설정 확인 

# PostgreSQL 포트 리스닝 여부 확인
ss -tlnp | grep 5432
# 또는
netstat -tlnp | grep 5432
Enter fullscreen mode Exit fullscreen mode 
# iptables 방화벽 5432 포트 허용 (Linux)
sudo iptables -A INPUT -p tcp --dport 5432 -s 192.168.1.0/24 -j ACCEPT
sudo iptables-save > /etc/iptables/rules.v4
Enter fullscreen mode Exit fullscreen mode

PostgreSQL에서 현재 활성 연결 및 접속 현황을 확인하는 쿼리:

-- 현재 접속 중인 클라이언트 IP 및 상태 확인
SELECT 
    pid,
    usename,
    application_name,
    client_addr,
    client_port,
    state,
    backend_start
FROM pg_stat_activity
WHERE state IS NOT NULL
ORDER BY backend_start DESC;
Enter fullscreen mode Exit fullscreen mode 
-- 클라이언트 IP별 연결 수 집계
SELECT 
    client_addr,
    count(*) AS connection_count
FROM pg_stat_activity
WHERE client_addr IS NOT NULL
GROUP BY client_addr
ORDER BY connection_count DESC;
Enter fullscreen mode Exit fullscreen mode

원인 3: postgresql.conf 설정 검토 및 수정 

-- 현재 listen_addresses 및 max_connections 설정 확인
SHOW listen_addresses;
SHOW max_connections;
Enter fullscreen mode Exit fullscreen mode 
-- 현재 사용 중인 연결 수 vs 최대 연결 수 비교
SELECT 
    count(*) AS current_connections,
    (SELECT setting::int FROM pg_settings WHERE name = 'max_connections') AS max_connections,
    (SELECT setting::int FROM pg_settings WHERE name = 'max_connections') - count(*) AS available_connections
FROM pg_stat_activity;
Enter fullscreen mode Exit fullscreen mode

postgresql.conf 파일 수정 (OS 레벨):

# /etc/postgresql/15/main/postgresql.conf

# 모든 IP에서 접속 허용 (보안 그룹/방화벽으로 별도 제어)
listen_addresses = '*'

# 최대 연결 수 조정 (서버 메모리에 따라 조정 필요)
max_connections = 200

# 슈퍼유저 전용 예약 연결 (긴급 접속용)
superuser_reserved_connections = 3
Enter fullscreen mode Exit fullscreen mode

설정 변경 후 반드시 재시작이 필요한 항목 확인:

-- 재시작 없이 적용 가능한 항목 vs 재시작 필요 항목 확인
SELECT 
    name,
    setting,
    context
FROM pg_settings
WHERE name IN ('listen_addresses', 'max_connections', 'superuser_reserved_connections');
-- context = 'postmaster' 이면 재시작 필요
-- context = 'sighup' 이면 reload만으로 적용 가능
Enter fullscreen mode Exit fullscreen mode 
-- 유휴 상태 연결 강제 종료 (긴급 시 사용)
SELECT pg_terminate_backend(pid)
FROM pg_stat_activity
WHERE state = 'idle'
  AND state_change < now() - interval '10 minutes'
  AND usename != 'postgres';
Enter fullscreen mode Exit fullscreen mode

예방 방법

1. 커넥션 풀러 도입으로 연결 수 안정화

PgBouncer 또는 Pgpool-II 같은 커넥션 풀러를 애플리케이션과 PostgreSQL 사이에 배치하면, 실제 DB에 맺어지는 연결 수를 효과적으로 제어할 수 있습니다. PgBouncer의 transaction 모드를 사용할 경우 수천 개의 클라이언트 요청도 수십 개의 실제 DB 연결로 처리할 수 있어 max_connections 초과로 인한 08000 에러를 근본적으로 예방할 수 있습니다. 아래는 PgBouncer 기본 설정 예시입니다.

# /etc/pgbouncer/pgbouncer.ini 핵심 설정
[databases]
mydb = host=127.0.0.1 port=5432 dbname=mydb

[pgbouncer]
listen_port = 6432
listen_addr = *
auth_type = scram-sha-256
pool_mode = transaction
max_client_conn = 1000
default_pool_size = 20
Enter fullscreen mode Exit fullscreen mode 
-- 모니터링: 현재 연결 수 임계치 알림용 쿼리 (모니터링 시스템에 등록)
SELECT 
    CASE 
        WHEN count(*) > (SELECT setting::int * 0.8 FROM pg_settings WHERE name = 'max_connections')
        THEN 'WARNING: 연결 수 80% 초과'
        ELSE 'NORMAL'
    END AS connection_status,
    count(*) AS current_conn
FROM pg_stat_activity;
Enter fullscreen mode Exit fullscreen mode

2. 설정 변경 시 체크리스트 및 테스트 절차 수립

pg_hba.conf, postgresql.conf 등 연결 관련 설정 파일을 변경할 때는 반드시 스테이징 환경에서 먼저 검증하고, 변경 전 백업을 남기는 습관을 들여야 합니다. 특히 pg_hba.conf 수정 후에는 pg_reload_conf() 적용 전에 pg_hba_file_rules 뷰를 통해 파싱 오류 여부를 확인하는 것이 좋습니다.

-- 설정 리로드 전 pg_hba.conf 파싱 오류 확인
SELECT * FROM pg_hba_file_rules
WHERE error IS NOT NULL;

-- 설정 파일 변경 이력 관리 (변경 시 코멘트 추가 권장)
-- 예: # 2024-01-15 홍길동 - 신규 앱서버 IP 추가 (192.168.10.50)
Enter fullscreen mode Exit fullscreen mode

관련 에러

에러 코드 에러명 설명
08001 SQLSTATE 08001 - sqlclient_unable_to_establish_sqlconnection 클라이언트가 서버에 연결을 맺을 수 없을 때 발생. 방화벽/포트 차단 시 주로 나타남
08003 connection_does_not_exist 이미 닫힌 연결에 쿼리를 보낼 때 발생. 커넥션 풀에서 stale connection 반환 시 자주 등장
08006 connection_failure 통신 중 연결이 끊어질 때 발생. 네트워크 불안정 또는 서버 비정상 종료 시 나타남
08P01 protocol_violation 클라이언트-서버 간 프로토콜 버전 불일치 또는 드라이버 버그로 인해 발생
57P03 cannot_connect_now 서버가 시작 중이거나 복구 중일 때 연결을 거부하는 에러

08000 계열 에러가 발생하면 PostgreSQL 서버 로그($PGDATA/log/)와 함께 클라이언트 측 에러 메시지를 동시에 확인하는 것이 빠른 원인 파악의 핵심입니다. 실무에서는 Prometheus + postgres_exporter를 활용하여 연결 수, 거부된 연결 수를 실시간으로 모니터링하고, 임계치 초과 시 즉시 알람이 오도록 구성하는 것을 강력히 권장합니다.

Top comments (0)