mirrors
/
postgres
mirror of https://github.com/postgres/postgres
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Reorder basebackup options, to list pg_basebackup first 

Since this is the easy way of doing it, it should be listed first. All
the old information is retained for those who want the more advanced way.

Also adds a subheading for compressing logs, that seems to have been missing
This commit is contained in:
Magnus Hagander 2012-06-17 21:18:02 +08:00
parent a22cba0e6c
commit 3cdd19b0a6
1 changed files with 83 additions and 66 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

149
doc/src/sgml/backup.sgml
View File

@ -724,7 +724,72 @@ test ! -f /mnt/server/archivedir/00000001000000A900000065 && cp pg_xlog/
<title>Making a Base Backup</title>
<para>
The procedure for making a base backup is relatively simple:
The easiest way to perform a base backup is to use the
<xref linkend="app-pgbasebackup"> tool. It can create
a base backup either as regular files or as a tar archive. If more
flexibility than <xref linkend="app-pgbasebackup"> can provide is
required, you can also make a base backup using the low level API
(see <xref linkend="backup-lowlevel-base-backup">).
</para>
<para>
It is not necessary to be concerned about the amount of time it takes
to make a base backup. However, if you normally run the
server with <varname>full_page_writes</> disabled, you might notice a drop
in performance while the backup runs since <varname>full_page_writes</> is
effectively forced on during backup mode.
</para>
<para>
To make use of the backup, you will need to keep all the WAL
segment files generated during and after the file system backup.
To aid you in doing this, the base backup process
creates a <firstterm>backup history file</> that is immediately
stored into the WAL archive area. This file is named after the first
WAL segment file that you need for the file system backup.
For example, if the starting WAL file is
<literal>0000000100001234000055CD</> the backup history file will be
named something like
<literal>0000000100001234000055CD.007C9330.backup</>. (The second
part of the file name stands for an exact position within the WAL
file, and can ordinarily be ignored.) Once you have safely archived
the file system backup and the WAL segment files used during the
backup (as specified in the backup history file), all archived WAL
segments with names numerically less are no longer needed to recover
the file system backup and can be deleted. However, you should
consider keeping several backup sets to be absolutely certain that
you can recover your data.
</para>
<para>
The backup history file is just a small text file. It contains the
label string you gave to <xref linkend="app-pgbasebackup">, as well as
the starting and ending times and WAL segments of the backup.
If you used the label to identify the associated dump file,
then the archived history file is enough to tell you which dump file to
restore.
</para>
<para>
Since you have to keep around all the archived WAL files back to your
last base backup, the interval between base backups should usually be
chosen based on how much storage you want to expend on archived WAL
files. You should also consider how long you are prepared to spend
recovering, if recovery should be necessary &mdash; the system will have to
replay all those WAL segments, and that could take awhile if it has
been a long time since the last base backup.
</para>
</sect2>
<sect2 id="backup-lowlevel-base-backup">
<title>Making a Base Backup Using the Low Level API</title>
<para>
The procedure for making a base backup using the low level
APIs contains a few more steps than
the <xref linkend="app-pgbasebackup"> method, but is relatively
simple. It is very important that these steps are executed in
sequence, and that the success of a step is verified before
proceeding to the next step.
<orderedlist>
<listitem>
<para>
@ -813,17 +878,6 @@ SELECT pg_stop_backup();
</orderedlist>
</para>
<para>
You can also use the <xref linkend="app-pgbasebackup"> tool to take
the backup, instead of manually copying the files. This tool will do
the equivalent of <function>pg_start_backup()</>, copy and
<function>pg_stop_backup()</> steps automatically, and transfers the
backup over a regular <productname>PostgreSQL</productname> connection
using the replication protocol, instead of requiring file system level
access. <command>pg_basebackup</command> does not interfere with file system level backups
taken using <function>pg_start_backup()</>/<function>pg_stop_backup()</>.
</para>
<para>
Some file system backup tools emit warnings or errors
if the files they are trying to copy change while the copy proceeds.
@ -842,19 +896,6 @@ SELECT pg_stop_backup();
--warning=no-file-removed</literal> to hide the related warning messages.
</para>
<para>
It is not necessary to be concerned about the amount of time elapsed
between <function>pg_start_backup</> and the start of the actual backup,
nor between the end of the backup and <function>pg_stop_backup</>; a
few minutes' delay won't hurt anything. (However, if you normally run the
server with <varname>full_page_writes</> disabled, you might notice a drop
in performance between <function>pg_start_backup</> and
<function>pg_stop_backup</>, since <varname>full_page_writes</> is
effectively forced on during backup mode.) You must ensure that these
steps are carried out in sequence, without any possible
overlap, or you will invalidate the backup.
</para>
<para>
Be certain that your backup dump includes all of the files under
the database cluster directory (e.g., <filename>/usr/local/pgsql/data</>).
@ -878,46 +919,6 @@ SELECT pg_stop_backup();
(These files can confuse <application>pg_ctl</>.)
</para>
<para>
To make use of the backup, you will need to keep all the WAL
segment files generated during and after the file system backup.
To aid you in doing this, the <function>pg_stop_backup</> function
creates a <firstterm>backup history file</> that is immediately
stored into the WAL archive area. This file is named after the first
WAL segment file that you need for the file system backup.
For example, if the starting WAL file is
<literal>0000000100001234000055CD</> the backup history file will be
named something like
<literal>0000000100001234000055CD.007C9330.backup</>. (The second
part of the file name stands for an exact position within the WAL
file, and can ordinarily be ignored.) Once you have safely archived
the file system backup and the WAL segment files used during the
backup (as specified in the backup history file), all archived WAL
segments with names numerically less are no longer needed to recover
the file system backup and can be deleted. However, you should
consider keeping several backup sets to be absolutely certain that
you can recover your data.
</para>
<para>
The backup history file is just a small text file. It contains the
label string you gave to <function>pg_start_backup</>, as well as
the starting and ending times and WAL segments of the backup.
If you used the label to identify the associated dump file,
then the archived history file is enough to tell you which dump file to
restore.
</para>
<para>
Since you have to keep around all the archived WAL files back to your
last base backup, the interval between base backups should usually be
chosen based on how much storage you want to expend on archived WAL
files. You should also consider how long you are prepared to spend
recovering, if recovery should be necessary &mdash; the system will have to
replay all those WAL segments, and that could take awhile if it has
been a long time since the last base backup.
</para>
<para>
It's also worth noting that the <function>pg_start_backup</> function
makes a file named <filename>backup_label</> in the database cluster
@ -1214,7 +1215,18 @@ restore_command = 'cp /mnt/server/archivedir/%f %p'
</para>
<para>
To prepare for standalone hot backups, set <varname>wal_level</> to
As with base backups, the easiest way to produce a standalone
hot backup is to use the <xref linkend="app-pgbasebackup">
tool. If you include the <literal>-X</> parameter when calling
it, all the transaction log required to use the backup will be
included in the backup automatically, and no special action is
required to restore the backup.
</para>
<para>
If more flexibility in copying the backup files is needed, a lower
level process can be used for standalone hot backups as well.
To prepare for low level standalone hot backups, set <varname>wal_level</> to
<literal>archive</> (or <literal>hot_standby</>), <varname>archive_mode</> to
<literal>on</>, and set up an <varname>archive_command</> that performs
archiving only when a <emphasis>switch file</> exists. For example:
@ -1246,6 +1258,11 @@ tar -rf /var/lib/pgsql/backup.tar /var/lib/pgsql/archive/
Please remember to add error handling to your backup scripts.
</para>
</sect3>
<sect3 id="compressed-archive-logs">
<title>Compressed Archive Logs</title>
<para>
If archive storage size is a concern, you can use
<application>gzip</application> to compress the archive files: