Update doc about "Setting up PostgreSQL standby" in "8.2. Pgpool-II + Watchdog Setup...

Add a note that when setting up a standby without online recovery, do not write primary_conninfo to postgresql.auto.conf.

Discussion: https://github.com/pgpool/pgpool2/issues/67
Backpatch-through: v4.2

diff --git a/doc.ja/src/sgml/example-cluster.sgml b/doc.ja/src/sgml/example-cluster.sgml
index 070155a74798ce8fc6fea2a9608ed388a06c00b6..13922196abd990891dad95ab3dcad19961840ec9 100644 (file)
--- a/doc.ja/src/sgml/example-cluster.sgml
+++ b/doc.ja/src/sgml/example-cluster.sgml
@@ -289,21 +289,7 @@ exclude=pgpool*
   <itemizedlist>
    <listitem>
     <para>
-     <productname>PostgreSQL</productname>プライマリサーバのみでストリーミングレプリケーションの設定を行います。
-     スタンバイサーバの設定は、プライマリが起動した状態で、<productname>Pgpool-II</productname>の
-     オンラインリカバリ機能を使って行うため不要です。この設定の例ではアーカイブリカバリを行うように設定します。
-    </para>
-    <para>
-     まず、すべてのサーバにて<acronym>WAL</acronym>を格納するディレクトリ<filename>/var/lib/pgsql/archivedir</filename>を
-     事前に作成します。この設定例では、プライマリサーバのみで<acronym>WAL</acronym>アーカイブをローカルで実施します。
-    </para>
-    <programlisting>
-[全サーバ]# su - postgres
-[全サーバ]$ mkdir /var/lib/pgsql/archivedir
-    </programlisting>
-
-    <para>
-     プライマリサーバの<productname>PostgreSQL</productname>を初期化します。
+     プライマリサーバーをセットアップします。まずプライマリサーバの<productname>PostgreSQL</productname>を初期化します。
     </para>
     <programlisting>
 [server1]# su - postgres
@@ -312,6 +298,7 @@ exclude=pgpool*
 
     <para>
      次に<literal>server1</literal>にて、設定ファイル<filename>$PGDATA/postgresql.conf</filename>を以下のように編集します。
+     この設定例では、プライマリサーバのみでWALアーカイブをローカルで実施します。
      <application>pg_rewind</application>を使うために<varname>wal_log_hints</varname>を有効にしておきます。
      プライマリが後でスタンバイになる可能性があるので、<literal>hot_standby = on</literal>にしておきます。
     </para>
@@ -327,6 +314,54 @@ wal_log_hints = on
     </programlisting>
    </listitem>
 
+   <listitem>
+    <para>
+     スタンバイサーバをセットアップします。スタンバイサーバをセットアップする方法としては、次のような複数の方法があります。
+     <itemizedlist>
+      <listitem>
+       <para>
+        <productname>Pgpool-II</productname>のオンラインリカバリ機能（<xref linkend="runtime-online-recovery">）を使用して、スタンバイサーバを自動的にセットアップします。
+       </para>
+      </listitem>
+      <listitem>
+       <para>
+        スタンバイで<command>pg_basebackup</command>を実行して、プライマリのデータディレクトリのバックアップを生成します。
+       </para>
+      </listitem>
+     </itemizedlist>
+    </para>
+    <note>
+     <para>
+      オンラインリカバリを使用せず手動でスタンバイをセットアップする場合は次の注意点があります。
+      <itemizedlist>
+       <listitem>
+        <para>
+         手動でレプリケーションスロットを作成する必要があります。
+        </para>
+       </listitem>
+       <listitem>
+        <para>
+         pg_basebackup を実行する際には -R オプションを指定しないでください。<varname>primary_conninfo</varname>、 <varname>recovery_target_timeline</varname>、 <varname>primary_slot_name</varname> は <filename>postgresql.auto.conf</filename> ではなく、<filename>$PGDATA/myrecovery.conf</filename> に記載し、<filename>postgresql.conf</filename> に以下を追記してください。
+        </para>
+       </listitem>
+      </itemizedlist>
+      <programlisting>
+include_if_exists = 'myrecovery.conf'
+      </programlisting>
+     </para>
+    </note>
+   </listitem>
+   <listitem>
+    <para>
+     この設定の例ではアーカイブリカバリを行うように設定します。
+     すべてのサーバにて<acronym>WAL</acronym>を格納するディレクトリ<filename>/var/lib/pgsql/archivedir</filename>を事前に作成します。
+    </para>
+    <programlisting>
+[全サーバ]# su - postgres
+[全サーバ]$ mkdir /var/lib/pgsql/archivedir
+    </programlisting>
+   </listitem>
+
    <listitem>
     <para>
      <productname>Pgpool-II</productname>のヘルスチェック及びレプリケーションの

