DevOps 지식 허브
DevOps 지식 허브

일반적인 PostgreSQL 연결 오류 문제 해결

PostgreSQL 연결 문제에 직면하셨습니까? 이 문서는 인증 실패, 네트워크 거부 및 서비스 미사용과 같은 일반적인 오류를 해결하기 위한 종합 가이드를 제공합니다. `pg_hba.conf` 충돌, 잘못된 자격 증명 및 서버 응답 없음 문제를 진단하는 방법을 알아보십시오. 실용적인 단계, 명령줄 예제 및 모범 사례를 통해 연결 문제를 신속하게 해결하고 PostgreSQL 데이터베이스를 항상 액세스 가능하고 안전하게 유지하는 데 필요한 지식을 얻을 수 있습니다.

54 조회수

일반적인 PostgreSQL 연결 오류 문제 해결

PostgreSQL은 견고성과 신뢰성으로 잘 알려져 있지만, 복잡한 시스템이므로 애플리케이션과 사용자가 데이터베이스에 액세스하지 못하게 하는 연결 문제가 발생할 수 있습니다. 이러한 오류는 잘못된 인증 자격 증명, 잘못 구성된 네트워크 설정 또는 비활성 데이터베이스 서비스 등 다양한 출처에서 발생할 수 있습니다. 서버에 연결할 수 없습니다 또는 암호 인증 실패 메시지가 표시되면 특히 데이터에 대한 빠른 액세스가 필요할 때 좌절감을 느낄 수 있습니다.

이 포괄적인 가이드는 일반적인 PostgreSQL 연결 오류를 명확히 하고 명확하고 실행 가능한 솔루션을 제공하는 것을 목표로 합니다. 인증 실패, 네트워크 구성 문제, 서비스 가용성 부족 등 일반적인 문제의 원인을 살펴보고 체계적인 문제 해결 단계를 안내합니다. 근본적인 원인을 이해하고 여기에 설명된 실용적인 솔루션을 적용하면 대부분의 연결 문제를 진단하고 해결할 수 있는 좋은 장비를 갖추게 되어 PostgreSQL 데이터베이스에 계속 액세스하고 운영할 수 있습니다.

PostgreSQL 연결 기본 사항 이해

특정 오류를 자세히 살펴보기 전에 PostgreSQL이 연결을 처리하는 방법을 이해하는 것이 중요합니다. PostgreSQL은 클라이언트-서버 모델로 작동합니다. 클라이언트(예: psql 명령줄 도구, 웹 애플리케이션 또는 데스크톱 클라이언트)는 PostgreSQL 서버 프로세스에 연결하려고 시도합니다. 이 프로세스는 일반적으로 특정 네트워크 인터페이스와 포트(기본값 5432)에서 들어오는 연결을 수신 대기합니다.

두 가지 주요 구성 파일이 연결 수락 및 인증 방식을 제어합니다.

  • postgresql.conf: listen_addresses 및 port를 포함하여 수신할 네트워크 인터페이스를 포함한 일반 서버 동작을 제어합니다.
  • pg_hba.conf: (호스트 기반 인증) 어떤 인증 방법을 사용하여 어느 데이터베이스에 어디서 연결할 수 있는지를 지정합니다. 이 파일은 보안 및 액세스 제어에 매우 중요합니다.

이러한 파일의 역할과 클라이언트-서버 상호 작용을 이해하는 것은 효과적인 문제 해결의 기본입니다.

일반적인 연결 오류 및 해결 방법

발생할 수 있는 가장 빈번한 연결 오류와 해당 해결 방법을 분석해 보겠습니다.

오류 1: FATAL: database "..." does not exist

이 오류는 클라이언트가 지정한 데이터베이스 이름이 PostgreSQL 서버에 존재하지 않음을 의미합니다.

설명: 클라이언트 애플리케이션 또는 psql 명령이 생성되지 않았거나 이름이 잘못 입력된 데이터베이스에 연결하려고 시도하고 있습니다.

솔루션:
1. 데이터베이스 이름 확인: 연결 문자열 또는 psql 명령의 데이터베이스 이름이 올바른지 확인합니다.
2. 기존 데이터베이스 나열: 기본 데이터베이스(예: postgres 또는 template1)에 연결하고 \l(또는 \list)을 사용하여 사용 가능한 모든 데이터베이스를 나열합니다.

# 기본 'postgres' 데이터베이스에 연결 시도
psql -U your_username -h your_host -d postgres

