<!-- doc/src/sgml/config.sgml -->

<sect1 id="runtime-online-recovery">
<!--
  <title>Online Recovery</title>
-->
  <title>オンラインリカバリ</title>

  <para>
<!--
    <productname>Pgpool-II</productname> can synchronize database nodes and attach
	a node without stopping the service.
    This feature is called <acronym>"online recovery"</acronym>.
-->
<productname>Pgpool-II</productname> はサービスを止めることなくデータベースノード同期させ、ノードを復帰させることができます。
この機能は「<acronym>オンラインリカバリ</acronym>」と呼ばれます。
  </para>
  <para>
<!--
    For online recovery, the recovery target node must be detached from <productname>Pgpool-II</>.
    If you wish to add a <productname>PostgreSQL</> server node dynamically, reload the
    <filename>pgpool.conf</filename> after adding the
    <xref linkend="guc-backend-hostname"> and its associated parameters.
    This will register the new server to <productname>Pgpool-II</productname> as a detached backend node.
-->
オンラインリカバリを実施するためには、リカバリ対象のノードは<productname>Pgpool-II</>から切り離されている必要があります。
新しい<productname>PostgreSQL</>サーバを動的に追加したい場合には、<xref linkend="guc-backend-hostname">および関連パラメータを追加した後に<filename>pgpool.conf</filename>を再読み込みします。
これにより新しいサーバが切り離された状態のバックエンドノードとして<productname>Pgpool-II</productname>に登録されます。
  </para>
<!--
  <caution>
    <para>
      Make sure that <command>autovacuum</command> is stopped on the
      master node (the first node which is up and running) before starting the
      online recovery. Autovacuum can change the contents of the database which
      can cause the inconsistency after the online recovery.
オンラインリカバリを実行する前に、マスタノード(稼働中のノードのうち、一番番号が若いノード)上での<command>autovacuum</command>を停止してください。
オンラインリカバリ中に<command>autovacuum</command>が動作すると、データベースの内容が変化する可能性があるため、ノード間の同期がきちんと取れなくなる可能性があります。
    </para>
    <para>
      This applies only if you're recovering with a simple copy mechanism,
      such as the <command>rsync</command> and doesn't apply when using
      the PostgreSQL's PITR mechanism.
この制限は、<command>rsync</command>などの単純なコピー方法を使っている場合にのみ適用されます。
PostgreSQLのPITRを使っている場合は適用されません。
    </para>
  </caution>
-->
  <note>
    <para>
<!--
      The recovery target <productname>PostgreSQL</> server must not be running for performing the online recovery.
      If the target <productname>PostgreSQL</> server has already started, you must shut it down before
      starting the online recovery.
-->
オンラインリカバリ実行のためには、対象となる<productname>PostgreSQL</>サーバは稼働していてはいけません。
対象の<productname>PostgreSQL</>がすでに動作中であれば、オンラインリカバリを開始する前にシャットダウンしておいてください。 
    </para>
  </note>

  <para>
<!--
    Online recovery is performed in two phases. Connections from cliens are
    not allowd in second phase of online recovery while the data can be
    updated or retrieved during the first phase.
    <productname>Pgpool-II</productname> performs the follows steps in online recovery:
-->
オンラインリカバリは2段階に分けて実施されます。
ファーストステージではデータの更新や読み取りができますが、セカンドステージではクライアントからの接続は許されていません。
オンラインリカバリでは<productname>Pgpool-II</productname>は以下の手順を実施します。
  </para>
  <itemizedlist>

    <listitem>
      <para>
        CHECKPOINT.
      </para>
    </listitem>
    <listitem>
      <para>
<!--
        First stage of online recovery.
-->
オンラインリカバリのファーストステージ。
      </para>
    </listitem>
    <listitem>
      <para>
<!--
        Wait until all client connections have disconnected.
