Just some docs enhancements based on feedback I received from a few recent
talks on PITR.
Thanks,
Gavin
--- doc/src/sgml/backup.sgml
+++ doc/src/sgml/backup.sgml
@@ -379,7 +379,7 @@
</sect1>
<sect1 id="backup-online">
- <title>On-line backup and point-in-time recovery</title>
+ <title>On-line backup and point-in-time recovery (PITR)</title>
<indexterm zone="backup">
<primary>on-line backup</primary>
@@ -389,9 +389,14 @@
<primary>point-in-time recovery</primary>
</indexterm>
+ <indexterm zone="backup">
+ <primary>PITR</primary>
+ </indexterm>
+
<para>
At all times, <productname>PostgreSQL</> maintains a <firstterm>write ahead
- log</> (WAL) that shows details of every change made to the database's data
+ log</> (WAL) in the <filename>pg_xlog/</> directory under the cluster data
+ directory. The log shows details of every change made to the database's data
files. This log exists primarily for crash-safety purposes: if the system
crashes, the database can be restored to consistency by <quote>replaying</>
the log entries made since the last checkpoint. However, the existence
@@ -481,7 +486,8 @@
file is recycled for reuse. Depending on the application and the
available hardware, there could be many different ways of <quote>saving
the data somewhere</>: we could copy the segment files to an NFS-mounted
- directory on another machine, or write them onto a tape drive, or batch
+ directory on another machine, write them onto a tape drive (ensuring that
+ you have a way of restoring the file with its original file name), or batch
them together and burn them onto CDs, or something else entirely. To
provide the database administrator with as much flexibility as possible,
<productname>PostgreSQL</> tries not to make any assumptions about how
@@ -600,6 +601,14 @@
remember the original full path (<literal>%p</>) but it is necessary to
remember the file name (<literal>%f</>).
</para>
+
+ <para>
+ Note that although WAL archiving will allow you to restore any
+ modifications made to the data in your <productname>PostgreSQL</> database
+ it will not restore changes made to configuration files (that is,
+ <filename>postgresql.conf</>, <filename>pg_hba.conf</> and
+ <filename>pg_ident.conf</>) after the initial base backup.
+ </para>
</sect2>
<sect2 id="backup-base-backup">
@@ -620,10 +628,16 @@
SELECT pg_start_backup('label');
</programlisting>
where <literal>label</> is any string you want to use to uniquely
- identify this backup operation. (One good practice is to use the
- full path where you intend to put the backup dump file.) It does
- not matter which database within the cluster you connect to to issue
- this command. You can ignore the result returned by the function;
+ identify this backup operation. <function>pg_start_backup</> creates
+ a <firstterm>backup label</> file, called <filename>backup_label</>,
+ in the cluster directory with information about your backup.
+ One good practice is to use the full path where you intend to put the
+ backup dump file as.
+ </para>
+
+ <para>
+ It does not matter which database within the cluster you connect to to
+ issue this command. You can ignore the result returned by the function;
but if it reports an error, deal with that before proceeding.
</para>
</listitem>
@@ -738,13 +744,20 @@
<orderedlist>
<listitem>
<para>
- Stop the postmaster, if it's running, and clean out all existing files
- under the cluster data directory and under the root directories of any
- tablespaces you are using.
- (If there are recent, unarchived WAL segment files in
- <filename>pg_xlog/</> that you want to use during restore, move these
aside
- instead of removing them.)
+ Stop the postmaster, if it's running. If you have the space to do so,
+ copy the cluster data directory and any tablespacecs to a temporary
+ location so that you can reference them later. Note that this will
+ require that you have enough free space on your system to hold two
+ copies of your existing database. If you do not have enough space,
+ you need at the least to backup the <filename>pg_xlog</> directory in
+ the cluster data directory as it may contain logs which were not archived
+ before the system went down.
</para>
+
+ <para>
+ Next, clean out all existing files under the cluster data directory and
+ under the root directories of any tablespaces you are using.
+ </para>
</listitem>
<listitem>
<para>
@@ -766,7 +773,7 @@
</listitem>
<listitem>
<para>
- If you had unarchived WAL segment files that you saved aside in step 1,
+ If you had unarchived WAL segment files that you saved in step 1,
copy them into <filename>pg_xlog/</>. (It's best to copy them, not move
them back in, so that you still have the unmodified files if the worst
happens and you have to start over.)
@@ -775,9 +775,9 @@
<listitem>
<para>
Create a recovery command file <filename>recovery.conf</> in the cluster
- data directory, as discussed below. You may also want to temporarily
- modify <filename>pg_hba.conf</> to prevent ordinary users from connecting
- until you are sure the recovery has worked.
+ data directory (see <xref linkend="recovery-config-settings">). You may
+ also want to temporarily modify <filename>pg_hba.conf</> to prevent
+ ordinary users from connecting until you are sure the recovery has worked.
</para>
</listitem>
<listitem>
@@ -862,7 +862,7 @@
and roll forward from there.)
</para>
- <sect3 id="recovery-config-settings">
+ <sect3 id="recovery-config-settings" xreflabel="Recovery Settings">
<title>Recovery Settings</title>
<para>
@@ -996,7 +996,7 @@
Tuesday evening, and are up and running. In <emphasis>this</> history of
the database universe, you never dropped the table at all. But suppose
you later realize this wasn't such a great idea after all, and would like
- to return to some later point in the original history? You won't be able
+ to return to some later point in the original history. You won't be able
to if, while your database was up-and-running, it overwrote some of the
sequence of WAL segment files that led up to the time you now wish you
could get back to. So you really want to distinguish the series of
---------------------------(end of broadcast)---------------------------
TIP 4: Don't 'kill -9' the postmaster
