Feature: Make online recovery database configurable
authorBo Peng <pengbo@sraoss.co.jp>
Thu, 17 Jul 2025 05:31:02 +0000 (14:31 +0900)
committerBo Peng <pengbo@sraoss.co.jp>
Thu, 17 Jul 2025 05:31:02 +0000 (14:31 +0900)
Prior to version 4.6, the online recovery database was hardcoded to "template1".
This commit introduces a new configuration parameter, "recovery_database",
which allows users to specify the database used for online recovery.
The default value is "postgres".

15 files changed:
doc.ja/src/sgml/example-cluster.sgml
doc.ja/src/sgml/example-replication-si-mode.sgml
doc.ja/src/sgml/installation.sgml
doc.ja/src/sgml/online-recovery.sgml
doc/src/sgml/example-cluster.sgml
doc/src/sgml/example-replication-si-mode.sgml
doc/src/sgml/installation.sgml
doc/src/sgml/online-recovery.sgml
src/config/pool_config_variables.c
src/include/pool_config.h
src/pcp_con/recovery.c
src/sample/pgpool.conf.sample-stream
src/test/pgpool_setup.in
src/test/watchdog_setup.in
src/utils/pool_process_reporting.c

index a9fa531356d67f8ddaf12535ba96b95b7185ee3b..2950c59c56416184e647146d8bc980b3eb205d24 100644 (file)
@@ -813,7 +813,7 @@ PCP_USER=pgpool
   <sect3 id="example-cluster-pgpool-config-online-recovery">
    <title>オンラインリカバリの設定</title>
    <para>
-    続いて、オンラインリカバリを実行する<productname>PostgreSQL</productname>ユーザ及びオンラインリカバリ時に呼び出されるスクリプトを設定します。
+    続いて、オンラインリカバリ(<xref linkend="runtime-online-recovery">)を実行する<productname>PostgreSQL</productname>ユーザ及びオンラインリカバリ時に呼び出されるスクリプトを設定します。
     オンラインリカバリで実行される<function>pgpool_recovery</function>関数は
     <productname>PostgreSQL</productname>のスーパーユーザ権限が必要なため、<varname>recovery_user</varname>に<emphasis>スーパーユーザ</emphasis>を指定しなければなりません。
     ここでは、<literal>postgres</literal>ユーザを指定します。
@@ -852,12 +852,12 @@ PGHOME=/usr/pgsql-17
    </programlisting>
 
    <para>
-    また、オンラインリカバリ機能を使用するには、<function>pgpool_recovery</function>、
-    <function>pgpool_remote_start</function>、<function>pgpool_switch_xlog</function>という関数が必要になるので、
-    <literal>server1</literal>のtemplate1に<function>pgpool_recovery</function>をインストールしておきます
+    また、オンラインリカバリ機能を使用するには、<function>pgpool_recovery</function>、<function>pgpool_remote_start</function>、<function>pgpool_switch_xlog</function>の各関数をあらかじめ<xref linkend="guc-recovery-database">で指定されたデータベース(デフォルトは<literal>'postgres'</literal>です)に作成しておく必要があります。
+    <literal>server1</literal>上で以下のコマンドを実行し、これらの関数を<literal>postgres</literal>に作成します。
+    <xref linkend="guc-recovery-database">にデフォルト以外の値が設定されている場合は、<literal>postgres</literal>をその設定値に置き換えてください
    </para>
    <programlisting>
-[root@server1 ~]# psql -U postgres template1 -c "CREATE EXTENSION pgpool_recovery"
+[root@server1 ~]# psql -U postgres postgres -c "CREATE EXTENSION pgpool_recovery"
    </programlisting>
    <note>
     <para>
index 605a4427827c3ad3f3d55e760e734f1b17e2b4e0..2915ccbb8033db190e5bedcd8c9dcb02d8d3ad18 100644 (file)
@@ -567,13 +567,12 @@ PGHOME=/usr/pgsql-15
    </programlisting>
 
    <para>