-->
全てのクライアント接続が切断されるまで待機
      </para>
    </listitem>
    <listitem>
      <para>
        CHECKPOINT.
      </para>
    </listitem>
    <listitem>
      <para>
<!--
        Second stage of online recovery.
-->
オンラインリカバリのセカンドステージ。
      </para>
    </listitem>
    <listitem>
      <para>
<!--
        Start up postmaster (perform <literal>pgpool_remote_start</literal>)
-->
postmasterの起動（<literal>pgpool_remote_start</literal>の実施）
      </para>
    </listitem>
    <listitem>
      <para>
<!--
        Node attach
-->
ノードの復帰
      </para>
    </listitem>

  </itemizedlist>
  <note>
    <para>
<!--
      There is a restriction in the online recovery. If
      <productname>Pgpool-II</productname> itself is installed
      on multiple hosts, online recovery does not work correctly,
      because <productname>Pgpool-II</productname> has to stop all
      the clients during the 2nd stage of online recovery.
      If there are several <productname>Pgpool-II</productname> hosts,
      only one of them will have received the online recovery command and will
      block the connections from clients.
-->
オンラインリカバリには制限事項があります。
<productname>Pgpool-II</productname>が複数のホストにインストールされている場合、<productname>Pgpool-II</productname>はオンラインリカバリの2ndステージの間全てのクライアントを止める必要があるため、オンラインリカバリは正しく動作しません。
複数の<productname>Pgpool-II</productname>ホストがある場合、そのうちの１台のみがオンラインリカバコマンドを受け取り、クライアントからの接続をブロックします。
    </para>
  </note>
  <variablelist>

    <varlistentry id="guc-recovery-user" xreflabel="recovery_user">
      <term><varname>recovery_user</varname> (<type>string</type>)
        <indexterm>
<!--
        <primary><varname>recovery_user</varname> configuration parameter</primary>
-->
        <primary><varname>recovery_user</varname> 設定パラメータ</primary>
        </indexterm>
      </term>
      <listitem>
      <para>
<!--
        Specifies the <productname>PostgreSQL</> user name to perform online recovery.
-->
オンラインリカバリを行うための<productname>PostgreSQL</>ユーザ名です。
      </para>
        <para>
<!--
          This parameter can be changed by reloading the <productname>Pgpool-II</> configurations.
-->
このパラメータは<productname>Pgpool-II</>の設定を再読み込みすることで変更可能です。
        </para>
      </listitem>
    </varlistentry>

    <varlistentry id="guc-recovery-password" xreflabel="recovery_password">
      <term><varname>recovery_password</varname> (<type>string</type>)
        <indexterm>
<!--
        <primary><varname>recovery_password</varname> configuration parameter</primary>
-->
        <primary><varname>recovery_password</varname> 設定パラメータ</primary>
        </indexterm>
      </term>
      <listitem>
        <para>
<!--
          Specifies the password for the <productname>PostgreSQL</> user name configured in
-->
オンラインリカバリを行うための PostgreSQL ユーザパスワードです。
          <xref linkend="guc-recovery-user"> to perform online recovery.
        </para>
        <para>
<!--
          This parameter can be changed by reloading the <productname>Pgpool-II</> configurations.
-->
このパラメータは<productname>Pgpool-II</>の設定を再読み込みすることで変更可能です。
        </para>
      </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>
<!--
        <primary><varname>recovery_1st_stage_command</varname> configuration parameter</primary>
-->
        <primary><varname>recovery_1st_stage_command</varname> 設定パラメータ</primary>
        </indexterm>
      </term>
      <listitem>
        <para>
<!--
          Specifies a command file to be run by master(primary) node at the
          first stage of online recovery. The command file must be placed in the
          database cluster directory for security reasons.
          For example, if <varname>recovery_1st_stage_command</varname> = <literal>
          'sync-command'</literal>, then <productname>Pgpool-II</productname> will
          look for the command scrit in <literal>$PGDATA</literal> directory and will
          try to execute <command>$PGDATA/sync-command</command>.
