1<!-- doc/src/sgml/config.sgml -->
2
3<sect1 id="runtime-online-recovery">
4 <!--
5 <title>Online Recovery</title>
6 -->
7 <title>オンラインリカバリ</title>
8
9 <para>
10  <!--
11  <productname>Pgpool-II</productname> can synchronize database
12  nodes and attach a node without stopping the service.  This
13  feature is called <acronym>"online recovery"</acronym>.  Online
14  recovery can be executed by
15  using <xref linkend="pcp-recovery-node"> command.
16  -->
17  <productname>Pgpool-II</productname> はサービスを止めることなくデータベースノードを同期させ、ノードを復帰させることができます。
18  この機能は「<acronym>オンラインリカバリ</acronym>」と呼ばれます。
19  オンラインリカバリは<xref linkend="pcp-recovery-node">コマンドで実行できます。
20 </para>
21 <para>
22  <!--
23  For online recovery, the recovery target node must be in detached
24  state. This means the node must be either manually detached by
25  <xref linkend="pcp-detach-node"> or automatically detached
26  by <productname>Pgpool-II</productname> as a consequnece of
27  failover.
28  -->
29  オンラインリカバリを実施するためには、リカバリ対象のノードは<productname>Pgpool-II</productname>から切り離された状態になっていなければなりません。
30  このことは、そのノードが、<xref linkend="pcp-detach-node">で手動で切り離された状態にあるか、フェイルオーバの結果、<productname>Pgpool-II</productname>により自動的に切り離された状態にあるかのいずれかでなければならないことを意味します。
31 </para>
32 <para>
33  <!--
34  If you wish to add a <productname>PostgreSQL</productname> server
35  node dynamically, reload the
36  <filename>pgpool.conf</filename> after adding the
37  <xref linkend="guc-backend-hostname"> and its associated
38  parameters.  This will register the new server
39  to <productname>Pgpool-II</productname> as a detached backend
40  node.
41  -->
42  新しい<productname>PostgreSQL</>サーバを動的に追加したい場合には、<xref linkend="guc-backend-hostname">および関連パラメータを追加した後に<filename>pgpool.conf</filename>を再読み込みします。
43   これにより新しいサーバが切り離された状態のバックエンドノードとして<productname>Pgpool-II</productname>に登録されます。
44 </para>
45 <!--
46 <caution>
47 <para>
48 Make sure that <command>autovacuum</command> is stopped on the
49 master node (the first node which is up and running) before starting the
50 online recovery. Autovacuum can change the contents of the database which
51 can cause the inconsistency after the online recovery.
52 オンラインリカバリを実行する前に、マスタノード(稼働中のノードのうち、一番番号が若いノード)上での<command>autovacuum</command>を停止してください。
53 オンラインリカバリ中に<command>autovacuum</command>が動作すると、データベースの内容が変化する可能性があるため、ノード間の同期がきちんと取れなくなる可能性があります。
54    </para>
55 <para>
56 This applies only if you're recovering with a simple copy mechanism,
57 such as the <command>rsync</command> and doesn't apply when using
58 the PostgreSQL's PITR mechanism.
59 この制限は、<command>rsync</command>などの単純なコピー方法を使っている場合にのみ適用されます。
60 PostgreSQLのPITRを使っている場合は適用されません。
61    </para>
62  </caution>
63 -->
64 <note>
65  <para>
66   <!--
67   The recovery target <productname>PostgreSQL</> server must not be running for performing the online recovery.
68   If the target <productname>PostgreSQL</> server has already started, you must shut it down before
69   starting the online recovery.
70   -->
71   オンラインリカバリ実行のためには、対象となる<productname>PostgreSQL</>サーバは稼働していてはいけません。
72   対象の<productname>PostgreSQL</>がすでに動作中であれば、オンラインリカバリを開始する前にシャットダウンしておいてください。
73  </para>
74 </note>
75
76 <para>
77  <!--
78  Online recovery is performed in two phases. The first phase is
79  called "first stage" and the second phase is called "second
80  stage". You need to provide scripts for each
81  stage. Only <xref linkend="guc-replication-mode"> requires the
82  second stage.  For other modes including streaming replication
83  mode the second stage is not performed and you don't need to
84  provide a script for the stage
85  in <xref linkend="guc-recovery-2nd-stage-command">. i.e. you can
86  safely leave it as an empty string.
87
88  Online recovery is performed in two phases. Connections from cliens are
89  not allowd in second phase of online recovery while the data can be
90  updated or retrieved during the first phase.
91  <productname>Pgpool-II</productname> performs the follows steps in online recovery:
92  -->
93  オンラインリカバリは2段階に分けて実施されます。
94  第1段階は「ファーストステージ」、第2段階は「セカンドステージ」と呼ばれます。
95  それぞれのステージ用にスクリプトを用意する必要があります。
96  <xref linkend="guc-replication-mode">の時のみセカンドステージが必要です。
97   ストリーミングレプリケーションモードを含むその他のモードでは、セカンドステージは実施されず、<xref linkend="guc-recovery-2nd-stage-command">用のスクリプトを用意する必要はありません。
98    つまり、そのエントリを空文字にしておいても問題ありません。
99 </para>
100 <para>
101  <!--
102  Connections from cliens are not allowd only in the second stage
103  while the data can be updated or retrieved during the first statge.
104  -->
105  ファーストステージではデータの更新や読み取りができますが、セカンドステージではクライアントからの接続は許されていません。
106 </para>
107 <para>
108  <!--
109  <productname>Pgpool-II</productname> performs the follows steps in online recovery:
110  -->
111  オンラインリカバリでは<productname>Pgpool-II</productname>は以下の手順を実施します。
112 </para>
113 <itemizedlist>
114
115  <listitem>
116   <para>
117    CHECKPOINT.
118   </para>
119  </listitem>
120  <listitem>
121   <para>
122    <!--
123    First stage of online recovery.
124    -->
125    オンラインリカバリのファーストステージ。
126   </para>
127  </listitem>
128  <listitem>
129   <para>
130    <!--
131    Wait until all client connections have disconnected.
132    -->
133    全てのクライアント接続が切断されるまで待機（<xref linkend="guc-replication-mode">のみ）。
134   </para>
135  </listitem>
136  <listitem>
137   <para>
138    CHECKPOINT（<xref linkend="guc-replication-mode">のみ）。
139   </para>
140  </listitem>
141  <listitem>
142   <para>
143    <!--
144    Second stage of online recovery.
145    -->
146    オンラインリカバリのセカンドステージ（<xref linkend="guc-replication-mode">のみ）。
147   </para>
148  </listitem>
149  <listitem>
150   <para>
151    <!--
152    Start up postmaster (perform <literal>pgpool_remote_start</literal>)
153    -->
154    postmasterの起動（<literal>pgpool_remote_start</literal>の実施）
155   </para>
156  </listitem>
157  <listitem>
158   <para>
159    <!--
160    Node attach
161    -->
162    ノードの復帰
163   </para>
164  </listitem>
165
166 </itemizedlist>
167 <note>
168  <para>
169   <!--
170   There is a restriction in the online recovery in
171   <xref linkend="guc-replication-mode">. If
172   <productname>Pgpool-II</productname> itself is installed
173   on multiple hosts, online recovery does not work correctly,
174   because <productname>Pgpool-II</productname> has to stop all
175   the clients during the 2nd stage of online recovery.
176   If there are several <productname>Pgpool-II</productname> hosts,
177   only one of them will have received the online recovery command and will
178   block the connections from clients.
179   -->
180   <xref linkend="guc-replication-mode">でのオンラインリカバリには制限事項があります。
181    <productname>Pgpool-II</productname>が複数のホストにインストールされている場合、<productname>Pgpool-II</productname>はオンラインリカバリの2ndステージの間全てのクライアントを止める必要があるため、オンラインリカバリは正しく動作しません。
182    複数の<productname>Pgpool-II</productname>ホストがある場合、そのうちの１台のみがオンラインリカバコマンドを受け取り、クライアントからの接続をブロックします。
183  </para>
184 </note>
185 <variablelist>
186
187  <varlistentry id="guc-recovery-user" xreflabel="recovery_user">
188   <term><varname>recovery_user</varname> (<type>string</type>)
189    <indexterm>
190     <!--
191     <primary><varname>recovery_user</varname> configuration parameter</primary>
192     -->
193     <primary><varname>recovery_user</varname> 設定パラメータ</primary>
194    </indexterm>
195   </term>
196   <listitem>
197    <para>
198     <!--
199     Specifies the <productname>PostgreSQL</> user name to perform online recovery.
200     -->
201     オンラインリカバリを行うための<productname>PostgreSQL</>ユーザ名です。
202    </para>
203    <para>
204     <!--
205     This parameter can be changed by reloading the <productname>Pgpool-II</> configurations.
206     -->
207     このパラメータは<productname>Pgpool-II</>の設定を再読み込みすることで変更可能です。
208    </para>
209   </listitem>
210  </varlistentry>
211
212  <varlistentry id="guc-recovery-password" xreflabel="recovery_password">
213   <term><varname>recovery_password</varname> (<type>string</type>)
214    <indexterm>
215     <!--
216     <primary><varname>recovery_password</varname> configuration parameter</primary>
217     -->
218     <primary><varname>recovery_password</varname> 設定パラメータ</primary>
219    </indexterm>
220   </term>
221   <listitem>
222    <para>
223     <!--
224     Specifies the password for the <productname>PostgreSQL</> user name configured in
225     -->
226     オンラインリカバリを行うための PostgreSQL ユーザパスワードです。
227    </para>
228    <para>
229     <!--
230     This parameter can be changed by reloading the <productname>Pgpool-II</> configurations.
231     -->
232     このパラメータは<productname>Pgpool-II</>の設定を再読み込みすることで変更可能です。
233    </para>
234   </listitem>
235  </varlistentry>
236
237  <varlistentry id="guc-recovery-1st-stage-command" xreflabel="recovery_1st_stage_command">
238   <term><varname>recovery_1st_stage_command</varname> (<type>string</type>)
239    <indexterm>
240     <!--
241     <primary><varname>recovery_1st_stage_command</varname> configuration parameter</primary>
242     -->
243     <primary><varname>recovery_1st_stage_command</varname> 設定パラメータ</primary>
244    </indexterm>
245   </term>
246   <listitem>
247    <para>
248     <!--
249     Specifies a command file to be run by master(primary) node at the
250     first stage of online recovery. The command file must be placed in the
251     database cluster directory for security reasons.
252     For example, if <varname>recovery_1st_stage_command</varname> = <literal>
253     'sync-command'</literal>, then <productname>Pgpool-II</productname> will
254     look for the command scrit in <literal>$PGDATA</literal> directory and will
255     try to execute <command>$PGDATA/sync-command</command>.
256     -->
257     オンラインリカバリのファーストステージでマスタ（プライマリ）ノードで実行されるコマンドを指定します。
258     コマンドファイルはセキュリティ上の観点からデータベースクラスタ内に配置される必要があります。
259     例えば、<varname>recovery_1st_stage_command</varname> = <literal>'sync-command'</literal>となっている場合、<productname>Pgpool-II</productname>はコマンドスクリプトを<literal>$PGDATA</literal>ディレクトリの中で探し、<command>$PGDATA/sync-command</command>を起動しようとします。
260    </para>
261    <para>
262     <!--
263     <varname>recovery_1st_stage_command</varname> receives following 4 parameters:
264     -->
265     <varname>recovery_1st_stage_command</varname>は次の4つの引数を受けとります。
266    </para>
267
268    <itemizedlist>
269     <listitem>
270      <para>
271       <!--
272       Path to the database cluster of the master(primary) node.
273       -->
274       マスター（プライマリ）ノードのデータベースクラスタへのパス
275      </para>
276     </listitem>
277     <listitem>
278      <para>
279       <!--
280       Hostname of the backend node to be recovered.
281       -->
282       リカバリされるバックエンドノードのホスト名
283      </para>
284     </listitem>
285     <listitem>
286      <para>
287       <!--
288       Path to the database cluster of the node to be recovered.
289       -->
290       リカバリされるノードのデータベースクラスタへのパス
291      </para>
292     </listitem>
293     <listitem>
294      <para>
295       <!--
296       Port number of the master(primary) node.
297       -->
298       マスター（プライマリ）ノードのポート番号
299      </para>
300     </listitem>
301    </itemizedlist>
302
303    <note>
304     <para>
305      <!--
306      <productname>Pgpool-II</productname> accept connections and queries
307      while <varname>recovery_1st_stage command</varname> is executed,
308      so you can retrieve and update data.
309      -->
310      <varname>recovery_1st_stage_command</varname>の実行中は<productname>Pgpool-II</productname>は接続やクエリを受け付けており、データの参照や更新を行うことができます。
311     </para>
312    </note>
313
314    <caution>
315     <para>
316      <!--
317      <varname>recovery_1st_stage command</varname> runs as a <acronym>SQL</acronym>
318      command from <productname>PostgreSQL</>'s point of view. Therefore, <varname>recovery_1st_stage_command
319     </varname> can get prematuraly killed by <productname>PostgreSQL</> if
320      <varname>statement_timeout</varname> is configured with the value that is
321      smaller than the time <varname>recovery_1st_stage_command</varname> takes for
322      completion.
323      -->
324      <varname>recovery_1st_stage_command</varname>は、<productname>PostgreSQL</>から見ると、一つの<acronym>SQL</acronym>として実行されます。
325      そのため、<productname>PostgreSQL</>の<varname>statement_timeout</varname>が<varname>recovery_1st_stage_command</varname>の完了にかかる時間よりも短く設定されていると、<varname>recovery_1st_stagecommand</varname>コマンドの実行が途中でキャンセルされます。
326     </para>
327     <para>
328      <!--
329      Typical error in such case is
330      -->
331      典型的なエラーは以下のようなものです。
332      <programlisting>
333       rsync used in the command is killed by signal 2 for example.
334      </programlisting>
335     </para>
336    </caution>
337
338    <para>
339     <!--
340     This parameter can be changed by reloading the <productname>Pgpool-II</> configurations.
341     -->
342     このパラメータは<productname>Pgpool-II</>の設定を再読み込みすることで変更可能です。
343    </para>
344   </listitem>
345  </varlistentry>
346
347  <varlistentry id="guc-recovery-2nd-stage-command" xreflabel="recovery_2nd_stage_command">
348   <term><varname>recovery_2nd_stage_command</varname> (<type>string</type>)
349    <indexterm>
350     <!--
351     <primary><varname>recovery_2nd_stage_command</varname> configuration parameter</primary>
352     -->
353     <primary><varname>recovery_2nd_stage_command</varname> 設定パラメータ</primary>
354    </indexterm>
355   </term>
356   <listitem>
357
358    <para>
359     <!--
360     Specifies a command file to be run by master(primary) node at the
361     second stage of online recovery. The command file must be placed in the
362     database cluster directory for security reasons.
363     For example, if <varname>recovery_2nd_stage_command</varname> = <literal>
364     'sync-command'</literal>, then <productname>Pgpool-II</productname> will
365     look for the command scrit in <literal>$PGDATA</literal> directory and will
366     try to execute <command>$PGDATA/sync-command</command>.
367     -->
368     オンラインリカバリのセカンドステージでマスタ（プライマリ）ノードで実行されるコマンドを指定します。
369     コマンドファイルはセキュリティ上の観点からデータベースクラスタ内に配置される必要があります。
370     例えば、<varname>recovery_2nd_stage_command</varname> = <literal>'sync-command'</literal>となっている場合、<productname>Pgpool-II</productname>はコマンドスクリプトを<literal>$PGDATA</literal>ディレクトリの中で探し、<command>$PGDATA/sync-command</command>を起動しようとします。
371    </para>
372    <para>
373     <!--
374     <varname>recovery_2nd_stage_command</varname> receives following 4 parameters:
375     -->
376     <varname>recovery_2nd_stage_command</varname>は次の4つの引数を受けとります。
377    </para>
378
379    <itemizedlist>
380     <listitem>
381      <para>
382       <!--
383       Path to the database cluster of the master(primary) node.
384       -->
385       マスター（プライマリ）ノードのデータベースクラスタへのパス
386      </para>
387     </listitem>
388     <listitem>
389      <para>
390       <!--
391       Hostname of the backend node to be recovered.
392       -->
393       リカバリされるバックエンドノードのホスト名
394      </para>
395     </listitem>
396     <listitem>
397      <para>
398       <!--
399       Path to the database cluster of the node to be recovered.
400       -->
401       リカバリされるノードのデータベースクラスタへのパス
402      </para>
403     </listitem>
404     <listitem>
405      <para>
406       <!--
407       Port number of the master(primary) node.
408       -->
409       マスター（プライマリ）ノードのポート番号
410      </para>
411     </listitem>
412    </itemizedlist>
413
414    <note>
415     <para>
416      <!--
417      <productname>Pgpool-II</productname> <emphasis>does not</emphasis>
418      accept client connections and queries during the execution
419      of <varname>recovery_2nd_stage_command</varname> command, and waits
420      for the existing clients to close their connections before executing the
421      command.
422      Therefore, the <varname>recovery_2nd_stage_command</varname> may not execute
423      if the client stays connected for a long time.
424      -->
425      <varname>recovery_2nd_stage_command</varname>の実行中は、<productname>Pgpool-II</productname>はクライアントからの接続およびクエリを<emphasis>受け付けません</emphasis>。
426      また、コマンドを実行する前に既存のクライアントが接続を閉じるのを待ちます。
427      そのため、長時間接続したままのクライアントがいる場合、<varname>recovery_2nd_stage_command</varname>は実行されない可能性があります。
428     </para>
429    </note>
430
431    <caution>
432     <para>
433      <!--
434      <varname>recovery_2nd_stage command</varname> runs as a <acronym>SQL</acronym>
435      command from PostgreSQL's point of view. Therefore, <varname>recovery_2nd_stage command
436     </varname> can get prematuraly killed by PostgreSQL if the PostgreSQL's
437      <varname>statement_time_out</varname> is configured with the value that is
438      smaller than the time <varname>recovery_2nd_stage_command</varname> takes for
439      completion.
440      -->
441      <varname>recovery_2nd_stage_command</varname>は、<productname>PostgreSQL</>から見ると、一つの<acronym>SQL</acronym>として実行されます。
442      そのため、<productname>PostgreSQL</>の<varname>statement_timeout</varname>が<varname>recovery_2nd_stage_command</varname>の完了にかかる時間よりも短く設定されていると、<varname>recovery_1st_stagecommand</varname>コマンドの実行が途中でキャンセルされます。
443     </para>
444    </caution>
445
446    <para>
447     <!--
448     This parameter can be changed by reloading the <productname>Pgpool-II</> configurations.
449     -->
450     このパラメータは<productname>Pgpool-II</>の設定を再読み込みすることで変更可能です。
451    </para>
452   </listitem>
453  </varlistentry>
454
455  <varlistentry id="guc-recovery-timeout" xreflabel="recovery_timeout">
456   <term><varname>recovery_timeout</varname> (<type>integer</type>)
457    <indexterm>
458     <!--
459     <primary><varname>recovery_timeout</varname> configuration parameter</primary>
460     -->
461     <primary><varname>recovery_timeout</varname> 設定パラメータ</primary>
462    </indexterm>
463   </term>
464   <listitem>
465    <para>
466     <!--
467     Specifies the timeout in seconds to cancel the online recovery if it
468     does not completes within this time.
469     Since <productname>Pgpool-II</productname> does not accepts the connections
470     during the second stage of online recovery, this parameter can be used to cancel
471     the online recovery to manage the service down time during the online recovery.
472     -->
473     時間内にオンラインリカバリが完了しなかった場合に、これをキャンセルするためのタイムアウトを秒単位で指定します。
474     <productname>Pgpool-II</productname>は、オンラインリカバリのセカンドステージの間は接続を受け付けないので、このパラメータはオンラインリカバリの最中のサーバがダウンした時にオンラインリカバリをキャンセルするのに使えます。
475    </para>
476    <para>
477     <!--
478     This parameter can be changed by reloading the <productname>Pgpool-II</> configurations.
479     -->
480     このパラメータは<productname>Pgpool-II</>の設定を再読み込みすることで変更可能です。
481    </para>
482   </listitem>
483  </varlistentry>
484
485  <varlistentry id="guc-client-idle-limit-in-recovery" xreflabel="client_idle_limit_in_recovery">
486   <term><varname>client_idle_limit_in_recovery</varname> (<type>integer</type>)
487    <indexterm>
488     <!--
489     <primary><varname>client_idle_limit_in_recovery</varname> configuration parameter</primary>
490     -->
491     <primary><varname>client_idle_limit_in_recovery</varname> 設定パラメータ</primary>
492    </indexterm>
493   </term>
494   <listitem>
495    <para>
496     <!--
497     Specifies the time in seconds to disconnect a client if it remains idle
498     since the last query during the online recovery.
499     <varname>client_idle_limit_in_recovery</varname> is similar to the
500     <xref linkend="guc-client-idle-limit"> but only takes effect during the
501     second stage of online recovery.
502     -->
503     オンラインリカバリの最中で、クライアントが前回のクエリからアイドル状態のままでいるときに、それを切断するまでの時間を秒単位で指定します。
504     <varname>client_idle_limit_in_recovery</varname>は<xref linkend="guc-client-idle-limit">と似ていますが、オンラインリカバリのセカンドステージでのみ効果を持ちます。
505    </para>
506    <para>
507     <!--
508     This is useful for preventing the <productname>Pgpool-II</productname>
509     recovery from being disturbed by the lazy clients or if the TCP/IP
510     connection between the client and <productname>Pgpool-II</productname>
511     is accidentally down (a cut cable for instance).
512     -->
513     これは、だらしないクライアントや<productname>Pgpool-II</productname>の間のTCP/IPコネクションの不調（例えばケーブルの切断など）によって、<productname>Pgpool-II</productname>のリカバリが邪魔されるのを防止するのに役立ちます。
514    </para>
515
516    <note>
517     <para>
518      <!--
519      <varname>client_idle_limit_in_recovery</varname> must be smaller than
520      <xref linkend="guc-recovery-timeout">.
521      Otherwise, <xref linkend="guc-recovery-timeout"> comes
522      first and you will see following error while executing online recovery:
523      -->
524      <varname>client_idle_limit_in_recovery</varname>は、<xref linkend="guc-recovery-timeout">よりも小さな値でなければなりません。
525       さもないと、<xref linkend="guc-recovery-timeout">のタイムアウトが先に起こり、オンラインリカバリを実行中に以下のエラーとなります。
526	<programlisting>
527	 ERROR:  node recovery failed, waiting connection closed in the other pgpools timeout
528	</programlisting>
529     </para>
530    </note>
531
532    <para>
533     <!--
534     If set to -1, all clients get immediately disconnected when the second
535     stage of online recovery starts.
536     The default is 0, which turns off the feature.
537     -->
538     -1に設定すると、オンラインリカバリのセカンドステージが始まると全てのクライアントは直ちに切断されます。
539     デフォルト値は0で、この機能は無効です。
540    </para>
541
542    <para>
543     <!--
544     This parameter can be changed by reloading the <productname>Pgpool-II</> configurations.
545     You can also use <xref linkend="SQL-PGPOOL-SET"> command to alter the value of
546     this parameter for a current session.
547     -->
548     このパラメータは<productname>Pgpool-II</>の設定を再読み込みすることで変更可能です。
549     現在のセッションでのパラメータ値は、<xref linkend="SQL-PGPOOL-SET">コマンドで変更することもできます。
550    </para>
551   </listitem>
552  </varlistentry>
553
554 </variablelist>
555</sect1>
556