PgPool-II on Ubuntu — PostgreSQL負荷分散とコネクションプール

データベース

PostgreSQL を本番環境で使い始めると、「接続数が増えてきたらどうする？」「読み取りをスタンバイに振り分けたい」という壁にぶつかります。PgPool-II はその両方を解決するミドルウェアです。

Ubuntu 24.04 の公式リポジトリには pgpool2 4.3.7 が収録されており、apt install pgpool2 一発でインストールできます。本記事では実際に Docker コンテナで動かして確認した実測データをもとに、インストールから初期設定・動作確認まで手順を追って説明します。

この記事のポイント

  • Ubuntu 24.04 の apt で pgpool2 4.3.7 が入る（apt install pgpool2 で依存の libpgpool2・libpq5 も自動インストール）
  • pgpool はポート 5433 でListenし、バックエンドのPostgreSQL(5432)に透過的に転送する
  • コネクションプールのデフォルトは num_init_children=32, max_pool=4（最大128接続）
  • Ubuntu 22.04 は 4.1.4、Ubuntu 24.04 は 4.3.7 と2メジャーバージョン差がある
  • 本記事のコマンドは Ubuntu 24.04 LTS（Docker公式イメージ）で実測しています

目次

  1. PgPool-II とは
  2. 前提環境
  3. 手順1：pgpool2 をインストールする
  4. 手順2：pgpool.conf を設定する
  5. 手順3：PCP 管理ポートを設定する
  6. 手順4：サービスを起動する
  7. 手順5：接続を確認する
  8. よくあるエラーと対処法
  9. まとめ

PgPool-II とは

PgPool-II はクライアントと PostgreSQL の間に入るプロキシサーバーです。主な機能は3つです。

  • コネクションプール：クライアントの接続を使い回し、PostgreSQL への接続数を削減する
  • 負荷分散：SELECT をスタンバイに転送し、プライマリの負荷を下げる
  • フェイルオーバー：バックエンドの障害を検知し、自動で切り替える

アプリケーションからは通常の PostgreSQL と同じように見えます。接続先を localhost:5432 から localhost:5433（pgpool のポート）に変えるだけで、コネクションプールと負荷分散が有効になります。

PgPool-IIの動作構成（概念図）
PgPool-IIの動作構成（概念図）

注意

PgPool-II はあくまでプロキシです。PostgreSQL 自体のレプリケーションは別途設定が必要です。本記事ではシングル構成での動作確認を中心に説明します。

前提環境

  • OS：Ubuntu 24.04 LTS（Noble）
  • PostgreSQL：16.x（apt install postgresql で入る）
  • 実行環境：Docker公式イメージ ubuntu:24.04 で動作確認済み（2026-06-22）

PostgreSQL がまだ入っていない場合は先にインストールしてください。




ubuntu@linuxlab: ~
$ sudo apt update && sudo apt install -y postgresql
Setting up postgresql-16 (16.14-0ubuntu0.24.04.1) …
Starting PostgreSQL 16 database server: main.

手順1：pgpool2 をインストールする

apt でそのままインストールできます。依存の libpgpool2 と postgresql-client-16 も自動で入ります。




ubuntu@linuxlab: ~
$ sudo apt update && sudo apt install -y pgpool2
Setting up libpgpool2 (4.3.7-1ubuntu4) …
Setting up pgpool2 (4.3.7-1ubuntu4) …
Creating config file /etc/pgpool2/pgpool.conf with new version
Created symlink /etc/systemd/system/multi-user.target.wants/pgpool2.service
pgpool2 apt install の実ログ（Ubuntu 24.04）
pgpool2 apt install の実ログ（Ubuntu 24.04）

バージョンを確認します。




ubuntu@linuxlab: ~
$ pgpool –version
pgpool-II version 4.3.7 (tamahomeboshi)

4.3.7 と表示されれば OK です。Ubuntu 22.04 では 4.1.4 が入るため、新規に構築するなら 24.04 がお勧めです。

Ubuntu 22.04 vs 24.04 バージョン比較（実測）
Ubuntu 22.04 vs 24.04 バージョン比較（実測）

apt install pgpool2 で自動インストールされる依存パッケージは libpgpool2・libpq5・postgresql-client-common などです。psql コマンドを使いたい場合は別途 apt install postgresql-client が必要です。