-->
オンラインリカバリのファーストステージでマスタ（プライマリ）ノードで実行されるコマンドを指定します。
コマンドファイルはセキュリティ上の観点からデータベースクラスタ内に配置される必要があります。
例えば、<varname>recovery_1st_stage_command</varname> = <literal>'sync-command'</literal>となっている場合、<productname>Pgpool-II</productname>はコマンドスクリプトを<literal>$PGDATA</literal>ディレクトリの中で探し、<command>$PGDATA/sync-command</command>を起動しようとします。
        </para>
        <para>
<!--
          <varname>recovery_1st_stage_command</varname> receives following 4 parameters:
-->
<varname>recovery_1st_stage_command</varname>は次の4つの引数を受けとります。 
        </para>

        <itemizedlist>
          <listitem>
            <para>
<!--
              Path to the database cluster of the master(primary) node.
-->
マスター（プライマリ）ノードのデータベースクラスタへのパス
            </para>
          </listitem>
          <listitem>
            <para>
<!--
              Hostname of the backend node to be recovered.
-->
リカバリされるバックエンドノードのホスト名
            </para>
          </listitem>
          <listitem>
            <para>
<!--
              Path to the database cluster of the node to be recovered.
-->
リカバリされるノードのデータベースクラスタへのパス
            </para>
          </listitem>
          <listitem>
            <para>
<!--
              Port number of database to be recovered.
-->
リカバリーされるノードのポート番号
            </para>
          </listitem>
        </itemizedlist>

        <note>
          <para>
<!--
            <productname>Pgpool-II</productname> accept connections and queries
            while <varname>recovery_1st_stage command</varname> is executed,
            so you can retrieve and update data.
-->
<varname>recovery_1st_stage_command</varname>の実行中は<productname>Pgpool-II</productname>は接続やクエリを受け付けており、データの参照や更新を行うことができます。
          </para>
        </note>

        <caution>
          <para>
<!--
            <varname>recovery_1st_stage command</varname> runs as a <acronym>SQL</acronym>
            command from <productname>PostgreSQL</>'s point of view. Therefore, <varname>recovery_1st_stage_command
            </varname> can get prematuraly killed by <productname>PostgreSQL</> if
            <varname>statement_timeout</varname> is configured with the value that is
            smaller than the time <varname>recovery_1st_stage_command</varname> takes for
            completion.
-->
<varname>recovery_1st_stage_command</varname>は、<productname>PostgreSQL</>から見ると、一つの<acronym>SQL</acronym>として実行されます。
そのため、<productname>PostgreSQL</>の<varname>statement_timeout</varname>が<varname>recovery_1st_stage_command</varname>の完了にかかる時間よりも短く設定されていると、<varname>recovery_1st_stagecommand</varname>コマンドの実行が途中でキャンセルされます。
          </para>
          <para>
<!--
            Typical error in such case is
-->
典型的なエラーは以下のようなものです。
            <programlisting>
rsync used in the command is killed by signal 2 for example.
            </programlisting>
          </para>
        </caution>

        <para>
<!--
          This parameter can be changed by reloading the <productname>Pgpool-II</> configurations.
-->
このパラメータは<productname>Pgpool-II</>の設定を再読み込みすることで変更可能です。
        </para>
      </listitem>
    </varlistentry>

    <varlistentry id="guc-recovery-2nd-stage-command" xreflabel="recovery_2nd_stage_command">
      <term><varname>recovery_2nd_stage_command</varname> (<type>string</type>)
        <indexterm>
<!--
        <primary><varname>recovery_2nd_stage_command</varname> configuration parameter</primary>
-->
        <primary><varname>recovery_2nd_stage_command</varname> 設定パラメータ</primary>
        </indexterm>
      </term>
      <listitem>

        <para>
