<!-- $PostgreSQL: pgsql/doc/src/sgml/backup.sgml,v 2.142 2010/02/19 00:15:25 momjian Exp $ -->

<!-- $PostgreSQL: pgsql/doc/src/sgml/backup.sgml,v 2.143 2010/02/22 11:47:30 heikki Exp $ -->

<chapter id="backup">

<title>Backup and Restore</title>

<listitem>

<para>

Create a recovery command file <filename>recovery.conf</> in the cluster

data directory (see <xref linkend="recovery-config-settings">). You might

data directory (see <xref linkend="recovery-config">). You might

also want to temporarily modify <filename>pg_hba.conf</> to prevent

ordinary users from connecting until you are sure the recovery was successful.

</para>

WAL data need not be scanned again.

</para>

<sect3 id="recovery-config-settings" xreflabel="Recovery Settings">

<title>Recovery Settings</title>

<para>

These settings can only be made in the <filename>recovery.conf</>

file, and apply only for the duration of the recovery. (A sample file,

<filename>share/recovery.conf.sample</>, exists in the installation's

<filename>share/</> directory.) They must be

reset for any subsequent recovery you wish to perform. They cannot be

changed once recovery has begun.

The parameters for streaming replication are described in <xref

linkend="replication-config-settings">.

</para>

<variablelist>

<varlistentry id="restore-command" xreflabel="restore_command">

<term><varname>restore_command</varname> (<type>string</type>)</term>

<listitem>

<para>

The shell command to execute to retrieve an archived segment of

the WAL file series. This parameter is required for archive recovery,

but optional for streaming replication.

Any <literal>%f</> in the string is

replaced by the name of the file to retrieve from the archive,

and any <literal>%p</> is replaced by the copy destination path name

on the server.

(The path name is relative to the current working directory,

i.e., the cluster's data directory.)

Any <literal>%r</> is replaced by the name of the file containing the

last valid restart point. That is the earliest file that must be kept

to allow a restore to be restartable, so this information can be used

to truncate the archive to just the minimum required to support

restarting from the current restore. <literal>%r</> is typically only

used by warm-standby configurations

(see <xref linkend="warm-standby">).

Write <literal>%%</> to embed an actual <literal>%</> character.

</para>

<para>

It is important for the command to return a zero exit status

only if it succeeds. The command <emphasis>will</> be asked for file

names that are not present in the archive; it must return nonzero

when so asked. Examples:

<programlisting>

restore_command = 'cp /mnt/server/archivedir/%f "%p"'

restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"' # Windows

</programlisting>

</para>

</listitem>

</varlistentry>

<varlistentry id="recovery-end-command" xreflabel="recovery_end_command">

<term><varname>recovery_end_command</varname> (<type>string</type>)</term>

<listitem>

<para>

This parameter specifies a shell command that will be executed once only

at the end of recovery. This parameter is optional. The purpose of the

<varname>recovery_end_command</> is to provide a mechanism for cleanup

following replication or recovery.

Any <literal>%r</> is replaced by the name of the file

containing the last valid restart point. That is the earliest file that

must be kept to allow a restore to be restartable, so this information

can be used to truncate the archive to just the minimum required to

support restart from the current restore. <literal>%r</> would

typically be used in a warm-standby configuration

(see <xref linkend="warm-standby">).

Write <literal>%%</> to embed an actual <literal>%</> character

in the command.

</para>

<para>

If the command returns a non-zero exit status then a WARNING log

message will be written and the database will proceed to start up

anyway. An exception is that if the command was terminated by a

signal, the database will not proceed with startup.

</para>

</listitem>

</varlistentry>

<varlistentry id="recovery-target-time" xreflabel="recovery_target_time">

<term><varname>recovery_target_time</varname>

(<type>timestamp</type>)

</term>

<listitem>

<para>

This parameter specifies the time stamp up to which recovery

will proceed.

At most one of <varname>recovery_target_time</> and

<xref linkend="recovery-target-xid"> can be specified.

The default is to recover to the end of the WAL log.

The precise stopping point is also influenced by

<xref linkend="recovery-target-inclusive">.

</para>

</listitem>

</varlistentry>

<varlistentry id="recovery-target-xid" xreflabel="recovery_target_xid">

<term><varname>recovery_target_xid</varname> (<type>string</type>)</term>

<listitem>

<para>

This parameter specifies the transaction ID up to which recovery

will proceed. Keep in mind

that while transaction IDs are assigned sequentially at transaction

start, transactions can complete in a different numeric order.

The transactions that will be recovered are those that committed

before (and optionally including) the specified one.

At most one of <varname>recovery_target_xid</> and

<xref linkend="recovery-target-time"> can be specified.

The default is to recover to the end of the WAL log.

The precise stopping point is also influenced by

<xref linkend="recovery-target-inclusive">.

</para>

</listitem>

</varlistentry>

<varlistentry id="recovery-target-inclusive"

xreflabel="recovery_target_inclusive">

<term><varname>recovery_target_inclusive</varname>

(<type>boolean</type>)

</term>

<listitem>

<para>

Specifies whether we stop just after the specified recovery target

(<literal>true</literal>), or just before the recovery target

(<literal>false</literal>).

Applies to both <xref linkend="recovery-target-time">

and <xref linkend="recovery-target-xid">, whichever one is

specified for this recovery. This indicates whether transactions

having exactly the target commit time or ID, respectively, will

be included in the recovery. Default is <literal>true</>.

</para>

</listitem>

</varlistentry>

<varlistentry id="recovery-target-timeline"

xreflabel="recovery_target_timeline">

<term><varname>recovery_target_timeline</varname>

(<type>string</type>)

</term>

<listitem>

<para>

Specifies recovering into a particular timeline. The default is

to recover along the same timeline that was current when the

base backup was taken. You only need to set this parameter

in complex re-recovery situations, where you need to return to

a state that itself was reached after a point-in-time recovery.

See <xref linkend="backup-timelines"> for discussion.

</para>

</listitem>

</varlistentry>

</variablelist>

</sect3>

</sect2>

<sect2 id="backup-timelines">

<!-- $PostgreSQL: pgsql/doc/src/sgml/filelist.sgml,v 1.66 2010/02/17 04:19:37 tgl Exp $ -->

<!-- $PostgreSQL: pgsql/doc/src/sgml/filelist.sgml,v 1.67 2010/02/22 11:47:30 heikki Exp $ -->

<!entity history SYSTEM "history.sgml">

<!entity info SYSTEM "info.sgml">

<!entity manage-ag SYSTEM "manage-ag.sgml">

<!entity monitoring SYSTEM "monitoring.sgml">

<!entity regress SYSTEM "regress.sgml">

<!entity recovery-config SYSTEM "recovery-config.sgml">

<!entity runtime SYSTEM "runtime.sgml">

<!entity config SYSTEM "config.sgml">

<!entity user-manag SYSTEM "user-manag.sgml">

<!-- $PostgreSQL: pgsql/doc/src/sgml/high-availability.sgml,v 1.48 2010/02/20 10:07:27 sriggs Exp $ -->

<!-- $PostgreSQL: pgsql/doc/src/sgml/high-availability.sgml,v 1.49 2010/02/22 11:47:30 heikki Exp $ -->

<chapter id="high-availability">

<title>High Availability, Load Balancing, and Replication</title>

<listitem>

<para>

Create a recovery command file <filename>recovery.conf</> in the data

directory on the standby server.

directory on the standby server. Set <varname>restore_command</varname>

as you would in normal recovery from a continuous archiving backup

(see <xref linkend="backup-pitr-recovery">). <literal>pg_standby</> or

similar tools that wait for the next WAL file to arrive cannot be used

with streaming replication, as the server handles retries and waiting

itself. Enable <varname>standby_mode</varname>. Set

<varname>primary_conninfo</varname> to point to the primary server.

</para>

<variablelist id="replication-config-settings" xreflabel="Replication Settings">

<varlistentry id="standby-mode" xreflabel="standby_mode">

<term><varname>standby_mode</varname> (<type>boolean</type>)</term>

<listitem>

<para>

Specifies whether to start the <productname>PostgreSQL</> server as

a standby. If this parameter is <literal>on</>, the server will

not end recovery when the end of archived WAL is reached, but

will keep trying to continue recovery using <varname>restore_command</>

and by connecting to the primary server as specified by the

<varname>primary_conninfo</> setting.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><varname>restore_command</varname> (<type>string</type>)</term>

<term><varname>restore_end_command</varname> (<type>string</type>)</term>

<listitem>

<para>

With <varname>standby_mode</> enabled, <varname>restore_command</>

(and <varname>restore_end_command</>) should be set to a

simple command or script like in PITR. <literal>pg_standby</> or similar tools

that wait for the next WAL file to arrive cannot be used with

streaming replication, as the server handles retries and waiting

itself. Set <varname>restore_command</> as you would if you were

recovering using a Continuous archiving backup (see <xref linkend="backup-pitr-recovery">).

</para>

</listitem>

</varlistentry>

<varlistentry id="primary-conninfo" xreflabel="primary_conninfo">

<term><varname>primary_conninfo</varname> (<type>string</type>)</term>

<listitem>

<para>

Specifies a connection string to be used for the standby server

to connect with the primary. This string is in the same format as

described in <xref linkend="libpq-connect">. If any option is

unspecified in this string, then the corresponding environment

variable (see <xref linkend="libpq-envars">) is checked. If the

environment variable is not set either, then

defaults are used.

</para>

<para>

The built-in replication requires that a host name (or host address)

or port number which the primary server listens on be

specified in this string. Also ensure that a role with

the <literal>SUPERUSER</> and <literal>LOGIN</> privileges on the

primary is set (see

<xref linkend="streaming-replication-authentication">). Note that

the password needs to be set if the primary demands password

authentication.

</para>

<para>

This setting has no effect if <varname>standby_mode</> is <literal>off</>.

</para>

</listitem>

</varlistentry>

<varlistentry id="trigger-file" xreflabel="trigger_file">

<term><varname>trigger_file</varname> (<type>string</type>)</term>

<listitem>

<para>

Specifies a trigger file whose presence ends recovery in the

standby. If no trigger file is specified, the standby never exits

recovery.

This setting has no effect if <varname>standby_mode</> is <literal>off</>.

</para>

</listitem>

</varlistentry>

</variablelist>

</listitem>

<listitem>

<para>

<!-- $PostgreSQL: pgsql/doc/src/sgml/postgres.sgml,v 1.90 2009/08/04 22:04:37 petere Exp $ -->

<!-- $PostgreSQL: pgsql/doc/src/sgml/postgres.sgml,v 1.91 2010/02/22 11:47:30 heikki Exp $ -->

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.2//EN" [

&maintenance;

&backup;

&high-availability;

&recovery-config;

&monitoring;

&diskusage;

&wal;