Thread: BUG #4548: Documentation Contradiction for 8.3

The following bug has been logged online:

Bug reference:      4548
Logged by:          Barry Reddy
Email address:      barryreddy@gmail.com
PostgreSQL version: 8.3.3
Operating system:   Linux 2.6.24-19-server i686 RHEL5
Description:        Documentation Contradiction for 8.3
Details:

I’ve been going over the PostgreSQL documentation for pg_archiving,
And have been struck by an apparent contradiction, which I’m hoping
To clarify…not sure if you have any thoughts, or can refer this to any
Contacts for a clarification, if so, feel free to forward.

http://www.postgresql.org/docs/8.3/interactive/backup-file.html

1.    The database server must be shut down in order to get a usable backup.
Half-way measures such as disallowing all connections will not work (in part
because tar and similar tools do not take an atomic snapshot of the state of
the file system, but also because of internal buffering within the server).
Information about stopping the server can be found in Section 17.5. Needless
to say that you also need to shut down the server before restoring the
data.

http://www.postgresql.org/docs/8.3/interactive/continuous-archiving.html#BAC
KUP-BASE-BACKUP

3.    Perform the backup, using any convenient file-system-backup tool such as
tar or cpio. It is neither necessary nor desirable to stop normal operation
of the database while you do this.

Can anyone clarify if this apparent contradiction is an oversight ?  Old
documentation with new archiving documentation patched on, with no attention
paid to the seeming contradiction on guidelines for filesystem backups of a
running PG database ?

In response to "Barry Reddy" <barryreddy@gmail.com>:
>
> The following bug has been logged online:
>
> Bug reference:      4548
> Logged by:          Barry Reddy
> Email address:      barryreddy@gmail.com
> PostgreSQL version: 8.3.3
> Operating system:   Linux 2.6.24-19-server i686 RHEL5
> Description:        Documentation Contradiction for 8.3
> Details:
>
> I’ve been going over the PostgreSQL documentation for pg_archiving,
> And have been struck by an apparent contradiction, which I’m hoping
> To clarify…not sure if you have any thoughts, or can refer this to any
> Contacts for a clarification, if so, feel free to forward.
>
> http://www.postgresql.org/docs/8.3/interactive/backup-file.html
>
> 1.    The database server must be shut down in order to get a usable backup.
> Half-way measures such as disallowing all connections will not work (in part
> because tar and similar tools do not take an atomic snapshot of the state of
> the file system, but also because of internal buffering within the server).
> Information about stopping the server can be found in Section 17.5. Needless
> to say that you also need to shut down the server before restoring the
> data.
>
> http://www.postgresql.org/docs/8.3/interactive/continuous-archiving.html#BAC
> KUP-BASE-BACKUP
>
> 3.    Perform the backup, using any convenient file-system-backup tool such as
> tar or cpio. It is neither necessary nor desirable to stop normal operation
> of the database while you do this.
>
> Can anyone clarify if this apparent contradiction is an oversight ?  Old
> documentation with new archiving documentation patched on, with no attention
> paid to the seeming contradiction on guidelines for filesystem backups of a
> running PG database ?

The data is correct and non-contradictory.  The problem is that you're
reading two different documents on two different methods of making
backups.  The methods have different rules that must be followed to
get a good backup.

--
Bill Moran
Collaborative Fusion Inc.
http://people.collaborativefusion.com/~wmoran/

wmoran@collaborativefusion.com
Phone: 412-422-3463x4023

On Monday 24 November 2008 23:37:02 Barry Reddy wrote:
> Can anyone clarify if this apparent contradiction is an oversight ? =C2=
=A0Old
> documentation with new archiving documentation patched on, with no
> attention paid to the seeming contradiction on guidelines for filesystem
> backups of a running PG database ?

It is not trivial to understand the difference.  Perhaps the documentation=
=20
doesn't make that entirely clear.

When you do a base backup with archiving on, that backup is only usable=20
together with the WAL segments that were written while the backup mode was=
=20
active.

So you can either make a backup: shutdown, tar, start
And then recover with: shutdown, untar, start

Or make a backup: pg_start_backup, tar, pg_stop_backup
And then recover with: shutdown, untar, recovery

In particular, it will *not* work to do:

Backup: pg_start_backup, tar, pg_stop_backup
Restore: shutdown, untar, start

So if you read both sections separately, they are correct.  It is only the=
=20
partial overlap in the otherwise diffferent procedures that is confusing.