<!--
          Specifies a command file to be run by master(primary) node at the
          second stage of online recovery. The command file must be placed in the
          database cluster directory for security reasons.
          For example, if <varname>recovery_2nd_stage_command</varname> = <literal>
          'sync-command'</literal>, then <productname>Pgpool-II</productname> will
          look for the command scrit in <literal>$PGDATA</literal> directory and will
          try to execute <command>$PGDATA/sync-command</command>.
-->
オンラインリカバリのセカンドステージでマスタ（プライマリ）ノードで実行されるコマンドを指定します。
コマンドファイルはセキュリティ上の観点からデータベースクラスタ内に配置される必要があります。
例えば、<varname>recovery_2nd_stage_command</varname> = <literal>'sync-command'</literal>となっている場合、<productname>Pgpool-II</productname>はコマンドスクリプトを<literal>$PGDATA</literal>ディレクトリの中で探し、<command>$PGDATA/sync-command</command>を起動しようとします。
        </para>
        <para>
<!--
          <varname>recovery_2nd_stage_command</varname> receives following 4 parameters:
-->
<varname>recovery_2nd_stage_command</varname>は次の4つの引数を受けとります。 
        </para>

        <itemizedlist>
          <listitem>
            <para>
<!--
              Path to the database cluster of the master(primary) node.
-->
マスター（プライマリ）ノードのデータベースクラスタへのパス
            </para>
          </listitem>
          <listitem>
            <para>
<!--
              Hostname of the backend node to be recovered.
-->
リカバリされるバックエンドノードのホスト名
            </para>
          </listitem>
          <listitem>
            <para>
<!--
              Path to the database cluster of the node to be recovered.
-->
リカバリされるノードのデータベースクラスタへのパス
            </para>
          </listitem>
          <listitem>
            <para>
<!--
              Port number of the master(primary) node.
-->
マスター（プライマリ）ノードのポート番号
            </para>
          </listitem>
        </itemizedlist>

        <note>
          <para>
<!--
            <productname>Pgpool-II</productname> <emphasis>does not</emphasis>
            accept client connections and queries during the execution
            of <varname>recovery_2nd_stage_command</varname> command, and waits
            for the existing clients to close their connections before executing the
            command.
            Therefore, the <varname>recovery_2nd_stage_command</varname> may not execute
            if the client stays connected for a long time.
-->
<varname>recovery_2nd_stage_command</varname>の実行中は、<productname>Pgpool-II</productname>はクライアントからの接続およびクエリを<emphasis>受け付けません</emphasis>。
また、コマンドを実行する前に既存のクライアントが接続を閉じるのを待ちます。
そのため、長時間接続したままのクライアントがいる場合、<varname>recovery_2nd_stage_command</varname>は実行されない可能性があります。
          </para>
        </note>

        <caution>
          <para>
<!--
            <varname>recovery_2nd_stage command</varname> runs as a <acronym>SQL</acronym>
            command from PostgreSQL's point of view. Therefore, <varname>recovery_2nd_stage command
            </varname> can get prematuraly killed by PostgreSQL if the PostgreSQL's
            <varname>statement_time_out</varname> is configured with the value that is
            smaller than the time <varname>recovery_2nd_stage_command</varname> takes for
            completion.
-->
<varname>recovery_2nd_stage_command</varname>は、<productname>PostgreSQL</>から見ると、一つの<acronym>SQL</acronym>として実行されます。
そのため、<productname>PostgreSQL</>の<varname>statement_timeout</varname>が<varname>recovery_2nd_stage_command</varname>の完了にかかる時間よりも短く設定されていると、<varname>recovery_1st_stagecommand</varname>コマンドの実行が途中でキャンセルされます。
          </para>
        </caution>

        <para>
<!--
          This parameter can be changed by reloading the <productname>Pgpool-II</> configurations.
