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

08001 sqlclient unable to establish sqlconnection 는?

PostgreSQL 에러 코드 08001은 클라이언트가 PostgreSQL 서버와의 TCP/IP 연결을 아예 수립하지 못했을 때 발생하는 연결 클래스 에러입니다. 이 에러는 단순히 쿼리 실행 중 발생하는 것이 아니라, 접속 자체가 이루어지기 전 단계인 네트워크 레이어 혹은 인증 레이어에서 차단될 때 나타납니다. 주로 서버가 다운되어 있거나, 방화벽 정책 문제, 잘못된 접속 정보, 혹은 pg_hba.conf 설정 오류로 인해 발생하며, 프로덕션 환경에서 갑작스럽게 발생하면 서비스 전체 장애로 이어질 수 있기 때문에 신속한 원인 파악과 대응이 매우 중요합니다.

---

주요 발생 원인

1. PostgreSQL 서버가 실행되지 않거나 포트가 열려 있지 않음

가장 흔하고 치명적인 원인은 PostgreSQL 서버 프로세스 자체가 중단되어 있거나 지정된 포트(기본 5432)를 리스닝하지 않는 경우입니다. 이는 서버 재부팅 후 자동 시작 설정이 빠져 있거나, OOM Killer에 의해 postgres 프로세스가 강제 종료된 경우에도 발생할 수 있으며, 운영자가 인지하지 못한 상태에서 서비스 장애로 이어지는 경우가 많습니다.

2. 방화벽 또는 네트워크 정책이 접속을 차단

클라이언트와 PostgreSQL 서버 사이에 위치한 방화벽(iptables, ufw, AWS Security Group, GCP Firewall Rule 등)이 5432 포트에 대한 인바운드 또는 아웃바운드 트래픽을 허용하지 않는 경우 이 에러가 발생합니다. 클라우드 환경에서는 특히 Security Group 규칙이나 VPC 설정이 잘못되어 있을 때 자주 발생하며, 인프라 변경 후 갑자기 이 에러가 나타나는 경우 이 원인을 가장 먼저 의심해야 합니다.

3. pg_hba.conf 설정 오류 또는 잘못된 접속 정보

pg_hba.conf 파일은 PostgreSQL의 클라이언트 인증 설정 파일로, 허용된 IP 대역, 사용자, 데이터베이스, 인증 방식을 정의합니다. 클라이언트의 IP가 허용 목록에 없거나, 접속 시 사용하는 호스트명, 포트, 사용자명, 데이터베이스명이 잘못 설정된 경우 서버는 연결 자체를 거부하며 08001 에러가 발생합니다. 또한 postgresql.conf의 listen_addresses 설정이 클라이언트의 접근을 허용하지 않는 경우에도 동일한 증상이 나타납니다.

---

해결 방법

원인 1: 서버 상태 확인 및 재시작

먼저 PostgreSQL 서버가 정상적으로 실행 중인지 확인합니다.

-- psql 로컬 접속 테스트 (서버에서 직접 실행)
psql -U postgres -h 127.0.0.1 -p 5432 -c "SELECT version();"

# 서버 상태 확인 (Linux systemd 환경)
sudo systemctl status postgresql

# 서버가 중지되어 있을 경우 재시작
sudo systemctl start postgresql

# 포트 리스닝 여부 확인
sudo ss -tlnp | grep 5432
# 또는
sudo netstat -tlnp | grep 5432

PostgreSQL이 어떤 주소를 리스닝하는지 확인하고 필요 시 수정합니다.

-- postgresql.conf에서 listen_addresses 확인
SHOW listen_addresses;

-- 모든 인터페이스에서 접속을 허용하려면 postgresql.conf 수정 후 재시작
-- listen_addresses = '*'

원인 2: 방화벽 및 네트워크 설정 점검

# 클라이언트에서 서버로 포트 연결 가능 여부 테스트
telnet <서버IP> 5432
# 또는
nc -zv <서버IP> 5432

# Linux iptables에서 5432 포트 허용
sudo iptables -A INPUT -p tcp --dport 5432 -j ACCEPT

# UFW 사용 시
sudo ufw allow 5432/tcp

# 설정 확인
sudo iptables -L -n | grep 5432