# 연결되면 모든 데이터베이스 나열
\l

# 누락된 데이터베이스 생성 예시
CREATE DATABASE my_app_db;

오류 2: FATAL: role "..." does not exist

이것은 연결에 지정된 사용자 이름(역할)이 존재하지 않음을 나타냅니다.

설명: 데이터베이스 오류와 유사하게 연결을 시도하는 사용자 계정이 없거나 이름이 잘못 입력되었습니다.

솔루션:
1. 사용자 이름 확인: 연결 문자열의 사용자 이름을 확인합니다.
2. 기존 역할 나열: 슈퍼유저 계정(예: postgres 사용자)으로 연결하고 \du를 사용하여 모든 역할을 나열합니다.

# 기본 'postgres' 슈퍼유저로 연결
psql -U postgres -h your_host -d postgres

# 모든 역할(사용자) 나열
\du

# 누락된 역할 생성 예시
CREATE ROLE my_app_user WITH LOGIN PASSWORD 'my_strong_password';

오류 3: FATAL: password authentication failed for user "..."

이것은 지정된 사용자에 대한 암호가 잘못되었음을 나타내는 일반적인 오류입니다.

설명: 클라이언트에서 제공한 암호가 PostgreSQL 사용자(역할)에 대해 저장된 암호와 일치하지 않습니다.

솔루션:
1. 애플리케이션 구성 확인: 애플리케이션의 연결 문자열 또는 환경 변수를 검토하여 암호가 올바른지 확인합니다.
2. 암호 재설정(슈퍼유저 액세스 권한이 있는 경우): 

```bash
# postgres 슈퍼유저로 연결
psql -U postgres -h your_host -d postgres

# 문제 사용자 암호 변경
ALTER USER my_app_user WITH PASSWORD 'new_strong_password';
```

**팁:** `pg_hba.conf` 항목이 암호 기반 인증 방법(예: `md5`, `scram-sha-256`)을 지정하고 암호를 사용하려는 경우 `trust` 또는 `ident`가 아닌지 확인합니다.

오류 4: FATAL: no pg_hba.conf entry for host "...", user "...", database "...", SSL off/on

이 오류는 pg_hba.conf 구성 문제이며, 서버가 액세스 규칙을 기반으로 연결을 명시적으로 거부했음을 의미합니다.

설명: pg_hba.conf 파일에 들어오는 연결의 매개변수(클라이언트 IP, 사용자, 데이터베이스 및 인증 방법)와 일치하는 규칙이 포함되어 있지 않습니다.

솔루션:
1. pg_hba.conf 찾기: 위치는 OS 및 설치 방법에 따라 다릅니다(예: Debian/Ubuntu의 /etc/postgresql/14/main/pg_hba.conf 또는 psql의 SHOW hba_file;에 의해 지정됨).
2. pg_hba.conf 편집: 연결을 허용하는 항목을 추가하거나 수정합니다. 암호 인증으로 어디서든 연결을 허용하는 일반적인 항목은 다음과 같습니다.

```ini
# TYPE  DATABASE        USER            ADDRESS                 METHOD
host    all             all             0.0.0.0/0               md5
```
*   `TYPE`: TCP/IP 연결의 경우 `host`.
*   `DATABASE`: `all` (또는 특정 데이터베이스 이름).
*   `USER`: `all` (또는 특정 사용자 이름).
*   `ADDRESS`: 클라이언트의 IP 주소 범위(예: 로컬의 경우 `192.168.1.0/24`, `127.0.0.1/32`, 모든 IPv4 주소의 경우 `0.0.0.0/0`).
*   `METHOD`: 인증 방법(예: `md5`, `scram-sha-256`, `trust`, `ident`). `md5`는 암호 인증에 일반적입니다.

**경고:** 방화벽으로 보호되지 않은 경우 `md5`와 함께 `0.0.0.0/0`을 사용하면 보안 위험이 될 수 있습니다. 가능한 경우 항상 알려진 IP로 `ADDRESS`를 제한하십시오.

  1. PostgreSQL 다시 로드: pg_hba.conf를 편집한 후 변경 사항을 적용하려면 PostgreSQL 구성을 다시 로드해야 합니다.

    ```bash

    systemd 기반 시스템

    sudo systemctl reload postgresql

    또는 pg_ctl 사용(데이터 디렉터리 지정 필요)

    pg_ctl reload -D /var/lib/postgresql/14/main

    ```

오류 5: could not connect to server: Connection refused (0x0000274D/10061)

