From dbcacd4b3472e27aae05097fd0ac6b4340dec973 Mon Sep 17 00:00:00 2001
From: Taiki Koshino <koshino@sraoss.co.jp>
Date: Mon, 26 Jan 2026 15:57:15 +0900
Subject: [PATCH] Add detail log about mismatch between backend_hostname and
 primary_conninfo host.

---
 doc.ja/src/sgml/connection-settings.sgml | 10 ++++++++++
 doc/src/sgml/connection-settings.sgml    | 19 +++++++++++++++++++
 src/main/pgpool_main.c                   |  4 +++-
 3 files changed, 32 insertions(+), 1 deletion(-)

diff --git a/doc.ja/src/sgml/connection-settings.sgml b/doc.ja/src/sgml/connection-settings.sgml
index d70788340..7f0dd32a8 100644
--- a/doc.ja/src/sgml/connection-settings.sgml
+++ b/doc.ja/src/sgml/connection-settings.sgml
@@ -1743,6 +1743,16 @@ backend_clustering_mode = raw
       この場合は、稼働中かつDBノードIDがもっとも若いものが新しいメインノードになります。
      </para>
 
+     <para>
+      レプリケーション構成において、スタンバイ側が参照する<literal>primary_conninfo</literal>の<literal>host</literal>と、<productname>Pgpool-II</productname>がプライマリノードを識別する<varname>backend_hostname</varname>は同じ値を指定する必要があります。
+      たとえば、プライマリノードがbackend0（ホスト名<literal>host0</literal>）、スタンバイノードがbackend1で<varname>backend_application_name</varname>が<literal>server1</literal>の場合、backend1の<filename>postgresql.conf</filename>は次のように設定します。
+      <programlisting>
+primary_conninfo = 'host=host0 port=5432 user=postgres application_name=''server1'''
+      </programlisting>
+      この場合、backend0に対応する<varname>backend_hostname</varname>も<literal>host0</literal>に設定してください。
+      一致していない場合<productname>Pgpool-II</productname>がプライマリノードを識別できずストリーミングレプリケーションチェックなどがうまく動作しないことがあります。
+     </para>
+
      <para>
       <!--
       Please note that the DB node which has id 0 has no special
diff --git a/doc/src/sgml/connection-settings.sgml b/doc/src/sgml/connection-settings.sgml
index 97eafa0fb..1aa2e1034 100644
--- a/doc/src/sgml/connection-settings.sgml
+++ b/doc/src/sgml/connection-settings.sgml
@@ -1283,6 +1283,25 @@ backend_clustering_mode = raw
 	 for more details.
      </para>
 
+     <para>
+      In a replication configuration, the <literal>host</literal> specified in
+      <literal>primary_conninfo</literal> on the standby side must match the value of
+      <varname>backend_hostname</varname> that <productname>Pgpool-II</productname> uses
+      to identify the primary node.
+      For example, if the primary node is backend0 (with hostname <literal>host0</literal>)
+      and the standby node is backend1 with <varname>backend_application_name</varname>
+      set to <literal>server1</literal>, then the <filename>postgresql.conf</filename>
+      on backend1 should be configured as follows:
+      <programlisting>
+primary_conninfo = 'host=host0 port=5432 user=postgres application_name=''server1'''
+      </programlisting>
+      In this case, <varname>backend_hostname</varname> corresponding to backend0
+      should also be set to <literal>host0</literal>.
+      If these values do not match, <productname>Pgpool-II</productname> may fail to
+      identify the primary node correctly, and features such as streaming replication
+      checks may not work as expected.
+     </para>
+
      <para>
       If you plan to use only
       one <productname>PostgreSQL</productname> server, specify
diff --git a/src/main/pgpool_main.c b/src/main/pgpool_main.c
index 98fba4b2b..fa05e15e7 100644
--- a/src/main/pgpool_main.c
+++ b/src/main/pgpool_main.c
@@ -2699,7 +2699,9 @@ verify_backend_node_status(POOL_CONNECTION_POOL_SLOT **slots)
 						{
 							/* the standby does not connect to the primary */
 							ereport(LOG,
-									(errmsg("verify_backend_node_status: primary %d does not connect to standby %d", i, j)));
+									(errmsg("verify_backend_node_status: primary %d does not connect to standby %d", i, j),
+									 errdetail("pgpool.conf backend: (host=\"%s\" port=%d) does not match PostgreSQL primary_conninfo: (host=\"%s\" port=%s)",
+											   backend_info->backend_hostname, backend_info->backend_port, host, port)));
 						}
 					}
 				}
-- 
2.39.5