-    また、オンラインリカバリ機能を使用するには、<function>pgpool_recovery</function>、
-    <function>pgpool_remote_start</function>、<function>pgpool_switch_xlog</function>という関数が必要になるので、
-    <literal>server1</literal>のtemplate1に<function>pgpool_recovery</function>をインストールしておきます
+    また、オンラインリカバリ機能を使用するには、<function>pgpool_recovery</function>、<function>pgpool_remote_start</function>、<function>pgpool_switch_xlog</function>の各関数をあらかじめ<xref linkend="guc-recovery-database">で指定されたデータベース(デフォルトは<literal>'postgres'</literal>です)に作成しておく必要があります。
+    <literal>server1</literal>上で以下のコマンドを実行し、これらの関数を<literal>postgres</literal>に作成します。
+    <xref linkend="guc-recovery-database">にデフォルト以外の値が設定されている場合は、<literal>postgres</literal>をその設定値に置き換えてください
    </para>
    <programlisting>
-[server1]# su - postgres
-[server1]$ psql template1 -c "CREATE EXTENSION pgpool_recovery"
+[server1]# psql -U postgres postgres -c "CREATE EXTENSION pgpool_recovery"
    </programlisting>
    <note>
     <para>
index 439f77ffef93e15f8a926c9f8d3c58b6e66c8af6..bc73e82ca0cb1698a9734c131e1083bcff880c42 100644 (file)
@@ -523,12 +523,9 @@ make install
    when you use the online recovery that describes latter.
    Also pgpoolAdmin of management tool, stop, restart or reload a
    <productname>PostgreSQL </productname> on the screen by use <function>pgpool_pgctl<function>.
-   It is enough, if these function installed in template1 first. These
-   function do not needed that install in all databases.
    -->
-   後述の オンラインリカバリ の機能を使う場合には、 pgpool_recovery, pgpool_remote_start, pgpool_switch_xlog という関数が必要です。
+   後述のオンラインリカバリの機能を使う場合には、 <function>pgpool_recovery</function>、<function>pgpool_remote_start</function>、および<function>pgpool_switch_xlog</function>という関数が必要です。
    また管理ツールである pgpoolAdmin の画面上から、バックエンドノードの PostgreSQL を停止・再起動・設定再読み込みを行なうことができますが、これには pgpool_pgctl という関数が使われます。
-   これらの関数は、すべてのデータベースにインストールされている必要はなく、template1 にだけで 構いません。
   </para>
 
   <para>
@@ -543,11 +540,19 @@ $ make
 $ make install
    </programlisting>
    <!--
-   After this:
+   After this, execute the following command to create the functions
+   <function>pgpool_recovery</function>, <function>pgpool_remote_start</function>
+   and <function>pgpool_switch_xlog</function> in the database specified in
+   <xref linkend="guc-recovery-database">
+   (The default is <literal>'postgres'</literal>).
+   If a value other than the default is configured for
+   <xref linkend="guc-recovery-database">, replace <literal>"postgres"</literal>
+   with the setting of <xref linkend="guc-recovery-database">.
    -->
-   この後に以下か、
+   この後、以下のコマンドを実行して、<xref linkend="guc-recovery-database">で指定されたデータベースに(デフォルトは<literal>'postgres'</literal>です)<function>pgpool_recovery</function>、<function>pgpool_remote_start</function>および<function>pgpool_switch_xlog</function>関数を作成します。
+   <xref linkend="guc-recovery-database">にデフォルト以外の値が設定されている場合は、<literal>"postgres"</literal>をその設定値に置き換えてください。
    <programlisting>
-$ psql template1
+$ psql postgres
 =# CREATE EXTENSION pgpool_recovery;
    </programlisting>
 
@@ -556,7 +561,7 @@ $ psql template1
    -->
    または
    <programlisting>
-$ psql -f pgpool-recovery.sql template1
+$ psql -f pgpool-recovery.sql postgres
    </programlisting>
    を実行します。
 
index aa0617b1bccc2a2a2cc3176ea2cc0456ae9bd860..8b895dad093e2ec8a47f53cc63dc0d81875589c6 100644 (file)
    </listitem>
   </varlistentry>
 