이것은 클라이언트가 PostgreSQL 서버에 연결을 설정할 수 없음을 나타내는 일반적인 오류입니다. 서버는 종종 대상 IP/포트에서 아무것도 수신 대기하지 않기 때문에 연결 시도를 적극적으로 거부했습니다.

설명: 일반적으로 다음 중 하나를 가리킵니다.
* PostgreSQL 서비스가 실행 중이지 않습니다.
* PostgreSQL이 예상 네트워크 인터페이스 또는 포트에서 수신 대기하고 있지 않습니다.
* 방화벽이 연결을 차단하고 있습니다.

솔루션:

  1. PostgreSQL 실행 중입니까?

    • 서비스 상태 확인:
      bash sudo systemctl status postgresql # 또는 이전 시스템/기타 설정의 경우: # sudo service postgresql status
      실행 중이 아닌 경우 시작합니다:
      bash sudo systemctl start postgresql
    • 로그 확인: 시작 오류에 대해 PostgreSQL 로그(예: /var/log/postgresql/)를 검토합니다.

  2. 올바른 주소/포트에서 수신 대기 중입니까?

    • postgresql.conf 확인: listen_addresses가 올바르게 구성되었는지 확인합니다. 다른 호스트에서의 연결의 경우 localhost(127.0.0.1)뿐만 아니라 * 또는 서버 네트워크 인터페이스의 특정 IP 주소여야 합니다.
      ini # postgresql.conf에서 listen_addresses = '*' # 사용 가능한 모든 네트워크 인터페이스에서 수신 대기 port = 5432 # 기본 포트
      listen_addresses를 변경한 후에는 PostgreSQL을 다시 시작해야 합니다(다시 로드는 충분하지 않음).
      bash sudo systemctl restart postgresql
    • 수신 포트 확인: netstat 또는 ss를 사용하여 PostgreSQL이 실제로 포트 5432(또는 구성된 포트)에서 수신 대기 중인지 확인합니다.
      bash sudo netstat -tulnp | grep 5432 # 예상 출력 예시: # tcp 0 0 0.0.0.0:5432 0.0.0.0:* LISTEN 12345/postgres
      0.0.0.0:5432 또는 your_server_ip:5432가 보이지 않으면 PostgreSQL은 127.0.0.1:5432에서만 수신 대기하거나 전혀 수신 대기하지 않을 가능성이 높습니다.

  3. 방화벽이 연결을 차단하고 있습니까?

    • 서버 측 방화벽: 클라이언트 IP 주소에서 들어오는 연결에 대해 포트 5432가 열려 있는지 확인하기 위해 ufw(Ubuntu/Debian), firewalld(CentOS/RHEL) 또는 iptables를 확인합니다.
      ```bash
      # UFW 예시
      sudo ufw allow 5432/tcp
      sudo ufw enable
      sudo ufw status

      firewalld 예시

      sudo firewall-cmd --permanent --add-port=5432/tcp
      sudo firewall-cmd --reload
      sudo firewall-cmd --list-ports
      ```
      * 클라이언트 측 방화벽: 덜 일반적이지만 클라이언트의 방화벽이 서버로 나가는 포트 5432 연결을 차단하지 않는지 확인합니다.

오류 6: timeout expired 또는 connection timed out

이 오류는 클라이언트가 연결을 시도했지만 지정된 시간 내에 서버로부터 응답을 받지 못했음을 시사합니다.

설명: Connection refused와 달리 능동적인 거부는 타임아웃이 연결 시도가 서버에 도달하지 못했거나 서버가 응답하지 않았음을 의미합니다. 종종 네트워크 연결 문제 또는 심각하게 과부하된 서버를 가리킵니다.

솔루션:
1. 네트워크 연결:
* 서버 ping: ping server_ip_address. ping이 실패하면 기본적인 네트워크 문제(케이블, 라우터, 서버 오프라인)가 발생합니다.
* Traceroute/MTR: traceroute server_ip_address(Linux/macOS) 또는 tracert server_ip_address(Windows)는 네트워크 경로를 따라 연결이 실패하는 위치를 식별하는 데 도움이 될 수 있습니다.
2. 서버 listen_addresses 및 방화벽: 오류 5의 해결 방법을 다시 확인하십시오. 잘못 구성된 listen_addresses 또는 방화벽도 서버에 도달할 수 없는 경우 타임아웃을 유발할 수 있습니다.
3. 서버 부하: 서버에 과도한 부하(높은 CPU, 낮은 메모리, 과도한 디스크 I/O)가 걸리면 새 연결을 신속하게 수락하기에 너무 바빠서 타임아웃이 발생할 수 있습니다. 시스템 리소스 사용량을 확인합니다.