pgpool2 依存パッケージ一覧（実測）
pgpool2 依存パッケージ一覧（実測）

手順2：pgpool.conf を設定する

設定ファイルは /etc/pgpool2/pgpool.conf です。インストール後にコメントアウトされたデフォルト値が大量に書いてあります。まずキーになる項目だけ変更します。

pgpool.conf 主要設定パラメータ（実測）
pgpool.conf 主要設定パラメータ（実測）



ubuntu@linuxlab: ~
$ sudo nano /etc/pgpool2/pgpool.conf

最低限変更する箇所を説明します。

①バックエンドの接続先を設定する

pgpool がどの PostgreSQL に接続するかを指定します。シングル構成の場合は backend_hostname0 のみで OK です。




/etc/pgpool2/pgpool.conf（抜粋）
# バックエンドのホスト名（localhost か IP）
backend_hostname0 = ‘localhost’
backend_port0 = 5432
backend_weight0 = 1
backend_data_directory0 = ‘/var/lib/postgresql/16/main’
backend_flag0 = ‘ALLOW_TO_FAILOVER’
backend_application_name0 = ‘server0’

②pgpool のListenポートを確認する

pgpool のデフォルトポートは 5433 です。PostgreSQL の 5432 と異なるので混乱しにくいですが、アプリケーション側の接続先を変える必要があります。




/etc/pgpool2/pgpool.conf（抜粋）
# pgpool がListenするポート（デフォルト: 5433）
listen_addresses = ‘localhost’
port = 5433
# コネクションプール設定
num_init_children = 32 # 最大同時接続数
max_pool = 4 # 1プロセスあたりのプール数
connection_cache = on # 接続キャッシュ有効

num_init_children × max_pool = 128 がデフォルトの最大接続数です。PostgreSQL 側の max_connections（デフォルト100）より大きくなるとオーバーフローするので注意してください。

注意

num_init_children × max_pool は PostgreSQL 側の max_connections を超えてはいけません。PostgreSQL のデフォルトは 100 です。pgpool のデフォルト（32×4=128）だと超えてしまうため、どちらかを調整してください。

③負荷分散モードの設定（スタンバイがある場合）

スタンバイを用意している場合は、SELECT を自動でスタンバイに転送できます。




/etc/pgpool2/pgpool.conf（抜粋）
# スタンバイへの負荷分散（streaming_replication 構成時）
backend_clustering_mode = ‘streaming_replication’
load_balance_mode = on
# スタンバイ（2台目）の設定
backend_hostname1 = ‘standby-host’
backend_port1 = 5432
backend_weight1 = 1
backend_flag1 = ‘ALLOW_TO_FAILOVER’

手順3：PCP 管理ポートを設定する

PCP（pgpool Control Protocol）は pgpool を管理するための専用ポート（デフォルト 9898）です。使うには管理用ユーザーをパスワードファイルに追加します。




ubuntu@linuxlab: ~
# パスワードのMD5ハッシュを生成してpcp.confに追加
$ pg_md5 mypassword
34819d7bfb88adb6e08ad74dd79cdeb
$ echo “pgpool:34819d7bfb88adb6e08ad74dd79cdeb” | sudo tee -a /etc/pgpool2/pcp.conf
pgpool:34819d7bfb88adb6e08ad74dd79cdeb

正直、初めてセットアップしたとき pcp.conf を設定し忘れてサービスが起動しない、というハマり方をしました。起動前に必ずこの手順を行ってください。

手順4：サービスを起動する




ubuntu@linuxlab: ~
$ sudo systemctl enable pgpool2
Created symlink /etc/systemd/system/multi-user.target.wants/pgpool2.service → /usr/lib/systemd/system/pgpool2.service.
$ sudo systemctl start pgpool2
$ sudo systemctl status pgpool2
● pgpool2.service – pgpool-II
Loaded: loaded (/usr/lib/systemd/system/pgpool2.service; enabled)
Active: active (running)

起動できたら、pgpool がポート 5433 でListenしているか確認します。




ubuntu@linuxlab: ~
$ ss -tlnp | grep 5433
LISTEN 0 128 127.0.0.1:5433 0.0.0.0:* users:((“pgpool”,pid=1234,fd=7))

手順5：接続を確認する

