From 387060951e40d550d37fe0457521e900d8c60feb Mon Sep 17 00:00:00 2001
From: Tom Lane
Date: Tue, 7 Apr 2009 00:31:26 +0000
Subject: Add an optional parameter to pg_start_backup() that specifies whether
 to do the checkpoint in immediate or lazy mode.  This is to address
 complaints that pg_start_backup() takes a long time even when there's no need
 to minimize its I/O consumption.

---
 doc/src/sgml/backup.sgml | 22 +++++++++++-----------
 doc/src/sgml/func.sgml   | 21 +++++++++++++--------
 2 files changed, 24 insertions(+), 19 deletions(-)

(limited to 'doc/src')

diff --git a/doc/src/sgml/backup.sgml b/doc/src/sgml/backup.sgml
index 51c3f909b3..ae9563a8e3 100644
--- a/doc/src/sgml/backup.sgml
+++ b/doc/src/sgml/backup.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/backup.sgml,v 2.123 2009/03/05 19:50:03 tgl Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/backup.sgml,v 2.124 2009/04/07 00:31:25 tgl Exp $ -->
 
 <chapter id="backup">
  <title>Backup and Restore</title>
@@ -730,19 +730,19 @@ SELECT pg_start_backup('label');
     </para>
 
     <para>
-     <function>pg_start_backup</> can take a long time to finish.
+     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 a checkpoint will be spread out over a significant
+     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">).  Usually
-     this is what you want because it minimizes the impact on query
+     this is what you want, because it minimizes the impact on query
      processing.  If you just want to start the backup as soon as
-     possible, execute a <command>CHECKPOINT</> command
-     (which performs a checkpoint as quickly as possible) and then
-     immediately execute <function>pg_start_backup</>.  Then there
-     will be very little for <function>pg_start_backup</>'s checkpoint
-     to do, and it won't take long.
+     possible, use:
+<programlisting>
+SELECT pg_start_backup('label', true);
+</programlisting>
+     This forces the checkpoint to be done as quickly as possible.
     </para>
    </listitem>
    <listitem>
@@ -769,9 +769,9 @@ SELECT pg_stop_backup();
     <para>
      Once the WAL segment files used during the backup are archived, you are
      done.  The file identified by <function>pg_stop_backup</>'s result is
-     the last segment that is required to form a complete set of backup files. 
+     the last segment that is required to form a complete set of backup files.
      <function>pg_stop_backup</> does not return until the last segment has
-     been archived. 
+     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
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index bd05152f78..f42f3e9341 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.474 2009/04/01 03:32:29 tgl Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.475 2009/04/07 00:31:25 tgl Exp $ -->
 
  <chapter id="functions">
   <title>Functions and Operators</title>
@@ -12880,10 +12880,10 @@ SELECT set_config('log_statement_stats', 'off', false);
      <tbody>
       <row>
        <entry>
-        <literal><function>pg_start_backup</function>(<parameter>label</> <type>text</>)</literal>
+        <literal><function>pg_start_backup</function>(<parameter>label</> <type>text</> <optional>, <parameter>fast</> <type>boolean</> </optional>)</literal>
         </entry>
        <entry><type>text</type></entry>
-       <entry>Set up for performing on-line backup</entry>
+       <entry>Prepare for performing on-line backup</entry>
       </row>
       <row>
        <entry>
@@ -12932,13 +12932,14 @@ SELECT set_config('log_statement_stats', 'off', false);
    </table>
 
    <para>
-    <function>pg_start_backup</> accepts a single parameter which is an
+    <function>pg_start_backup</> accepts a text parameter which is an
     arbitrary user-defined label for the backup.  (Typically this would be
     the name under which the backup dump file will be stored.)  The function
     writes a backup label file into the database cluster's data directory,
-    and then returns the backup's starting transaction log location as text.  The user
-    need not pay any attention to this result value, but it is provided in
-    case it is of use. 
+    performs a checkpoint,
+    and then returns the backup's starting transaction log location as text.
+    The user need not pay any attention to this result value, but it is
+    provided in case it is of use.
 <programlisting>
 postgres=# select pg_start_backup('label_goes_here');
  pg_start_backup
@@ -12946,6 +12947,10 @@ postgres=# select pg_start_backup('label_goes_here');
  0/D4445B8
 (1 row)
 </programlisting>
+    There is an optional boolean second parameter.  If <literal>true</>,
+    it specifies executing <function>pg_start_backup</> as quickly as
+    possible.  This forces an immediate checkpoint which will cause a
+    spike in I/O operations, slowing any concurrently executing queries.
    </para>
 
    <para>
@@ -12961,7 +12966,7 @@ postgres=# select pg_start_backup('label_goes_here');
    </para>
 
    <para>
-    <function>pg_switch_xlog</> moves to the next transaction log file, allowing the 
+    <function>pg_switch_xlog</> moves to the next transaction log file, allowing the
     current file to be archived (assuming you are using continuous archiving).
     The result is the ending transaction log location + 1 within the just-completed transaction log file.
     If there has been no transaction log activity since the last transaction log switch,
-- 
cgit v1.2.3