클라우드 환경(AWS RDS 등)에서는 Security Group의 인바운드 규칙에서 클라이언트 IP와 5432 포트가 허용되어 있는지 반드시 확인해야 합니다.

원인 3: pg_hba.conf 및 접속 정보 수정

-- 현재 pg_hba.conf 경로 확인
SHOW hba_file;

-- 현재 접속 가능한 설정 확인 (PostgreSQL 10 이상)
SELECT type, database, user_name, address, auth_method
FROM pg_hba_file_rules;

pg_hba.conf 파일을 직접 편집하여 클라이언트 IP를 허용합니다.

# pg_hba.conf 예시 (파일 직접 편집)
# TYPE  DATABASE        USER            ADDRESS                 METHOD
host    all             all             192.168.1.0/24          md5
host    mydb            myuser          10.0.0.5/32             scram-sha-256
host    all             all             0.0.0.0/0               md5  # 모든 IP 허용 (보안 주의)

변경 후 설정을 리로드합니다.

-- PostgreSQL 내에서 설정 리로드 (재시작 없이 적용)
SELECT pg_reload_conf();

# 또는 OS 커맨드로 리로드
sudo systemctl reload postgresql

접속 정보 자체도 점검합니다.

-- 접속 테스트용 쿼리 (psql 커맨드라인)
-- psql -h <호스트> -p <포트> -U <유저> -d <데이터베이스> -W
psql -h 192.168.1.100 -p 5432 -U myuser -d mydb -W

-- 접속 후 현재 연결 정보 확인
SELECT inet_server_addr(), inet_server_port(), current_user, current_database();

---

예방 방법

1. 연결 모니터링 및 자동 알림 체계 구축

PostgreSQL의 연결 상태를 주기적으로 모니터링하고, 서버가 응답하지 않을 경우 즉시 알림이 발송되도록 자동화된 헬스 체크 시스템을 구성해야 합니다. Prometheus + postgres_exporter 조합 또는 Zabbix, Datadog과 같은 모니터링 툴을 활용하면 연결 불가 상황을 사전에 감지할 수 있습니다.

-- 현재 활성 연결 수 및 최대 연결 수 모니터링
SELECT
    count(*) AS active_connections,
    (SELECT setting::int FROM pg_settings WHERE name = 'max_connections') AS max_connections,
    round(count(*) * 100.0 /
        (SELECT setting::int FROM pg_settings WHERE name = 'max_connections'), 2) AS usage_pct
FROM pg_stat_activity
WHERE state IS NOT NULL;

2. pg_hba.conf 변경 이력 관리 및 최소 권한 원칙 적용

pg_hba.conf는 Git 등의 버전 관리 시스템으로 변경 이력을 추적하고, 불필요하게 넓은 IP 대역(0.0.0.0/0)을 허용하지 않도록 최소 권한 원칙을 적용해야 합니다. 정기적으로 허용된 IP 목록을 검토하고, 더 이상 사용하지 않는 접속 허용 규칙은 즉시 제거하여 보안 사고를 사전에 방지해야 합니다.

-- 비활성 연결 및 오래된 연결 탐지 (예방 목적)
SELECT pid, usename, application_name, client_addr,
       state, now() - state_change AS duration
FROM pg_stat_activity
WHERE state = 'idle'
  AND now() - state_change > interval '10 minutes'
ORDER BY duration DESC;

---

관련 에러

• 08000 (connection_exception): 연결 중 일반적인 예외 상황. 08001보다 포괄적인 연결 오류 클래스입니다.
• 08003 (connection_does_not_exist): 이미 종료된 연결을 사용하려 할 때 발생하며, 커넥션 풀 설정 오류 시 자주 나타납니다.
• 08004 (sqlserver_rejected_establishment_of_sqlconnection): 서버가 의도적으로 연결을 거부한 경우로, pg_hba.conf의 reject 설정이나 max_connections 초과 시 발생합니다.
• 08006 (connection_failure): 연결이 수립된 이후 통신 중 끊어진 경우로, 네트워크 불안정이나 keepalive 설정 문제와 연관됩니다.
• 57P03 (cannot_connect_now): 서버가 시작 중이거나 복구 중일 때 발생하는 에러로, 08001과 함께 자주 혼동됩니다.

---

본 포스트는 AI가 생성한 기술 가이드입니다. 운영 환경 적용 전 충분한 검토를 권장합니다.