일반적인 문제 해결 단계

지속적인 연결 문제가 발생하는 경우 체계적인 진단을 위해 다음 일반 단계를 따르십시오.

  1. PostgreSQL 로그 확인: 로그 파일이 가장 유용합니다. 시작 문제, 오류 및 거부된 연결 시도에 대한 자세한 정보를 포함합니다. 위치는 일반적으로 postgresql.conf의 log_directory(예: Debian/Ubuntu의 /var/log/postgresql/ 또는 데이터 디렉터리 내의 pg_log)에 지정됩니다.

    ```bash

    최근 로그 확인 예시

    sudo tail -f /var/log/postgresql/postgresql-14-main.log
    ```

  2. 구성 파일 확인: postgresql.conf 및 pg_hba.conf에서 구문 오류, 오타 또는 잘못된 값을 다시 확인합니다. 문자 하나만 잘못 배치되어도 서버가 시작되지 않거나 연결을 수락하지 못할 수 있습니다.

  3. PostgreSQL 다시 시작(구성 변경에 대한 마지막 수단): pg_hba.conf 및 일부 postgresql.conf 매개변수의 경우 reload가 종종 충분하지만 listen_addresses와 같은 특정 중요한 변경 사항에는 전체 재시작이 필요합니다.

    bash sudo systemctl restart postgresql

  4. 서버에서 로컬 테스트: 원격 머신에서 연결하는 데 실패하면 서버 자체에서 직접 연결해 보십시오. 이렇게 하면 문제가 서버 측인지 네트워크 관련인지 확인할 수 있습니다.

    ```bash

    Unix 도메인 소켓 사용(사용 가능한 경우)으로 연결

    psql -U your_username -d your_database

    또는 TCP/IP를 통해 로컬호스트에 연결

    psql -U your_username -h 127.0.0.1 -p 5432 -d your_database
    `` 로컬 연결이 작동하지만 원격 연결이 작동하지 않으면 문제는listen_addresses,pg_hba.conf` 또는 방화벽일 가능성이 높습니다.

  5. 클라이언트 구성 확인: 애플리케이션의 연결 문자열(예: PGHOST, PGPORT, PGUSER, PGPASSWORD, PGDATABASE 환경 변수 또는 libpq 연결 문자열)이 서버 설정과 일치하도록 올바르게 구성되었는지 확인합니다.

팁 및 모범 사례

  • 최소 권한 원칙: 일반 애플리케이션 연결에 postgres 슈퍼유저를 사용하지 마십시오. 필요한 권한만 있는 특정 역할을 만듭니다.
  • 강력한 암호: 항상 데이터베이스 역할에 대해 강력하고 고유한 암호를 사용하십시오.
  • pg_hba.conf 제한: 0.0.0.0/0 대신 pg_hba.conf에 정확한 클라이언트 IP 주소 또는 좁은 CIDR 범위를 지정하여 보안을 강화합니다.
  • 로그 정기 모니터링: PostgreSQL 로그를 검토하는 일과를 설정합니다. 로그 항목을 관찰하여 많은 문제를 조기에 발견할 수 있습니다.
  • 구성 문서화: postgresql.conf 및 pg_hba.conf 설정에 대한 명확한 기록을 유지합니다. 특히 프로덕션 환경의 경우.

결론

PostgreSQL 연결 오류 문제 해결은 부담스러워 보일 수 있지만, 체계적인 접근 방식을 채택하면 대부분의 문제를 신속하게 파악하고 해결할 수 있습니다. 먼저 기본 사항을 확인하십시오. 서비스가 실행 중입니까? 올바른 주소와 포트에서 수신 대기 중입니까? pg_hba.conf가 연결을 허용합니까? 자격 증명이 올바릅니까?

PostgreSQL의 상세한 로깅을 활용하고 핵심 구성 파일의 역할을 이해함으로써 데이터베이스의 가용성과 보안을 유지하기 위한 강력한 도구를 얻게 됩니다. 이러한 문제 해결 기술을 일관되게 적용하면 즉각적인 문제를 해결할 뿐만 아니라 PostgreSQL의 작동 미묘함에 대한 전반적인 이해를 향상시켜 보다 탄력적이고 안정적인 데이터베이스 배포를 이끌어낼 수 있습니다.