pgpool）の原因と対処

kengine / kompira コンテナのログに記録されるデータベース接続エラーから、原因と対処を調べます。データベースの構成（ローカル postgres コンテナ／外部 DB／pgpool）によって発生するエラーと対処が異なります。

構成とデータベースの対応:

標準シングル構成: postgres はローカルのコンテナ（ke2-postgres-1）

外部DBシングル構成 / Swarmクラスタ構成: postgres は外部に配置（クラスタは pgpool 経由、既定ポート 9999）

DB 接続数の上限超過（FATAL: sorry, too many clients already）による 500 エラーは、接続エラーではなくチューニングの問題です。データベース接続数の上限超過を参照してください。

観測される症状・影響

データベースに接続できないため、システム全体が影響を受けます（ブラウザ操作・REST-API の応答不可、ジョブフローの停止）。

影響範囲: postgres の役割と影響範囲
症状から探す: コンテナが停止している（postgres）

ローカル DB 停止（nc: bad address 'postgres'）

対象構成: 標準シングル構成（ローカル postgres コンテナ）

主なエラーメッセージ

psycopg2.OperationalError: could not translate host name "postgres" to address: Name does not resolve
nc: bad address 'postgres'

ログのサンプルエントリ

psycopg2.OperationalError: could not translate host name "postgres" to address: Name does not resolve
nc: bad address 'postgres'
nc: bad address 'postgres'
nc: bad address 'postgres'

原因

postgres コンテナが停止している可能性があります。

解決策

以下のコマンドで postgres コンテナのステータスを確認してください。

$ docker ps -a -f name=postgres

CONTAINER ID   IMAGE                                                  COMMAND                  CREATED          STATUS                      PORTS     NAMES
35f1ae144b49   registry.hub.docker.com/library/postgres:16.3-alpine   "docker-entrypoint.s…"   16 minutes ago   Exited (1) 12 seconds ago             ke2-postgres-1

ステータスが Up の場合はコンテナとしては起動しているため、コンテナ停止以外の問題が起きていると考えられます。ホストサーバや docker サービス、ネットワークなどの状態を確認してみてください。

ステータスが Up 以外の場合は、停止しているコンテナの最新の ID を指定して再起動してください。

$ docker restart <POSTGRES_CONTAINER_ID>

KE2 APP が正常に戻らない場合は、docker サービスを再起動してみてください。

$ systemctl restart docker.service

解決しない場合

問い合わせ前に情報を収集のうえ、サポートへお問い合わせください。

外部 DB へ到達不可（Host is unreachable）

対象構成: 外部DBシングル構成・Swarmクラスタ構成

観測される症状・影響

KE2 APP と外部データベースサーバ間でネットワーク接続の問題が発生しています。

主なエラーメッセージ

psycopg2.OperationalError: connection to server at "<DB_IP>", port <DB_PORT> failed: Host is unreachable

ログのサンプルエントリ

psycopg2.OperationalError: connection to server at "10.20.47.20", port 5432 failed: Host is unreachable
	Is the server running on that host and accepting TCP/IP connections?

上記サンプルのポート 5432 は外部 DB へ直接接続する構成での PostgreSQL 既定値です。pgpool／クラスタ経由で接続する構成では既定 9999 になるなど、構成により異なります。

原因

KE2 APP から外部 DB ホストサーバへ ping しても応答がない状況で発生します。

解決策

以下を確認してください。

外部 DB ホストサーバの正常性
外部 DB ホストサーバのネットワークインターフェイスの状態
外部 DB ホストサーバの Network 設定

あわせて KE2 APP ホストサーバと外部データベース間のネットワーク導通の確認を実施してください。

外部 DB ホストサーバやネットワークなどの保守手順については、本マニュアルの範囲外になります。

pgpool ノード間の不整合（unable to read message kind）

対象構成: 外部DBシングル構成・Swarmクラスタ構成（pgpool 利用時）

主なエラーメッセージ

ERROR: unable to read message kind / DETAIL: kind does not match between main(4e) slot[1] (53)

ログのサンプルエントリ

Reconnecting to the database didn't help connection to server at "10.20.47.20", port 9999 failed: ERROR:  unable to read message kind
DETAIL:  kind does not match between main(4e) slot[1] (53)

psycopg2.OperationalError: connection to server at "10.20.47.20", port 9999 failed: ERROR:  unable to read message kind
DETAIL:  kind does not match between main(4e) slot[1] (53)

原因

DB クラスタ（pgpool）利用時に、DB ノード間のネットワーク遅延や DB サーバのリソース使用率が高い場合、ノード間でデータの同期が取れず発生することがあります。

pgpool ノード間の通信問題: ネットワークの問題により pgpool ノード間で適切な調整ができず、ノード間でデータの同期が取れない。
pgpool ノードのリソース使用率が高い: pgpool VM で CPU・メモリ・I/O の使用率が高いと、データベース操作が遅くなりノード間で同期が取れない。

解決策

KE2 APP ホストサーバと外部データベース間のネットワーク導通の確認（pgpool ノード間のネットワーク遅延確認を含む）を実施してください。

外部 DB ホストサーバやネットワークなどの保守手順については、本マニュアルの範囲外になります。

読み取り専用トランザクション（cannot execute UPDATE in a read-only transaction）

対象構成: 外部DBシングル構成・Swarmクラスタ構成

主なエラーメッセージ

database error: cannot execute UPDATE in a read-only transaction

ログのサンプルエントリ

ERROR: Failed to start due to database error: cannot execute UPDATE in a read-only transaction

原因

データベースの不整合、または DB クラスタ（pgpool）がフェイルオーバーを実行し、アプリケーションが依然として古いプライマリノード（現在は読み取り専用モード）に接続されている可能性があります。

解決策

外部 DB 操作を確認してください（外部データベースへのアクセス確認の「DB 操作の確認」）。問題があれば外部 DB 管理者に連絡してください。
外部 DB 操作に問題がなければ、KE2 APP 側での DB 接続セッションの問題の可能性があります。kengine を再起動してください。

外部DBシングル構成
```
# kengine コンテナ ID: $ docker ps -a -f name=kengine で取得できます
$ docker restart <KENGINE_CONTAINER_ID>
```
Swarmクラスタ構成
```
$ docker service update --force $(docker service ls | grep kengine | awk '{print $2}')
```

解決しない場合

docker サービスを再起動してください（systemctl restart docker.service）。それでも回復しない場合は問い合わせ前に情報を収集のうえ、サポートへお問い合わせください。

外部 DB が停止（Connection refused）

対象構成: 外部DBシングル構成・Swarmクラスタ構成

主なエラーメッセージ

connection to server at "<DB_IP>", port <DB_PORT> failed: Connection refused

ログのサンプルエントリ

Reconnecting to the database didn't help connection to server at "10.20.47.20", port 5432 failed: Connection refused
	Is the server running on that host and accepting TCP/IP connections?

上記サンプルのポート 5432 は外部 DB へ直接接続する構成での PostgreSQL 既定値です。pgpool／クラスタ経由で接続する構成では既定 9999 になるなど、構成により異なります。

原因

データベースが停止してしまった場合に発生します。

解決策

外部データベースへのアクセス確認を確認してみてください。

外部 DB の保守手順については、本マニュアルの範囲外になります。

Kompira Enterprise 2.0 管理者マニュアル