開始前に

以下が必要です。

• 管理者パスワードの設定 を使用した Databases for PostgreSQL の展開。
• UI、CLI、またはAPIで作成された、アプリケーション用のデータベースユーザー。
• PgBouncer 1.11.0 SCRAM認証に対応した、バージョンまたはそれ以降のものが、ご自身が管理するインフラストラクチャにインストールされていること。 トランザクション・プーリング・モードでプロトコルレベルのプリペアード・ステートメントを使用する場合は、 PgBouncer （ 1.21.0 以降）を使用してください。
• psql のクライアント。
• お客様のデプロイメント接続情報：
  • [接続文字列]から取得したホスト名とポート番号...
  • CA証明書（ ibmcloud cdb deployment-cacert で取得）。

pgbouncer_lookup のサポートは、各導入環境において順次展開されています。 デプロイメントにこの機能が実装されていることを確認するには、 admin として psql に接続し、 \df public.pgbouncer_lookup を実行してください。 結果が空の場合、次のメンテナンス更新時に、デプロイメントにその関数が適用されます。

専用の認証ユーザーを作成する

PgBouncer auth_query を1つの指定されたログインロールとして実行する場合、そのロールは となります。 auth_user この目的のみに使用するロールを作成してください。 データを一切所有せず、他の何も実行しない専用の役割こそが、最小権限の原則に基づく最適な選択肢です。

「 admin 」ユーザーとして psql に接続し、ロールを作成して、そのロールに「 pgbouncer_auth 」を付与します：

CREATE ROLE pool_auth WITH LOGIN PASSWORD '<POOL_AUTH_PASSWORD>';
GRANT pgbouncer_auth TO pool_auth;

pgbouncer_auth ロールには、 pgbouncer_lookup 関数を実行する権限という、1つの権限のみが付与されています。 admin ユーザーは、admin オプション付きの pgbouncer_auth を保持しているため、メンバーシップの付与や取り消しはご自身で行ってください。 サービス認証情報に表示させたい場合は、 ibmcloud cdb user-create を使用してユーザーを作成することもできますが、 この方法で作成されたユーザーは ibm-cloud-base-user のメンバーとなり、ユーザーやデータベースを作成できるようになります。これは、認証用ユーザーに必要な権限の範囲を超えています。

pgbouncer_auth の権限は、専用の認証ユーザーのみに付与してください。 このロールのメンバーであれば誰でも、他のデータベースユーザーの保存済みパスワード検証情報を閲覧できるため、メンバーが増えるたびに、認証情報が漏洩した場合の影響範囲が拡大することになります。

認証ユーザーを無効にするには、そのメンバーシップを取り消します：

REVOKE pgbouncer_auth FROM pool_auth;

設定 PgBouncer

Databases for PostgreSQL の展開環境に接続するには、 PgBouncer で以下の設定が必要です：

• auth_type = scram-sha-256, なぜなら、デプロイメントには SCRAM-SHA-256 のパスワード検証情報が保存されているからです。
• auth_query = SELECT * FROM public.pgbouncer_lookup($1), なぜなら、 PgBouncer's のデフォルト設定である auth_query は、 pg_authid を直接読み込むようになっており、データベースユーザーにはそのファイルを読み取る権限がないからです。
• サーバー側の TLS。デプロイ先では TLS 接続のみを受け付けるためです。 server_tls_sslmode = verify-full を設定し、 ibmcloud cdb deployment-cacert で取得した証明書を、 server_tls_ca_file で設定したパスに保存してください。

PgBouncer 自身の auth_user の認証情報を auth_file から読み込むため、この設定では、 userlist.txt にはauth_userの認証情報のみが含まれます。 他のすべてのユーザーは、 auth_query を経由して解決されます。 ファイルのアクセス権を、 PgBouncer プロセスの所有者に限定します。たとえば、モードを 0600 に設定します。

"pool_auth" "<POOL_AUTH_PASSWORD>"

<HOSTNAME> および <PORT> が 接続文字列 から取得される、完全な最小構成です：

[databases]
ibmclouddb = host=<HOSTNAME> port=<PORT> dbname=ibmclouddb
[pgbouncer]
listen_addr = 127.0.0.1
listen_port = 6432
auth_type = scram-sha-256
auth_file = /etc/pgbouncer/userlist.txt
auth_user = pool_auth
auth_query = SELECT * FROM public.pgbouncer_lookup($1)
server_tls_sslmode = verify-full
server_tls_ca_file = /etc/pgbouncer/ca-certificate.crt
pool_mode = session
max_client_conn = 200
default_pool_size = 20

