From f7ea4eeed6291e960116fe5ed796d1eb3f2ff914 Mon Sep 17 00:00:00 2001 From: Neil Conway Date: Tue, 19 Sep 2006 19:04:51 +0000 Subject: [PATCH] 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. --- doc/src/sgml/backup.sgml | 61 +++++++++++++++++++++++++--------------- 1 file changed, 39 insertions(+), 22 deletions(-) diff --git a/doc/src/sgml/backup.sgml b/doc/src/sgml/backup.sgml index 94d6c9cd5da..cff61ad6576 100644 --- 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 command line option. @@ -105,30 +105,42 @@ psql dbname < outfile for the pg_dump command. The database 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 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 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 @@ -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 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 .