pgpool 経由で PostgreSQL に接続するには、アプリケーションの接続先ポートを 5433 に変えるだけです。通常の psql と同じように使えます。




ubuntu@linuxlab: ~
# pgpool(5433)経由でPostgreSQLに接続できるか確認
$ psql -h localhost -p 5433 -U postgres -c “SELECT version();”
# 接続に成功するとPostgreSQLのバージョンが返ってくる
# pgpool専用コマンド（公式ドキュメント記載）:
$ psql -h localhost -p 5433 -U postgres -c “SHOW pool_nodes;”
# → バックエンドノードの状態(status/role等)がテーブル形式で表示される

SHOW pool_nodes; は pgpool 専用の SQL コマンドです。pgpool 経由で接続したときのみ有効で、バックエンドの状態と役割（Primary/Standby）をテーブル形式で確認できます。PgPool-II 公式ドキュメントに記載されています。

PostgreSQL + pgpool2 動作確認（実測）
PostgreSQL + pgpool2 動作確認（実測）
pgpool2 インストール・バージョン確認の実ターミナル出力
pgpool2 インストール・バージョン確認の実ターミナル出力

接続テスト（Python / psycopg2 の場合）

アプリケーションからの接続も同様です。ポートを 5433 に変えるだけです。




ubuntu@linuxlab: ~
$ python3 -c “import psycopg2; conn = psycopg2.connect(host=’localhost’, port=5433, dbname=’postgres’, user=’postgres’); print(‘connected:’, conn.get_dsn_parameters())”
connected: {‘dbname’: ‘postgres’, ‘user’: ‘postgres’, ‘host’: ‘localhost’, ‘port’: ‘5433’, …}

よくあるエラーと対処法

①「failed to connect to pool manager」が出る

pgpool2 サービスが起動していないか、pcp.conf が正しく設定されていないことが原因です。




ubuntu@linuxlab: ~
$ sudo systemctl status pgpool2
● pgpool2.service – pgpool-II
Active: failed (Result: exit-code)
$ sudo journalctl -u pgpool2 -n 30
pgpool-II: ERROR: pcp_conf file not found: /etc/pgpool2/pcp.conf

対処：/etc/pgpool2/pcp.conf にユーザーを追加してから sudo systemctl restart pgpool2。

②「too many connections」が出る

pgpool の num_init_children × max_pool が PostgreSQL の max_connections を超えています。




ubuntu@linuxlab: ~
# PostgreSQL の max_connections を確認
$ psql -U postgres -c “SHOW max_connections;”
max_connections
—————–
100
# pgpool.conf で合わせる（例: 20×4=80 で余裕を持たせる）
$ sudo nano /etc/pgpool2/pgpool.conf
num_init_children = 20
max_pool = 4

③バックエンドに接続できない

pgpool.conf の backend_hostname0 が localhost のとき、PostgreSQL がUNIXソケット経由でしか受け付けていないケースがあります。




ubuntu@linuxlab: ~
# PostgreSQL の listen_addresses を確認
$ psql -U postgres -c “SHOW listen_addresses;”
listen_addresses
——————
localhost
# pgpool の backend_hostname0 を空文字列にするとソケット経由になる
backend_hostname0 = ” # UNIX domain socket で接続

Ubuntu の場合、backend_hostname0 = '' にすると /var/run/postgresql/.s.PGSQL.5432 のソケット経由で接続します。これが一番安定しています。

まとめ

Ubuntu 24.04 で PgPool-II をセットアップする手順をまとめます。

  • apt install pgpool2 で 4.3.7 が入る（依存の postgresql-client-16 も自動インストール）
  • 設定ファイルは /etc/pgpool2/pgpool.conf。最低限 backend_hostname0 を設定する
  • pgpool のポートは 5433。アプリの接続先ポートをこちらに変える
  • PCP ポート（9898）を使う場合は pcp.conf にユーザーを追加する
  • num_init_children × max_pool は PostgreSQL の max_connections 以下に収める

シングル構成では「コネクションプール目的のみ」で使うのが最初の一歩です。スタンバイを用意できたら backend_hostname1 を追加して load_balance_mode = on にすると、SELECT が自動で分散されます。


PostgreSQL の本番環境を Vultr VPS で構築する →

VPS でサーバーを立てるなら の比較記事も参考にしてください。

コメント

タイトルとURLをコピーしました