auth_dbname = postgres を設定しないでください。 postgres データベースには、LOOKUP関数がインストールされていません。 auth_dbname を未設定のままにしておくと、認証クエリはクライアントが接続するデータベースで実行されます。 今後作成するデータベースには、この機能が自動的に含まれます。

各設定の詳細については、『 PgBouncer 』の設定リファレンスを参照してください。

セットアップの検証

1. その検索によって、データベースユーザーのうちの1人が特定されることを確認してください。 psql に「 admin 」として接続し、次のコマンドを実行します：

   SELECT usename, passwd IS NOT NULL AS can_authenticate
     FROM public.pgbouncer_lookup('<APP_USERNAME>');
   

   その結果、 can_authenticate = t という1行が表示されます。 このクエリは、パスワード確認画面が表示されないように記述されています。 admin を含む、サービス専用ユーザーからは、行が返されません。

2. データベースユーザーとして、 PgBouncer 経由で接続します：

   psql "host=127.0.0.1 port=6432 dbname=ibmclouddb user=<APP_USERNAME>"
   

   接続に成功した場合、 PgBouncer は auth_query を通じてユーザーを正しく認証しています。

3. データベースユーザーのパスワードを変更し、新しいパスワードを使用して PgBouncer 経由で再接続してください：

   ibmcloud cdb user-password <DEPLOYMENT_NAME_OR_CRN> <APP_USERNAME> <NEW_PASSWORD>
   

   新しいパスワードはすぐに有効になります。 PgBouncer の再起動やリロード、あるいは userlist.txt の設定変更は必要ありません。

セキュリティモデルの仕組み

pgbouncer_lookup 関数は、 PgBouncer が認証を行うために必要な情報のみを提供します。

• この関数は、 SECURITY DEFINERsearch_path を固定した状態で実行され、 pg_catalog.pg_authid をユーザーに代わって読み込みます。 pg_authid および pg_shadow への直接アクセスは、引き続きブロックされたままです。
• ハッシュ化されたSCRAM検証情報を返すものであり、平文のパスワードが返されることは決してありません。
• ログインが許可されているロールのみが解決されます。 admin や、内部レプリケーションおよび運用ユーザーなどのサービス専用ユーザーは、決して解決されません。
• ロールの VALID UNTIL タイムスタンプが過去の日付である場合、この関数はNULLのパスワードを返すため、認証は失敗し、パスワードの有効期限が引き続き適用されます。
• PUBLIC に対する関数の実行権限は取り消され、 admin および pgbouncer_auth のメンバーにのみ付与されます。

PgBouncer's デフォルトでは、 auth_query は pg_authid を直接読み取りますが、データベースユーザーにはその権限がありません。 このような状況では、 PgBouncer のドキュメントでは、代わりにスーパーユーザー以外のユーザーを通じて SECURITY DEFINER 関数を呼び出すことを推奨しています。 pgbouncer_lookup 関数は、そのサービスの予約済みユーザーを除外した、その関数です。

制限事項および留意点

• PgBouncer デプロイメントの max_connections を発生させません。 すべての PgBouncer インスタンスからのサーバー接続の合計数が 接続制限 内に収まるよう、 default_pool_size のサイズを調整してください。 制限に達した場合は、「 最大接続数の増加 」を参照してください。
• admin のユーザーは、 auth_query 経由で認証を行うことができません。 管理作業を行う際は、 PgBouncer を経由せず、 admin としてデプロイメントに直接接続してください。
• postgres データベースにはルックアップ機能がないため、 auth_dbname = postgres を設定してはいけません。
• トランザクション・プーリング・モード（pool_mode = transaction ）では、 SET 変数、一時テーブル、アドバイザリ・ロック、 LISTEN チャネルなどのセッション状態は、トランザクション間で引き継がれません。 プロトコルレベルのプリペアードステートメントを使用するには、 max_prepared_statements および PgBouncer 1.21.0 以降が必要です。 詳細については、「 PgBouncer の機能 」をご覧ください。
• インプレースでのメジャーバージョンアップグレード 中は、デプロイメントが一時的に停止し、開いている接続は切断されます（SQLSTATE 57P01 ）。 PgBouncer サーバーへの接続は自動的に再確立されますが、アプリケーション側では中断されたトランザクションの再試行やステートメントの再準備を行う必要があります。
• 読み取り専用ユーザーは、プライマリエンドポイントに接続できません。 それぞれの接続を統合するには、 読み取り専用レプリカ を指す別の [databases] エントリを追加してください。

次のステップ

• 接続の管理
• 接続文字列の取得
• ユーザー、役割、および特権の管理
• PgBouncer 設定リファレンス