@@ -724,7 +724,72 @@ test ! -f /mnt/server/archivedir/00000001000000A900000065 && cp pg_xlog/
724724 <title>Making a Base Backup</title>
725725
726726 <para>
727- The procedure for making a base backup is relatively simple:
727+ The easiest way to perform a base backup is to use the
728+ <xref linkend="app-pgbasebackup"> tool. It can create
729+ a base backup either as regular files or as a tar archive. If more
730+ flexibility than <xref linkend="app-pgbasebackup"> can provide is
731+ required, you can also make a base backup using the low level API
732+ (see <xref linkend="backup-lowlevel-base-backup">).
733+ </para>
734+
735+ <para>
736+ It is not necessary to be concerned about the amount of time it takes
737+ to make a base backup. However, if you normally run the
738+ server with <varname>full_page_writes</> disabled, you might notice a drop
739+ in performance while the backup runs since <varname>full_page_writes</> is
740+ effectively forced on during backup mode.
741+ </para>
742+
743+ <para>
744+ To make use of the backup, you will need to keep all the WAL
745+ segment files generated during and after the file system backup.
746+ To aid you in doing this, the base backup process
747+ creates a <firstterm>backup history file</> that is immediately
748+ stored into the WAL archive area. This file is named after the first
749+ WAL segment file that you need for the file system backup.
750+ For example, if the starting WAL file is
751+ <literal>0000000100001234000055CD</> the backup history file will be
752+ named something like
753+ <literal>0000000100001234000055CD.007C9330.backup</>. (The second
754+ part of the file name stands for an exact position within the WAL
755+ file, and can ordinarily be ignored.) Once you have safely archived
756+ the file system backup and the WAL segment files used during the
757+ backup (as specified in the backup history file), all archived WAL
758+ segments with names numerically less are no longer needed to recover
759+ the file system backup and can be deleted. However, you should
760+ consider keeping several backup sets to be absolutely certain that
761+ you can recover your data.
762+ </para>
763+
764+ <para>
765+ The backup history file is just a small text file. It contains the
766+ label string you gave to <xref linkend="app-pgbasebackup">, as well as
767+ the starting and ending times and WAL segments of the backup.
768+ If you used the label to identify the associated dump file,
769+ then the archived history file is enough to tell you which dump file to
770+ restore.
771+ </para>
772+
773+ <para>
774+ Since you have to keep around all the archived WAL files back to your
775+ last base backup, the interval between base backups should usually be
776+ chosen based on how much storage you want to expend on archived WAL
777+ files. You should also consider how long you are prepared to spend
778+ recovering, if recovery should be necessary — the system will have to
779+ replay all those WAL segments, and that could take awhile if it has
780+ been a long time since the last base backup.
781+ </para>
782+ </sect2>
783+
784+ <sect2 id="backup-lowlevel-base-backup">
785+ <title>Making a Base Backup Using the Low Level API</title>
786+ <para>
787+ The procedure for making a base backup using the low level
788+ APIs contains a few more steps than
789+ the <xref linkend="app-pgbasebackup"> method, but is relatively
790+ simple. It is very important that these steps are executed in
791+ sequence, and that the success of a step is verified before
792+ proceeding to the next step.
728793 <orderedlist>
729794 <listitem>
730795 <para>
@@ -813,17 +878,6 @@ SELECT pg_stop_backup();
813878 </orderedlist>
814879 </para>
815880
816- <para>
817- You can also use the <xref linkend="app-pgbasebackup"> tool to take
818- the backup, instead of manually copying the files. This tool will do
819- the equivalent of <function>pg_start_backup()</>, copy and
820- <function>pg_stop_backup()</> steps automatically, and transfers the
821- backup over a regular <productname>PostgreSQL</productname> connection
822- using the replication protocol, instead of requiring file system level
823- access. <command>pg_basebackup</command> does not interfere with file system level backups
824- taken using <function>pg_start_backup()</>/<function>pg_stop_backup()</>.
825- </para>
826-
827881 <para>
828882 Some file system backup tools emit warnings or errors
829883 if the files they are trying to copy change while the copy proceeds.
@@ -842,19 +896,6 @@ SELECT pg_stop_backup();
842896 --warning=no-file-removed</literal> to hide the related warning messages.
843897 </para>
844898
845- <para>
846- It is not necessary to be concerned about the amount of time elapsed
847- between <function>pg_start_backup</> and the start of the actual backup,
848- nor between the end of the backup and <function>pg_stop_backup</>; a
849- few minutes' delay won't hurt anything. (However, if you normally run the
850- server with <varname>full_page_writes</> disabled, you might notice a drop
851- in performance between <function>pg_start_backup</> and
852- <function>pg_stop_backup</>, since <varname>full_page_writes</> is
853- effectively forced on during backup mode.) You must ensure that these
854- steps are carried out in sequence, without any possible
855- overlap, or you will invalidate the backup.
856- </para>
857-
858899 <para>
859900 Be certain that your backup dump includes all of the files under
860901 the database cluster directory (e.g., <filename>/usr/local/pgsql/data</>).
@@ -878,46 +919,6 @@ SELECT pg_stop_backup();
878919 (These files can confuse <application>pg_ctl</>.)
879920 </para>
880921
881- <para>
882- To make use of the backup, you will need to keep all the WAL
883- segment files generated during and after the file system backup.
884- To aid you in doing this, the <function>pg_stop_backup</> function
885- creates a <firstterm>backup history file</> that is immediately
886- stored into the WAL archive area. This file is named after the first
887- WAL segment file that you need for the file system backup.
888- For example, if the starting WAL file is
889- <literal>0000000100001234000055CD</> the backup history file will be
890- named something like
891- <literal>0000000100001234000055CD.007C9330.backup</>. (The second
892- part of the file name stands for an exact position within the WAL
893- file, and can ordinarily be ignored.) Once you have safely archived
894- the file system backup and the WAL segment files used during the
895- backup (as specified in the backup history file), all archived WAL
896- segments with names numerically less are no longer needed to recover
897- the file system backup and can be deleted. However, you should
898- consider keeping several backup sets to be absolutely certain that
899- you can recover your data.
900- </para>
901-
902- <para>
903- The backup history file is just a small text file. It contains the
904- label string you gave to <function>pg_start_backup</>, as well as
905- the starting and ending times and WAL segments of the backup.
906- If you used the label to identify the associated dump file,
907- then the archived history file is enough to tell you which dump file to
908- restore.
909- </para>
910-
911- <para>
912- Since you have to keep around all the archived WAL files back to your
913- last base backup, the interval between base backups should usually be
914- chosen based on how much storage you want to expend on archived WAL
915- files. You should also consider how long you are prepared to spend
916- recovering, if recovery should be necessary — the system will have to
917- replay all those WAL segments, and that could take awhile if it has
918- been a long time since the last base backup.
919- </para>
920-
921922 <para>
922923 It's also worth noting that the <function>pg_start_backup</> function
923924 makes a file named <filename>backup_label</> in the database cluster
@@ -1214,7 +1215,18 @@ restore_command = 'cp /mnt/server/archivedir/%f %p'
12141215 </para>
12151216
12161217 <para>
1217- To prepare for standalone hot backups, set <varname>wal_level</> to
1218+ As with base backups, the easiest way to produce a standalone
1219+ hot backup is to use the <xref linkend="app-pgbasebackup">
1220+ tool. If you include the <literal>-X</> parameter when calling
1221+ it, all the transaction log required to use the backup will be
1222+ included in the backup automatically, and no special action is
1223+ required to restore the backup.
1224+ </para>
1225+
1226+ <para>
1227+ If more flexibility in copying the backup files is needed, a lower
1228+ level process can be used for standalone hot backups as well.
1229+ To prepare for low level standalone hot backups, set <varname>wal_level</> to
12181230 <literal>archive</> (or <literal>hot_standby</>), <varname>archive_mode</> to
12191231 <literal>on</>, and set up an <varname>archive_command</> that performs
12201232 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/
12461258 Please remember to add error handling to your backup scripts.
12471259 </para>
12481260
1261+ </sect3>
1262+
1263+ <sect3 id="compressed-archive-logs">
1264+ <title>Compressed Archive Logs</title>
1265+
12491266 <para>
12501267 If archive storage size is a concern, you can use
12511268 <application>gzip</application> to compress the archive files: