Document how to use psql's --single-transaction option to rollback restoring

an SQL dump if an error occurs. Along the way, make some improvements and
copy-edits to the surrounding text. Patch from Simon Riggs, additional
fixes by Neil Conway.

diff --git a/doc/src/sgml/backup.sgml b/doc/src/sgml/backup.sgml
index 94d6c9cd5da833b7da9274d76b693222e1898aef..cff61ad6576b6a5e069fc8c62b81caf0fe8be9dc 100644 (file)
--- a/doc/src/sgml/backup.sgml
+++ b/doc/src/sgml/backup.sgml
@@ -1,4 +1,4 @@
-
+
 
 
  Backup and Restore
@@ -84,7 +84,7 @@ pg_dump dbname > 
 
   
    
-    When your database schema relies on OIDs (for instance as foreign
+    If your database schema relies on OIDs (for instance as foreign
     keys) you must instruct pg_dump to dump the OIDs
     as well. To do this, use the -o command line
     option.
@@ -105,30 +105,42 @@ psql dbname < 
     you used as outfile
     for the pg_dump command. The database 
     class="parameter">dbname will not be created by this
-    command, you must create it yourself from template0 before executing
-    psql (e.g., with createdb -T template0
-    dbname).
-    psql supports options similar to pg_dump 
-    for controlling the database server location and the user name. See
-    's reference page for more information.
+    command, so you must create it yourself from template0
+    before executing psql (e.g., with
+    createdb -T template0 
+    class="parameter">dbname).  psql
+    supports similar options to pg_dump for specifying
+    the database server to connect to and the user name to use. See
+    the  reference page for more information.
    
 
    
-    Not only must the target database already exist before starting to
-    run the restore, but so must all the users who own objects in the
-    dumped database or were granted permissions on the objects.  If they
-    do not, then the restore will fail to recreate the objects with the
-    original ownership and/or permissions.  (Sometimes this is what you want,
-    but usually it is not.)
+    Before restoring a SQL dump, all the users who own objects or were
+    granted permissions on objects in the dumped database must already
+    exist. If they do not, then the restore will fail to recreate the
+    objects with the original ownership and/or permissions.
+    (Sometimes this is what you want, but usually it is not.)
    
 
    
-    Once restored, it is wise to run 
-    endterm="sql-analyze-title"> on each database so the optimizer has
-    useful statistics. An easy way to do this is to run
-    vacuumdb -a -z to
-    VACUUM ANALYZE all databases; this is equivalent to
-    running VACUUM ANALYZE manually.
+    By default, the psql script will continue to
+    execute after an SQL error is encountered. You may wish to use the
+    following command at the top of the script to alter that
+    behaviour and have psql exit with an
+    exit status of 3 if an SQL error occurs:
+
+\set ON_ERROR_STOP
+
+    Either way, you will only have a partially restored
+    dump. Alternatively, you can specify that the whole dump should be
+    restored as a single transaction, so the restore is either fully
+    completed or fully rolled back. This mode can be specified by
+    passing the -1 or --single-transaction
+    command-line options to psql. When using this
+    mode, be aware that even the smallest of errors can rollback a
+    restore that has already run for many hours. However, that may
+    still be preferable to manually cleaning up a complex database
+    after a partially restored dump.
    
 
    
@@ -153,8 +165,13 @@ pg_dump -h host1 dbname | psql -h h
    
 
    
-    For advice on how to load large amounts of data into
-    PostgreSQL efficiently, refer to 
+    After restoring a backup, it is wise to run 
+    linkend="sql-analyze" endterm="sql-analyze-title"> on each
+    database so the query optimizer has useful statistics. An easy way
+    to do this is to run vacuumdb -a -z; this is
+    equivalent to running VACUUM ANALYZE on each database
+    manually.  For more advice on how to load large amounts of data
+    into PostgreSQL efficiently, refer to 
     linkend="populate">.
    
   




This is the main PostgreSQL git repository.
RSS
Atom



window.onload = function () {
	var tz_cookie = { name: 'gitweb_tz', expires: 14, path: '/' };
	onloadTZSetup('local', tz_cookie, 'datetime');
};