+  <varlistentry id="guc-recovery-database" xreflabel="recovery_database">
+   <term><varname>recovery_database</varname> (<type>string</type>)
+    <indexterm>
+     <!--
+     <primary><varname>recovery_database</varname> configuration parameter</primary>
+     -->
+     <primary><varname>recovery_database</varname> 設定パラメータ</primary>
+    </indexterm>
+   </term>
+   <listitem>
+    <para>
+     <!--
+     Specifies the PostgreSQL database name to be used for online recovery.
+     The default is <literal>'postgres'</literal>. If not specified,
+     <productname>Pgpool-II</productname> will attempt to use the
+     <literal>"postgres"</literal> database.
+     -->
+     オンラインリカバリを行うための<productname>PostgreSQL</>データベースです。
+     デフォルトは<literal>'postgres'</literal>です。
+     空文字('')が指定された場合、<productname>Pgpool-II</>は
+     <literal>「postgres」</literal>データベースの使用を試みます。
+    </para>
+    <para>
+     <!--
+     This parameter can be changed by reloading the <productname>Pgpool-II</> configurations.
+     -->
+     このパラメータは<productname>Pgpool-II</>の設定を再読み込みすることで変更可能です。
+    </para>
+    <note>
+     <para>
+      <!--
+      To perform online recovery, the functions <varname>pgpool_recovery</varname>,
+      <varname>pgpool_remote_start</varname> and
+      <varname>pgpool_switch_xlog</varname> must be created in the database
+      specified by the <xref linkend="guc-recovery-database"> parameter.
+      To install these functions in the default database
+      <literal>"postgres"</literal>, execute the following command
+      (<emphasis>if a value other than the default is configured, replace
+      <literal>"postgres"</literal> with the setting of
+      <varname>recovery_database</varname></emphasis>):
+      -->
+      オンラインリカバリを実行するには、<xref linkend="guc-recovery-database">パラメータで指定されたデータベースに、pgpool_recovery、pgpool_remote_start、および pgpool_switch_xlog 関数を作成しておく必要があります。
+      これらの関数をデフォルトのデータベース<literal>postgres</literal>に作成するには、以下のコマンドを実行してください。
+      (デフォルト値以外が設定されている場合は、<literal>postgres</literal>を<xref linkend="guc-recovery-database">に設定された値に置き換えてください)
+      <programlisting>
+$ psql postgres -c "CREATE EXTENSION pgpool_recovery"
+      </programlisting>
+     </para>
+    </note>
+   </listitem>
+  </varlistentry>
+
   <varlistentry id="guc-recovery-1st-stage-command" xreflabel="recovery_1st_stage_command">
    <term><varname>recovery_1st_stage_command</varname> (<type>string</type>)
     <indexterm>
index 91b86491e336fa4e315b8ebd6c36dd2a03332721..1f9835e0c5861650c1f4d05cc889b9cd8c00d27a 100644 (file)
@@ -866,7 +866,8 @@ PCP_USER=pgpool
   <sect3 id="example-cluster-pgpool-config-online-recovery">
    <title>Pgpool-II Online Recovery Configurations</title>
    <para>
-    Next, configure the required parameters to perform online recovery.
+    Next, configure the required parameters to perform online recovery
+    (<xref linkend="runtime-online-recovery">).
     Because <emphasis>Superuser</emphasis> privilege in <productname>PostgreSQL</productname>
     is required for performing online recovery, we specify <literal>postgres</literal>
     user in <xref linkend="GUC-RECOVERY-USER">. In this example, we leave
@@ -909,14 +910,19 @@ PGHOME=/usr/pgsql-17
    </programlisting>
 
    <para>
-    In order to use the online recovery functionality, the functions of
-    <function>pgpool_recovery</function>, <function>pgpool_remote_start</function>,
-    <function>pgpool_switch_xlog</function> are required, so we need to install
-    <function>pgpool_recovery</function> on template1 of <productname>PostgreSQL</productname> server
-    <literal>server1</literal>.
+    In addition, to perform online recovery, the functions
+    <function>pgpool_recovery</function>, <function>pgpool_remote_start</function>
+    and <function>pgpool_switch_xlog</function> must be created in advance
+    in the database specified by <xref linkend="guc-recovery-database">
+    (the default is <literal>'postgres'</literal>).
+    Execute the following command to create these functions in
+    <literal>postgres</literal> on <literal>server1</literal>.
+    If a value other than the default is configured for
+    <xref linkend="guc-recovery-database">, replace <literal>postgres</literal>
+    with the configured value.
    </para>
    <programlisting>
-[root@server1 ~]# psql -U postgres template1 -c "CREATE EXTENSION pgpool_recovery"
+[root@server1 ~]# psql -U postgres postgres -c "CREATE EXTENSION pgpool_recovery"
    </programlisting>
    <note>
     <para>
index e4280837a85ed2e01fc11893fe4ad50384a69eb9..1100a754ed826cbb5462349434598dead1e50b53 100644 (file)
@@ -559,15 +559,19 @@ PGHOME=/usr/pgsql-14
    </programlisting>
 
    <para>
-    In order to use the online recovery functionality, the functions of
-    <function>pgpool_recovery</function>, <function>pgpool_remote_start</function>,
-    <function>pgpool_switch_xlog</function> are required, so we need to install
-    <function>pgpool_recovery</function> on template1 of <productname>PostgreSQL</productname> server
-    <literal>server1</literal>.
+    In addition, to perform online recovery, the functions
+    <function>pgpool_recovery</function>, <function>pgpool_remote_start</function>
+    and <function>pgpool_switch_xlog</function> must be created in advance
+    in the database specified by <xref linkend="guc-recovery-database">
+    (the default is <literal>'postgres'</literal>).
+    Execute the following command to create these functions in
+    <literal>postgres</literal> on <literal>server1</literal>.
+    If a value other than the default is configured for
+    <xref linkend="guc-recovery-database">, replace <literal>postgres</literal>
+    with the configured value.
    </para>
    <programlisting>
-[server1]# su - postgres
-[server1]$ psql template1 -c "CREATE EXTENSION pgpool_recovery"
+[server1]# psql -U postgres postgres -c "CREATE EXTENSION pgpool_recovery"
    </programlisting>
    <note>
     <para>
index aae7de632fe80a5140cf0ba1bc69a8316960f8d2..893c9c0e3a335766865b0059885b6396dd34c683 100644 (file)
@@ -443,8 +443,6 @@ make install
    when you use the online recovery that describes latter.
    Also pgpoolAdmin of management tool, stop, restart or reload a
    <productname>PostgreSQL</productname> on the screen by use <function>pgpool_pgctl</function>.
-   It is enough, if these function installed in template1 first. These
-   function do not needed that install in all databases.
   </para>
 
   <para>
@@ -455,15 +453,22 @@ $ cd pgpool-II-&version/src/sql/pgpool-recovery
 $ make
 $ make install
    </programlisting>
-   After this:
+   After this, execute the following command to create the functions
+   <function>pgpool_recovery</function>, <function>pgpool_remote_start</function>
+   and <function>pgpool_switch_xlog</function> in the database specified in
+   <xref linkend="guc-recovery-database">
+   (The default is <literal>'postgres'</literal>).
+   If a value other than the default is configured for
+   <xref linkend="guc-recovery-database">, replace <literal>"postgres"</literal>
+   with the setting of <xref linkend="guc-recovery-database">.
    <programlisting>
-$ psql template1
+$ psql postgres
 =# CREATE EXTENSION pgpool_recovery;
    </programlisting>
 
    or
    <programlisting>
-$ psql -f pgpool-recovery.sql template1
+$ psql -f pgpool-recovery.sql postgres
    </programlisting>
 
   </para>
index 55092a744c5573e26ba9066fd2bc947a9a97ad8e..e8ee405289dc13ae7c83a88e890c69e9bfedc468 100644 (file)
    </listitem>
   </varlistentry>
 
+  <varlistentry id="guc-recovery-database" xreflabel="recovery_database">
+   <term><varname>recovery_database</varname> (<type>string</type>)
+    <indexterm>
+     <primary><varname>recovery_database</varname> configuration parameter</primary>
+    </indexterm>
+   </term>
+   <listitem>
+    <para>
+     Specifies the PostgreSQL database name to be used for online recovery.
+     The default is <literal>'postgres'</literal>. If an empty string ('')
+     is specified, <productname>Pgpool-II</productname> will attempt to use
+     the <literal>"postgres"</literal> database.
+    </para>
+    <para>
+     This parameter can be changed by reloading the <productname>Pgpool-II</> configurations.
+    </para>
+    <note>
+     <para>
+      To perform online recovery, the functions <varname>pgpool_recovery</varname>,
+      <varname>pgpool_remote_start</varname> and
+      <varname>pgpool_switch_xlog</varname> must be created in the database
+      specified by the <xref linkend="guc-recovery-database"> parameter.
+      To install these functions in the default database
+      <literal>"postgres"</literal>, execute the following command
+      (<emphasis>if a value other than the default is configured, replace
+      <literal>"postgres"</literal> with the setting of
+      <varname>recovery_database</varname></emphasis>):
+      <programlisting>
+$ psql postgres -c "CREATE EXTENSION pgpool_recovery"
+      </programlisting>
+     </para>
+    </note>
+   </listitem>
+  </varlistentry>
+
   <varlistentry id="guc-recovery-1st-stage-command" xreflabel="recovery_1st_stage_command">
    <term><varname>recovery_1st_stage_command</varname> (<type>string</type>)
     <indexterm>
index 5e61f02db4cf715ae239a3b2d27b2ca58067d17f..83ce0c2bf38ad8d40ed3a8baf7b16098bc244e55 100644 (file)
@@ -1027,6 +1027,16 @@ static struct config_string ConfigureNamesString[] =
                NULL, NULL, NULL, NULL
        },
 