-->
このパラメータは<productname>Pgpool-II</>の設定を再読み込みすることで変更可能です。
        </para>
      </listitem>
    </varlistentry>

    <varlistentry id="guc-recovery-timeout" xreflabel="recovery_timeout">
      <term><varname>recovery_timeout</varname> (<type>integer</type>)
        <indexterm>
<!--
        <primary><varname>recovery_timeout</varname> configuration parameter</primary>
-->
        <primary><varname>recovery_timeout</varname> 設定パラメータ</primary>
        </indexterm>
      </term>
      <listitem>
        <para>
<!--
          Specifies the timeout in seconds to cancel the online recovery if it
          does not completes within this time.
          Since <productname>Pgpool-II</productname> does not accepts the connections
          during the second stage of online recovery, this parameter can be used to cancel
          the online recovery to manage the service down time during the online recovery.
-->
時間内にオンラインリカバリが完了しなかった場合に、これをキャンセルするためのタイムアウトを秒単位で指定します。
<productname>Pgpool-II</productname>は、オンラインリカバリのセカンドステージの間は接続を受け付けけないので、このパラメータはオンラインリカバリの最中のサーバがダウンした時にオンラインリカバリをキャンセルするのに使えます。
        </para>
        <para>
<!--
          This parameter can be changed by reloading the <productname>Pgpool-II</> configurations.
-->
このパラメータは<productname>Pgpool-II</>の設定を再読み込みすることで変更可能です。
        </para>
      </listitem>
    </varlistentry>

    <varlistentry id="guc-client-idle-limit-in-recovery" xreflabel="client_idle_limit_in_recovery">
      <term><varname>client_idle_limit_in_recovery</varname> (<type>integer</type>)
        <indexterm>
<!--
        <primary><varname>client_idle_limit_in_recovery</varname> configuration parameter</primary>
-->
        <primary><varname>client_idle_limit_in_recovery</varname> 設定パラメータ</primary>
        </indexterm>
      </term>
      <listitem>
        <para>
<!--
          Specifies the time in seconds to disconnect a client if it remains idle
          since the last query during the online recovery.
          <varname>client_idle_limit_in_recovery</varname> is similar to the
          <xref linkend="guc-client-idle-limit"> but only takes effect during the
          second stage of online recovery.
-->
オンラインリカバリの最中で、クライアントが前回のクエリからアイドル状態のままでいるときに、それを切断するまでの時間を秒単位で指定します。
<varname>client_idle_limit_in_recovery</varname>は<xref linkend="guc-client-idle-limit">と似ていますが、オンラインリカバリのセカンドステージでのみ効果を持ちます。
        </para>
        <para>
<!--
          This is useful for preventing the <productname>Pgpool-II</productname>
          recovery from being disturbed by the lazy clients or if the TCP/IP
          connection between the client and <productname>Pgpool-II</productname>
          is accidentally down (a cut cable for instance).
-->
これは、だらしないクライアントや<productname>Pgpool-II</productname>の間のTCP/IPコネクションの不調（例えばケーブルの切断など）によって、<productname>Pgpool-II</productname>のリカバリが邪魔されるのを防止するのに役立ちます。
        </para>
        <para>
<!--
          If set to -1, all clients get immediately disconnected when the second
          stage of online recovery starts.
          The default is 0, which turns off the feature.
-->
-1に設定すると、オンラインリカバリのセカンドステージが始まると全てのクライアントは直ちに切断されます。
デフォルト値は0で、この機能は無効です。
        </para>

        <para>
<!--
          This parameter can be changed by reloading the <productname>Pgpool-II</> configurations.
					You can also use <xref linkend="SQL-PGPOOL-SET"> command to alter the value of
					this parameter for a current session.
-->
このパラメータは<productname>Pgpool-II</>の設定を再読み込みすることで変更可能です。
現在のセッションでのパラメータ値は、<xref linkend="SQL-PGPOOL-SET">コマンドで変更することもできます。
        </para>
      </listitem>
    </varlistentry>

  </variablelist>
</sect1>