diff --git a/doc/src/sgml/example-cluster.sgml b/doc/src/sgml/example-cluster.sgml
index 1548ab19279803a92175d016f23a6cd2337ad1b3..b0f8daa211dec68a8230fc3d628c142f574f74f9 100644 (file)
--- a/doc/src/sgml/example-cluster.sgml
+++ b/doc/src/sgml/example-cluster.sgml
@@ -279,21 +279,7 @@ exclude=pgpool*
   <itemizedlist>
    <listitem>
     <para>
-     Set up <productname>PostgreSQL</productname> streaming replication on the primary server.
-     In this example, we use WAL archiving.
-    </para>
-    <para>
-     First, we create the directory <filename>/var/lib/pgsql/archivedir</filename> to store
-     <acronym>WAL</acronym> segments on all servers. In this example, only Primary node archives
-     <acronym>WAL</acronym> locally.
-    </para>
-    <programlisting>
-[all servers]# su - postgres
-[all servers]$ mkdir /var/lib/pgsql/archivedir
-    </programlisting>
-
-    <para>
-     Initialize <productname>PostgreSQL</productname> on the primary server.
+     Set up the primary server. Initialize <productname>PostgreSQL</productname> on the primary server.
     </para>
     <programlisting>
 [server1]# su - postgres
@@ -302,7 +288,8 @@ exclude=pgpool*
 
     <para>
      Then we edit the configuration file <filename>$PGDATA/postgresql.conf</filename>
-     on <literal>server1</literal> (primary) as follows. Enable <literal>wal_log_hints</literal>
+     on <literal>server1</literal> (primary) as follows. In this example, only Primary node archives
+     <acronym>WAL</acronym> locally. Enable <literal>wal_log_hints</literal>
      to use <literal>pg_rewind</literal>. 
      Since the Primary may become a Standby later, we set <varname>hot_standby = on</varname>.
     </para>
@@ -316,9 +303,59 @@ wal_level = replica
 hot_standby = on
 wal_log_hints = on
     </programlisting>
+   </listitem>
+
+   <listitem>
     <para>
-     We use the online recovery functionality of <productname>Pgpool-II</productname> to setup standby server after the primary server is started.
+     Set up the standby server.There are multiple methods to setup a standby server, such as:
+     <itemizedlist>
+      <listitem>
+       <para>
+        use <productname>Pgpool-II</productname>'s online recovery feature
+        (<xref linkend="runtime-online-recovery">) to automatically
+        setup a standby server.
+       </para>
+      </listitem>
+      <listitem>
+       <para>
+        use pg_basebackup to backup the data directory of the primary from the standby.
+       </para>
+      </listitem>
+     </itemizedlist>
     </para>
+    <note>
+     <para>
+      If you set up standby manually without using online recovery, please note the following:
+      <itemizedlist>
+       <listitem>
+        <para>
+         You must manually create the replication slots.
+        </para>
+       </listitem>
+       <listitem>
+        <para>
+         Do not specify the -R option when running pg_basebackup.
+         Write <varname>primary_conninfo</varname>, <varname>recovery_target_timeline</varname>, and <varname>primary_slot_name</varname> in <filename>$PGDATA/myrecovery.conf</filename>, not in <filename>postgresql.auto.conf</filename>, and add the following to <filename>postgresql.conf</filename>.
+        </para>
+       </listitem>
+      </itemizedlist>
+      <programlisting>
+include_if_exists = 'myrecovery.conf'
+      </programlisting>
+     </para>
+    </note>
+   </listitem>
+
+   <listitem>
+    <para>
+     In this example configuration, we will configure it to use online recovery. We
+     create the directory <filename>/var/lib/pgsql/archivedir</filename> to store
+     <acronym>WAL</acronym> segments on all servers.
+    </para>
+    <programlisting>
+[all servers]# su - postgres
+[all servers]$ mkdir /var/lib/pgsql/archivedir
+    </programlisting>
    </listitem>
 
    <listitem>