Skip to content

Commit 0c5a533

Browse files
bloghCommitfest Bot
blogh
authored and
Commitfest Bot
committed
Reorganize the backup section
The standalone backup of the backup documentation lacks visibility. The solution described in the file level backup section, while still usable, is not the preferred method. This patch attempts to remedy this by moving things around.
1 parent c9e38a5 commit 0c5a533

File tree

1 file changed

+139
-139
lines changed

1 file changed

+139
-139
lines changed

‎doc/src/sgml/backup.sgml‎

Lines changed: 139 additions & 139 deletions
Original file line numberDiff line numberDiff line change
@@ -354,124 +354,8 @@ pg_dump -j <replaceable class="parameter">num</replaceable> -F d -f <replaceable
354354
</sect2>
355355
</sect1>
356356

357-
<sect1 id="backup-file">
358-
<title>File System Level Backup</title>
359-
360-
<para>
361-
An alternative backup strategy is to directly copy the files that
362-
<productname>PostgreSQL</productname> uses to store the data in the database;
363-
<xref linkend="creating-cluster"/> explains where these files
364-
are located. You can use whatever method you prefer
365-
for doing file system backups; for example:
366-
367-
<programlisting>
368-
tar -cf backup.tar /usr/local/pgsql/data
369-
</programlisting>
370-
</para>
371-
372-
<para>
373-
There are two restrictions, however, which make this method
374-
impractical, or at least inferior to the <application>pg_dump</application>
375-
method:
376-
377-
<orderedlist>
378-
<listitem>
379-
<para>
380-
The database server <emphasis>must</emphasis> be shut down in order to
381-
get a usable backup. Half-way measures such as disallowing all
382-
connections will <emphasis>not</emphasis> work
383-
(in part because <command>tar</command> and similar tools do not take
384-
an atomic snapshot of the state of the file system,
385-
but also because of internal buffering within the server).
386-
Information about stopping the server can be found in
387-
<xref linkend="server-shutdown"/>. Needless to say, you
388-
also need to shut down the server before restoring the data.
389-
</para>
390-
</listitem>
391-
392-
<listitem>
393-
<para>
394-
If you have dug into the details of the file system layout of the
395-
database, you might be tempted to try to back up or restore only certain
396-
individual tables or databases from their respective files or
397-
directories. This will <emphasis>not</emphasis> work because the
398-
information contained in these files is not usable without
399-
the commit log files,
400-
<filename>pg_xact/*</filename>, which contain the commit status of
401-
all transactions. A table file is only usable with this
402-
information. Of course it is also impossible to restore only a
403-
table and the associated <filename>pg_xact</filename> data
404-
because that would render all other tables in the database
405-
cluster useless. So file system backups only work for complete
406-
backup and restoration of an entire database cluster.
407-
</para>
408-
</listitem>
409-
</orderedlist>
410-
</para>
411-
412-
<para>
413-
An alternative file-system backup approach is to make a
414-
<quote>consistent snapshot</quote> of the data directory, if the
415-
file system supports that functionality (and you are willing to
416-
trust that it is implemented correctly). The typical procedure is
417-
to make a <quote>frozen snapshot</quote> of the volume containing the
418-
database, then copy the whole data directory (not just parts, see
419-
above) from the snapshot to a backup device, then release the frozen
420-
snapshot. This will work even while the database server is running.
421-
However, a backup created in this way saves
422-
the database files in a state as if the database server was not
423-
properly shut down; therefore, when you start the database server
424-
on the backed-up data, it will think the previous server instance
425-
crashed and will replay the WAL log. This is not a problem; just
426-
be aware of it (and be sure to include the WAL files in your backup).
427-
You can perform a <command>CHECKPOINT</command> before taking the
428-
snapshot to reduce recovery time.
429-
</para>
430-
431-
<para>
432-
If your database is spread across multiple file systems, there might not
433-
be any way to obtain exactly-simultaneous frozen snapshots of all
434-
the volumes. For example, if your data files and WAL log are on different
435-
disks, or if tablespaces are on different file systems, it might
436-
not be possible to use snapshot backup because the snapshots
437-
<emphasis>must</emphasis> be simultaneous.
438-
Read your file system documentation very carefully before trusting
439-
the consistent-snapshot technique in such situations.
440-
</para>
441-
442-
<para>
443-
If simultaneous snapshots are not possible, one option is to shut down
444-
the database server long enough to establish all the frozen snapshots.
445-
Another option is to perform a continuous archiving base backup (<xref
446-
linkend="backup-base-backup"/>) because such backups are immune to file
447-
system changes during the backup. This requires enabling continuous
448-
archiving just during the backup process; restore is done using
449-
continuous archive recovery (<xref linkend="backup-pitr-recovery"/>).
450-
</para>
451-
452-
<para>
453-
Another option is to use <application>rsync</application> to perform a file
454-
system backup. This is done by first running <application>rsync</application>
455-
while the database server is running, then shutting down the database
456-
server long enough to do an <command>rsync --checksum</command>.
457-
(<option>--checksum</option> is necessary because <command>rsync</command> only
458-
has file modification-time granularity of one second.) The
459-
second <application>rsync</application> will be quicker than the first,
460-
because it has relatively little data to transfer, and the end result
461-
will be consistent because the server was down. This method
462-
allows a file system backup to be performed with minimal downtime.
463-
</para>
464-
465-
<para>
466-
Note that a file system backup will typically be larger
467-
than an SQL dump. (<application>pg_dump</application> does not need to dump
468-
the contents of indexes for example, just the commands to recreate
469-
them.) However, taking a file system backup might be faster.
470-
</para>
471-
</sect1>
472-
473357
<sect1 id="continuous-archiving">
474-
<title>Continuous Archiving and Point-in-Time Recovery (PITR)</title>
358+
<title>Physical Backups Using Continuous Archiving</title>
475359

476360
<indexterm zone="backup">
477361
<primary>continuous archiving</primary>
@@ -569,6 +453,28 @@ tar -cf backup.tar /usr/local/pgsql/data
569453
archiving WAL files.
570454
</para>
571455

456+
<sect2 id="backup-standalone">
457+
<title>Built-In Standalone Backups</title>
458+
459+
<para>
460+
If all you want is a standalone backup, it is possible to use <productname>
461+
PostgreSQL</productname>'s backup facilities to produce standalone hot backups.
462+
These are backups that cannot be used for point-in-time recovery, yet are
463+
typically much faster to backup and restore than <application>pg_dump</application>
464+
dumps. (They are also much larger than <application>pg_dump</application> dumps,
465+
so in some cases the speed advantage might be negated.)
466+
</para>
467+
468+
<para>
469+
The easiest way to produce a standalone
470+
hot backup is to use the <xref linkend="app-pgbasebackup"/>
471+
tool. If you include the <literal>-X</literal> parameter when calling
472+
it, all the write-ahead log required to use the backup will be
473+
included in the backup automatically, and no special action is
474+
required to restore the backup.
475+
</para>
476+
</sect2>
477+
572478
<sect2 id="backup-archiving-wal">
573479
<title>Setting Up WAL Archiving</title>
574480

@@ -1464,28 +1370,6 @@ restore_command = 'cp /mnt/server/archivedir/%f %p'
14641370
Some tips for configuring continuous archiving are given here.
14651371
</para>
14661372

1467-
<sect3 id="backup-standalone">
1468-
<title>Standalone Hot Backups</title>
1469-
1470-
<para>
1471-
It is possible to use <productname>PostgreSQL</productname>'s backup facilities to
1472-
produce standalone hot backups. These are backups that cannot be used
1473-
for point-in-time recovery, yet are typically much faster to backup and
1474-
restore than <application>pg_dump</application> dumps. (They are also much larger
1475-
than <application>pg_dump</application> dumps, so in some cases the speed advantage
1476-
might be negated.)
1477-
</para>
1478-
1479-
<para>
1480-
As with base backups, the easiest way to produce a standalone
1481-
hot backup is to use the <xref linkend="app-pgbasebackup"/>
1482-
tool. If you include the <literal>-X</literal> parameter when calling
1483-
it, all the write-ahead log required to use the backup will be
1484-
included in the backup automatically, and no special action is
1485-
required to restore the backup.
1486-
</para>
1487-
</sect3>
1488-
14891373
<sect3 id="compressed-archive-logs">
14901374
<title>Compressed Archive Logs</title>
14911375

@@ -1617,4 +1501,120 @@ archive_command = 'local_backup_script.sh "%p" "%f"'
16171501
</sect2>
16181502
</sect1>
16191503

1504+
<sect1 id="backup-file">
1505+
<title>File System Level Backup</title>
1506+
1507+
<para>
1508+
An older and largely deprecated technique to take a backup is to directly copy
1509+
the files that <productname>PostgreSQL</productname> uses to store the data in
1510+
the database; <xref linkend="creating-cluster"/> explains where these files
1511+
are located. You can use whatever method you prefer for doing file system
1512+
backups; for example:
1513+
1514+
<programlisting>
1515+
tar -cf backup.tar /usr/local/pgsql/data
1516+
</programlisting>
1517+
</para>
1518+
1519+
<para>
1520+
There are two restrictions, however, which make this method
1521+
impractical, or at least inferior to the <application>pg_dump</application>
1522+
method:
1523+
1524+
<orderedlist>
1525+
<listitem>
1526+
<para>
1527+
The database server <emphasis>must</emphasis> be shut down in order to
1528+
get a usable backup. Half-way measures such as disallowing all
1529+
connections will <emphasis>not</emphasis> work
1530+
(in part because <command>tar</command> and similar tools do not take
1531+
an atomic snapshot of the state of the file system,
1532+
but also because of internal buffering within the server).
1533+
Information about stopping the server can be found in
1534+
<xref linkend="server-shutdown"/>. Needless to say, you
1535+
also need to shut down the server before restoring the data.
1536+
</para>
1537+
</listitem>
1538+
1539+
<listitem>
1540+
<para>
1541+
If you have dug into the details of the file system layout of the
1542+
database, you might be tempted to try to back up or restore only certain
1543+
individual tables or databases from their respective files or
1544+
directories. This will <emphasis>not</emphasis> work because the
1545+
information contained in these files is not usable without
1546+
the commit log files,
1547+
<filename>pg_xact/*</filename>, which contain the commit status of
1548+
all transactions. A table file is only usable with this
1549+
information. Of course it is also impossible to restore only a
1550+
table and the associated <filename>pg_xact</filename> data
1551+
because that would render all other tables in the database
1552+
cluster useless. So file system backups only work for complete
1553+
backup and restoration of an entire database cluster.
1554+
</para>
1555+
</listitem>
1556+
</orderedlist>
1557+
</para>
1558+
1559+
<para>
1560+
An alternative file-system backup approach is to make a
1561+
<quote>consistent snapshot</quote> of the data directory, if the
1562+
file system supports that functionality (and you are willing to
1563+
trust that it is implemented correctly). The typical procedure is
1564+
to make a <quote>frozen snapshot</quote> of the volume containing the
1565+
database, then copy the whole data directory (not just parts, see
1566+
above) from the snapshot to a backup device, then release the frozen
1567+
snapshot. This will work even while the database server is running.
1568+
However, a backup created in this way saves
1569+
the database files in a state as if the database server was not
1570+
properly shut down; therefore, when you start the database server
1571+
on the backed-up data, it will think the previous server instance
1572+
crashed and will replay the WAL log. This is not a problem; just
1573+
be aware of it (and be sure to include the WAL files in your backup).
1574+
You can perform a <command>CHECKPOINT</command> before taking the
1575+
snapshot to reduce recovery time.
1576+
</para>
1577+
1578+
<para>
1579+
If your database is spread across multiple file systems, there might not
1580+
be any way to obtain exactly-simultaneous frozen snapshots of all
1581+
the volumes. For example, if your data files and WAL log are on different
1582+
disks, or if tablespaces are on different file systems, it might
1583+
not be possible to use snapshot backup because the snapshots
1584+
<emphasis>must</emphasis> be simultaneous.
1585+
Read your file system documentation very carefully before trusting
1586+
the consistent-snapshot technique in such situations.
1587+
</para>
1588+
1589+
<para>
1590+
If simultaneous snapshots are not possible, one option is to shut down
1591+
the database server long enough to establish all the frozen snapshots.
1592+
Another option is to perform a continuous archiving base backup (<xref
1593+
linkend="backup-base-backup"/>) because such backups are immune to file
1594+
system changes during the backup. This requires enabling continuous
1595+
archiving just during the backup process; restore is done using
1596+
continuous archive recovery (<xref linkend="backup-pitr-recovery"/>).
1597+
</para>
1598+
1599+
<para>
1600+
Another option is to use <application>rsync</application> to perform a file
1601+
system backup. This is done by first running <application>rsync</application>
1602+
while the database server is running, then shutting down the database
1603+
server long enough to do an <command>rsync --checksum</command>.
1604+
(<option>--checksum</option> is necessary because <command>rsync</command> only
1605+
has file modification-time granularity of one second.) The
1606+
second <application>rsync</application> will be quicker than the first,
1607+
because it has relatively little data to transfer, and the end result
1608+
will be consistent because the server was down. This method
1609+
allows a file system backup to be performed with minimal downtime.
1610+
</para>
1611+
1612+
<para>
1613+
Note that a file system backup will typically be larger
1614+
than an SQL dump. (<application>pg_dump</application> does not need to dump
1615+
the contents of indexes for example, just the commands to recreate
1616+
them.) However, taking a file system backup might be faster.
1617+
</para>
1618+
</sect1>
1619+
16201620
</chapter>

0 commit comments

Comments
 (0)