DevOpsナレッジハブ
DevOpsナレッジハブ

よくあるPostgreSQL接続エラーのトラブルシューティング

PostgreSQLの接続問題に直面していますか？この記事では、認証失敗、ネットワーク拒否、サービス停止など、よくあるエラーをトラブルシューティングするための包括的なガイドを提供します。`pg_hba.conf`の競合、誤った認証情報、サーバーの応答がない状態を診断する方法を学びましょう。実用的な手順、コマンドラインの例、およびベストプラクティスにより、接続問題を迅速に解決し、PostgreSQLデータベースが常にアクセス可能で安全であることを保証するための知識が得られます。

53 ビュー

PostgreSQL 接続エラーの一般的なトラブルシューティング

PostgreSQL はその堅牢性と信頼性で知られていますが、あらゆる複雑なシステムと同様に、アプリケーションやユーザーがデータベースにアクセスできなくなる接続問題が発生する可能性があります。これらのエラーは、認証情報の誤り、ネットワーク設定の不備、データベースサービスが非アクティブであるなど、さまざまな原因から発生する可能性があります。could not connect to server（サーバーに接続できませんでした）や password authentication failed（パスワード認証に失敗しました）というメッセージに直面すると、特にデータへの迅速なアクセスが必要な場合に、イライラする可能性があります。

この包括的なガイドは、一般的な PostgreSQL 接続エラーを解明し、明確で実行可能な解決策を提供することを目的としています。認証の失敗、ネットワーク構成の問題、サービスが利用できない状態など、これらの問題の一般的な原因を探り、体系的なトラブルシューティングの手順を説明します。根本的な原因を理解し、ここで概説されている実践的な解決策を適用することで、ほとんどの接続問題を診断および解決できるようになり、PostgreSQL データベースがアクセス可能で運用可能な状態を維持できるようになります。

PostgreSQL 接続の基本を理解する

特定のエラーの詳細に入る前に、PostgreSQL が接続をどのように処理するかを理解することが重要です。PostgreSQL はクライアント・サーバーモデルで動作します。クライアント（例：psql コマンドラインツール、Web アプリケーション、デスクトップクライアント）は PostgreSQL サーバープロセスへの接続を試みます。このプロセスは通常、特定のネットワークインターフェイスとポート（デフォルトは 5432）で着信接続をリッスンしています。

接続の受け入れと認証を制御する 2 つの主要な設定ファイルがあります。

  • postgresql.conf: リッスンするネットワークインターフェイス（listen_addresses）やポート（port）など、一般的なサーバーの動作を制御します。
  • pg_hba.conf (Host-Based Authentication): どのユーザーが、どこから、どのデータベースに、どのような認証方法で接続できるかを決定します。このファイルはセキュリティとアクセス制御にとって非常に重要です。

これらのファイルの役割とクライアント・サーバーのやり取りを理解することは、効果的なトラブルシューティングの基本となります。

一般的な接続エラーとその解決策

発生する可能性のある最も頻繁な接続エラーとその解決策を分析してみましょう。

エラー 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';
```

**ヒント:** パスワードベースの認証方法（`md5`、`scram-sha-256` など）を使用する場合は、`pg_hba.conf` のエントリで `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` を使用すると、ファイアウォールで保護されていない場合、セキュリティリスクとなる可能性があります。可能な限り `ADDRESS` を既知の IP に制限してください。

  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. ファイアウォールが接続をブロックしているか？

    • サーバー側のファイアウォール: ufw (Ubuntu/Debian)、firewalld (CentOS/RHEL)、または iptables を確認し、ポート 5432 がクライアントの IP アドレスからの着信接続に対して開いていることを確認します。
      ```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 の構文エラー、タイポ、または間違った値がないか再確認します。1 文字のずれでも、サーバーの起動や接続の受け入れを妨げる可能性があります。

  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 を使用して localhost に接続

    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 接続エラーのトラブルシューティングは daunting に思えるかもしれませんが、体系的なアプローチを採用することで、ほとんどの問題を迅速に特定して解決できます。まず基本的なことを確認してください：サービスは実行されていますか？正しいアドレスとポートでリッスンしていますか？pg_hba.conf は接続を許可していますか？認証情報は正しいですか？

PostgreSQL の詳細なログと、そのコア設定ファイルの役割を理解することで、データベースのアクセス可能性とセキュリティを維持するための強力なツールが得られます。これらのトラブルシューティング技術を一貫して適用することで、即時の問題を解決するだけでなく、PostgreSQL の運用上のニュアンスについての全体的な理解も深まり、より回復力があり信頼性の高いデータベース展開につながります。