+       {
+               {"recovery_database", CFGCXT_RELOAD, RECOVERY_CONFIG,
+                       "The database name for online recovery.",
+                       CONFIG_VAR_TYPE_STRING, false, 0
+               },
+               &g_pool_config.recovery_database,
+               "postgres",
+               NULL, NULL, NULL, NULL
+       },
+
        {
                {"recovery_1st_stage_command", CFGCXT_RELOAD, RECOVERY_CONFIG,
                        "Command to execute in first stage recovery.",
index 96b15af549a4660468268fe6ba1aec36656ab608..4dece394eb2af800fad7c365e2c032099fabae63 100644 (file)
@@ -184,8 +184,7 @@ typedef struct
        int                     health_check_period;    /* health check period */
        char       *health_check_user;  /* PostgreSQL user name for health check */
        char       *health_check_password;      /* password for health check username */
-       char       *health_check_database;      /* database name for health check
-                                                                                * username */
+       char       *health_check_database;      /* database name for health check */
        int                     health_check_max_retries;       /* health check max retries */
        int                     health_check_retry_delay;       /* amount of time to wait between
                                                                                         * retries */
@@ -352,8 +351,7 @@ typedef struct
        int                     health_check_period;    /* health check period */
        char       *health_check_user;  /* PostgreSQL user name for health check */
        char       *health_check_password;      /* password for health check username */
-       char       *health_check_database;      /* database name for health check
-                                                                                * username */
+       char       *health_check_database;      /* database name for health check */
        int                     health_check_max_retries;       /* health check max retries */
        int                     health_check_retry_delay;       /* amount of time to wait between
                                                                                         * retries */
@@ -386,6 +384,7 @@ typedef struct
        char       *recovery_user;      /* PostgreSQL user name for online recovery */
        char       *recovery_password;  /* PostgreSQL user password for online
                                                                         * recovery */
+       char       *recovery_database;  /* Database name for recovery */
        char       *recovery_1st_stage_command; /* Online recovery command in 1st
                                                                                         * stage */
        char       *recovery_2nd_stage_command; /* Online recovery command in 2nd
index 598c1a28d10b97ee28eefbe4b130b5fff95d5306..cc4dd5e143804e7c6d0d32d3ec1803df51de8d9d 100644 (file)
@@ -463,16 +463,25 @@ connect_backend_libpq(BackendInfo * backend)
 {
        char            port_str[16];
        PGconn     *conn;
+       char       *dbname;
        char       *password = get_pgpool_config_user_password(pool_config->recovery_user,
                                                                                                                   pool_config->recovery_password);
 
        snprintf(port_str, sizeof(port_str),
                         "%d", backend->backend_port);
+       /*
+        * If database is not specified, "postgres" database is assumed.
+        */
+       if (*pool_config->recovery_database == '\0')
+               dbname = "postgres";
+       else
+               dbname = pool_config->recovery_database;
+
        conn = PQsetdbLogin(backend->backend_hostname,
                                                port_str,
                                                NULL,
                                                NULL,
-                                               "template1",
+                                               pool_config->recovery_database,
                                                pool_config->recovery_user,
                                                password ? password : "");
 
index 301289c928cadf54c25693fcc627324eb9026b25..bec929dcd947b0add74c4ac3f39a3b23d1ece3ba 100644 (file)
@@ -667,6 +667,9 @@ backend_clustering_mode = streaming_replication
                                    # Leaving it empty will make Pgpool-II to first look for the
                                    # Password in pool_passwd file before using the empty password
 
+#recovery_database = 'postgres'
+                                   # Database name for online recovery
+
 #recovery_1st_stage_command = ''
                                    # Executes a command in first stage
 #recovery_2nd_stage_command = ''
index 4eff7dd73e786decfd6d5316534afd2df5cecbde..926b8f8ac02df6267bb00ea5880f82b01fa1ac34 100644 (file)
@@ -881,6 +881,7 @@ function set_pgpool_conf {
        echo "sr_check_password = ''"  >> $CONF
        echo "recovery_user = '$WHOAMI'" >> $CONF
        echo "recovery_password = ''"  >> $CONF
+       echo "recovery_database = 'template1'"  >> $CONF
        echo "recovery_1st_stage_command = 'basebackup.sh'" >> $CONF
 
        if [ $MODE = "r" -o $MODE = "i" ];then
index 42ba2f7522c027d6171e5c0cf7b4b8f6a4f38cf4..d84a5b619b81517768136acbf2114d28f0c7ae39 100644 (file)
@@ -107,6 +107,7 @@ function set_pgpool_conf {
     echo "sr_check_user = '$WHOAMI'" >> $CONF
     echo "recovery_user = '$WHOAMI'" >> $CONF
     echo "recovery_password = ''"  >> $CONF
+    echo "recovery_database = 'template1'"  >> $CONF
     echo "recovery_1st_stage_command = 'basebackup.sh'" >> $CONF
 
     if [ $MODE = "r" || $MODE = "i" ];then
index 01761c73efc4e950aa52c95e622036aff8dfff83..ce4117a4bbcac08742656398a10eb7bb51c828f3 100644 (file)
@@ -774,6 +774,11 @@ get_config(int *nrows)
        StrNCpy(status[i].desc, "online recovery user", POOLCONFIG_MAXDESCLEN);
        i++;
 
+       StrNCpy(status[i].name, "recovery_database", POOLCONFIG_MAXNAMELEN);
+       snprintf(status[i].value, POOLCONFIG_MAXVALLEN, "%s", pool_config->recovery_database);
+       StrNCpy(status[i].desc, "database name for online recovery", POOLCONFIG_MAXDESCLEN);
+       i++;
+
        StrNCpy(status[i].name, "recovery_1st_stage_command", POOLCONFIG_MAXNAMELEN);
        snprintf(status[i].value, POOLCONFIG_MAXVALLEN, "%s", pool_config->recovery_1st_stage_command);
        StrNCpy(status[i].desc, "execute a command in first stage.", POOLCONFIG_MAXDESCLEN);