On Wed, Apr 13, 2016 at 4:07 AM, Noah Misch <n...@leadboat.com> wrote:
> On Tue, Apr 12, 2016 at 10:08:23PM +0200, Magnus Hagander wrote:
> > On Tue, Apr 12, 2016 at 8:39 AM, Noah Misch <n...@leadboat.com> wrote:
> > > On Mon, Apr 11, 2016 at 11:22:27AM +0200, Magnus Hagander wrote:
> > > > Well, if we *don't* do the rewrite before we release it, then we
> have to
> > > > instead put information about the new version of the functions into
> the
> > > old
> > > > structure I think.
> > > >
> > > > So I think it's an open issue.
> > >
> > > Works for me...
> > >
> > > [This is a generic notification.]
> > >
> > > The above-described topic is currently a PostgreSQL 9.6 open item.
> Magnus,
> > > since you committed the patch believed to have created it, you own this
> > > open
> > > item. If that responsibility lies elsewhere, please let us know whose
> > > responsibility it is to fix this. Since new open items may be
> discovered
> > > at
> > > any time and I want to plan to have them all fixed well in advance of
> the
> > > ship
> > > date, I will appreciate your efforts toward speedy resolution. Please
> > > present, within 72 hours, a plan to fix the defect within seven days of
> > > this
> > > message. Thanks.
> > >
> >
> > I won't have time to do the bigger rewrite/reordeirng by then, but I can
> > certainly commit to having the smaller updates done to cover the new
> > functionality in less than a week. If nothing else, that'll be something
> > for me to do on the flight over to pgconf.us.
>
> Thanks for that plan; it sounds good.
>
Here's a suggested patch.
There is some duplication between the non-exclusive and exclusive backup
sections, but I wanted to make sure that each set of instructions can just
be followed top-to-bottom.
I've also removed some tips that aren't really necessary as part of the
step-by-step instructions in order to keep things from exploding in size.
Finally, I've changed references to "backup dump" to just be "backup",
because it's confusing to call them something with dumps in when it's not
pg_dump. Enough that I got partially confused myself while editing...
Comments?
--
Magnus Hagander
Me: http://www.hagander.net/
Work: http://www.redpill-linpro.com/
*** a/doc/src/sgml/backup.sgml
--- b/doc/src/sgml/backup.sgml
***************
*** 818,823 **** test ! -f /mnt/server/archivedir/00000001000000A900000065 && cp pg_xlog/
--- 818,838 ----
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.
+ </para>
+ <para>
+ Low level base backups can be made in a non-exclusive or an exclusive
+ way. The non-exclusive method is recommended and the exclusive one will
+ at some point be deprecated and removed.
+ </para>
+ <sect3 id="backup-lowlevel-base-backup-nonexclusive">
+ <title>Making a non-exclusive low level backup</title>
+ <para>
+ A non-exclusive low level backup is one that allows other
+ concurrent backups to be running (both those started using
+ the same backup API and those started using
+ <xref linkend="app-pgbasebackup">.
+ </para>
+ <para>
<orderedlist>
<listitem>
<para>
***************
*** 826,857 **** test ! -f /mnt/server/archivedir/00000001000000A900000065 && cp pg_xlog/
</listitem>
<listitem>
<para>
! Connect to the database as a user with rights to run pg_start_backup
! (superuser, or a user who has been granted EXECUTE on the function)
! and issue the command:
<programlisting>
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.)
<function>pg_start_backup</> creates a <firstterm>backup label</> file,
called <filename>backup_label</>, in the cluster directory with
! information about your backup, including the start time and label
! string. The function also creates a <firstterm>tablespace map</> file,
called <filename>tablespace_map</>, in the cluster directory with
! information about tablespace symbolic links in <filename>pg_tblspc/</>
! if one or more such link is present. Both files are critical to the
integrity of the backup, should you need to restore from it.
</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>
-
- <para>
By default, <function>pg_start_backup</> can take a long time to finish.
This is because it performs a checkpoint, and the I/O
required for the checkpoint will be spread out over a significant
--- 841,970 ----
</listitem>
<listitem>
<para>
! Connect to the server (it does not matter which database) as a user with
! rights to run pg_start_backup (superuser, or a user who has been granted
! EXECUTE on the function) and issue the command:
! <programlisting>
! SELECT pg_start_backup('label', false, false);
! </programlisting>
! where <literal>label</> is any string you want to use to uniquely
! identify this backup operation. The connection
! calling <function>pg_start_backup</> must be maintained until the end of
! the backup, or the backup will be automatically aborted.
! </para>
!
! <para>
! By default, <function>pg_start_backup</> can take a long time to finish.
! This is because it performs a checkpoint, and the I/O
! required for the checkpoint will be spread out over a significant
! period of time, by default half your inter-checkpoint interval
! (see the configuration parameter
! <xref linkend="guc-checkpoint-completion-target">). This is
! usually what you want, because it minimizes the impact on query
! processing. If you want to start the backup as soon as
! possible, change the second parameter to <literal>true</>.
! </para>
!
! <para>
! The third parameter being <literal>false</> tells
! <function>pg_start_backup</> to initiate a non-exclusive base backup.
! </para>
! </listitem>
! <listitem>
! <para>
! Perform the backup, using any convenient file-system-backup tool
! such as <application>tar</> or <application>cpio</> (not
! <application>pg_dump</application> or
! <application>pg_dumpall</application>). It is neither
! necessary nor desirable to stop normal operation of the database
! while you do this. See section
! <xref linkend="backup-lowlevel-base-backup-data"> for things to
! consider during this backup.
! </para>
! </listitem>
! <listitem>
! <para>
! In the same connection as before, issue the command:
! <programlisting>
! SELECT * FROM pg_stop_backup(false);
! </programlisting>
! This terminates the backup mode and performs an automatic switch to
! the next WAL segment. The reason for the switch is to arrange for
! the last WAL segment file written during the backup interval to be
! ready to archive.
! </para>
! <para>
! The <function>pg_stop_backup</> will return one row with three
! values. The second of these fields should be written to a file named
! <filename>backup_label</> in the root directory of the backup. The
! third field should be written to a file named
! <filename>tablespace_map</> unless the field is empty. These files are
! vital to the backup working, and must be written without modification.
! </para>
! </listitem>
! <listitem>
! <para>
! Once the WAL segment files active during the backup are archived, you are
! done. The file identified by <function>pg_stop_backup</>'s first return
! value the last segment that is required to form a complete set of backup
! files. If <varname>archive_mode</> is enabled,
! <function>pg_stop_backup</> does not return until the last segment has
! been archived.
! Archiving of these files happens automatically since you have
! already configured <varname>archive_command</>. In most cases this
! happens quickly, but you are advised to monitor your archive
! system to ensure there are no delays.
! If the archive process has fallen behind
! because of failures of the archive command, it will keep retrying
! until the archive succeeds and the backup is complete.
! If you wish to place a time limit on the execution of
! <function>pg_stop_backup</>, set an appropriate
! <varname>statement_timeout</varname> value, but make note that if
! <function>pg_stop_backup</> terminates because of this your backup
! may not be valid.
! </para>
! </listitem>
! </orderedlist>
! </para>
! </sect3>
! <sect3 id="backup-lowlevel-base-backup-exclusive">
! <title>Making an exclusive low level backup</title>
! <para>
! The process for an exclusive backup is mostly the same as for a
! non-exclusive one, but it differs in a few key steps. It does not allow
! more than one concurrent backup to run, and there can be some issues on
! the server if it crashes during the backup. Prior to PostgreSQL 9.6, this
! was the only low-level method available, but it is now recommended that
! all users upgrade their scripts to use non-exclusive backups if possible.
! </para>
! <para>
! <orderedlist>
! <listitem>
! <para>
! Ensure that WAL archiving is enabled and working.
! </para>
! </listitem>
! <listitem>
! <para>
! Connect to the server (it does not matter which database) as a user with
! rights to run pg_start_backup (superuser, or a user who has been granted
! EXECUTE on the function) and issue the command:
<programlisting>
SELECT pg_start_backup('label');
</programlisting>
where <literal>label</> is any string you want to use to uniquely
! 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, including the start time and label string.
! The function also creates a <firstterm>tablespace map</> file,
called <filename>tablespace_map</>, in the cluster directory with
! information about tablespace symbolic links in <filename>pg_tblspc/</> if
! one or more such link is present. Both files are critical to the
integrity of the backup, should you need to restore from it.
</para>
<para>
By default, <function>pg_start_backup</> can take a long time to finish.
This is because it performs a checkpoint, and the I/O
required for the checkpoint will be spread out over a significant
***************
*** 874,880 **** SELECT pg_start_backup('label', true);
<application>pg_dump</application> or
<application>pg_dumpall</application>). It is neither
necessary nor desirable to stop normal operation of the database
! while you do this.
</para>
</listitem>
<listitem>
--- 987,995 ----
<application>pg_dump</application> or
<application>pg_dumpall</application>). It is neither
necessary nor desirable to stop normal operation of the database
! while you do this. See section
! <xref linkend="backup-lowlevel-base-backup-data"> for things to
! consider during this backup.
</para>
</listitem>
<listitem>
***************
*** 908,919 **** SELECT pg_stop_backup();
until the archive succeeds and the backup is complete.
If you wish to place a time limit on the execution of
<function>pg_stop_backup</>, set an appropriate
! <varname>statement_timeout</varname> value.
</para>
</listitem>
</orderedlist>
! </para>
!
<para>
Some file system backup tools emit warnings or errors
if the files they are trying to copy change while the copy proceeds.
--- 1023,1038 ----
until the archive succeeds and the backup is complete.
If you wish to place a time limit on the execution of
<function>pg_stop_backup</>, set an appropriate
! <varname>statement_timeout</varname> value, but make note that if
! <function>pg_stop_backup</> terminates because of this your backup
! may not be valid.
</para>
</listitem>
</orderedlist>
! </para>
! </sect3>
! <sect3 id="backup-lowlevel-base-backup-data">
! <title>Backing up the data directory</title>
<para>
Some file system backup tools emit warnings or errors
if the files they are trying to copy change while the copy proceeds.
***************
*** 933,948 **** SELECT pg_stop_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</>).
If you are using tablespaces that do not reside underneath this directory,
! be careful to include them as well (and be sure that your backup dump
archives symbolic links as links, otherwise the restore will corrupt
your tablespaces).
</para>
<para>
! You can, however, omit from the backup dump the files within the
cluster's <filename>pg_xlog/</> subdirectory. This
slight adjustment is worthwhile because it reduces the risk
of mistakes when restoring. This is easy to arrange if
--- 1052,1067 ----
</para>
<para>
! Be certain that your backup includes all of the files under
the database cluster directory (e.g., <filename>/usr/local/pgsql/data</>).
If you are using tablespaces that do not reside underneath this directory,
! be careful to include them as well (and be sure that your backup
archives symbolic links as links, otherwise the restore will corrupt
your tablespaces).
</para>
<para>
! You should, however, omit from the backup the files within the
cluster's <filename>pg_xlog/</> subdirectory. This
slight adjustment is worthwhile because it reduces the risk
of mistakes when restoring. This is easy to arrange if
***************
*** 956,962 **** SELECT pg_stop_backup();
</para>
<para>
! It is often a good idea to also omit from the backup dump the files
within the cluster's <filename>pg_replslot/</> directory, so that
replication slots that exist on the master do not become part of the
backup. Otherwise, the subsequent use of the backup to create a standby
--- 1075,1081 ----
</para>
<para>
! It is often a good idea to also omit from the backup the files
within the cluster's <filename>pg_replslot/</> directory, so that
replication slots that exist on the master do not become part of the
backup. Otherwise, the subsequent use of the backup to create a standby
***************
*** 971,985 **** SELECT pg_stop_backup();
</para>
<para>
! It's also worth noting that the <function>pg_start_backup</> function
! makes files named <filename>backup_label</> and
! <filename>tablespace_map</> in the database cluster directory,
! which are removed by <function>pg_stop_backup</>. These files will of
! course be archived as a part of your backup dump file. The backup label
file includes the label string you gave to <function>pg_start_backup</>,
as well as the time at which <function>pg_start_backup</> was run, and
the name of the starting WAL file. In case of confusion it is therefore
! possible to look inside a backup dump file and determine exactly which
backup session the dump file came from. The tablespace map file includes
the symbolic link names as they exist in the directory
<filename>pg_tblspc/</> and the full path of each symbolic link.
--- 1090,1100 ----
</para>
<para>
! The backup label
file includes the label string you gave to <function>pg_start_backup</>,
as well as the time at which <function>pg_start_backup</> was run, and
the name of the starting WAL file. In case of confusion it is therefore
! possible to look inside a backup file and determine exactly which
backup session the dump file came from. The tablespace map file includes
the symbolic link names as they exist in the directory
<filename>pg_tblspc/</> and the full path of each symbolic link.
***************
*** 989,1001 **** SELECT pg_stop_backup();
</para>
<para>
! It is also possible to make a backup dump while the server is
stopped. In this case, you obviously cannot use
<function>pg_start_backup</> or <function>pg_stop_backup</>, and
you will therefore be left to your own devices to keep track of which
! backup dump is which and how far back the associated WAL files go.
It is generally better to follow the continuous archiving procedure above.
</para>
</sect2>
<sect2 id="backup-pitr-recovery">
--- 1104,1117 ----
</para>
<para>
! It is also possible to make a backup while the server is
stopped. In this case, you obviously cannot use
<function>pg_start_backup</> or <function>pg_stop_backup</>, and
you will therefore be left to your own devices to keep track of which
! backup is which and how far back the associated WAL files go.
It is generally better to follow the continuous archiving procedure above.
</para>
+ </sect3>
</sect2>
<sect2 id="backup-pitr-recovery">
--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers
