First pass at docs for pg_restore

diff --git a/doc/src/sgml/ref/pg_restore.sgml b/doc/src/sgml/ref/pg_restore.sgml
new file mode 100644 (file)
index 0000000..b8e9e48
--- /dev/null
+++ b/doc/src/sgml/ref/pg_restore.sgml
@@ -0,0 +1,578 @@
+
+ 
+  
+   pg_restore
+  
+  Application
+ 
+ 
+  
+   pg_restore
+  
+  
+   Restore a Postgres database from an archive file created by \r
+pg_dump\r
+  
+ 
+ 
+  
+   2000-10-11
+  
+  \r
+pg_restore [ archive-file  ] \r
+    [ -h  host  ] \r
+    [ -p  port  ]     \r
+    [ -t  table  ]     \r
+    [ -a  ] [ -c  ] [-C] [-d ] \r
+    [-f archive-file] \r
+    [-F format] \r
+    [ -i  index  ] \r
+    [ -l ] [ -N  ] [ -o  ] [ -O ] \r
+    [ -P function-name ] [ -r ] [ -R ] \r
+    [ -s  ] [ -S ] { -T  trigger ] [ -u  ] \r
+    [-U contents-file ] [ -v  ] [ -x ] \r
+  
+
+  
+   
+    2000-10-11
+   
+   </div>
<div class="diff add">+    Inputs</div>
<div class="diff add">+   
+   
+    pg_restore accepts the following command
+    line arguments:
+
+    
+     
+      archive-name
+      
+       
+       Specifies the location of the archive file to be restored.\r
+       If not specified, and no '-f' option is specified, then STDIN is used.
+       
+      
+     
+
+     
+      -a
+      
+       
+   Restore only the data, no schema (definitions).
+       
+      
+     
+
+     \r
+      -c\r
+      \r
+       \r
+   Clean (drop) schema prior to create.\r
+       \r
+      \r
+     \r
+\r
+     \r
+      -C\r
+      \r
+       \r
+   Include SQL to create the schema.\r
+       \r
+      \r
+     \r
+\r
+     
+      -d dbname
+      
+       
+        Connect to database dbname and restore \r
+        directly into the database. BLOBs can only be restored by using a direct database connection.\r
+       
+      
+     
+
+     \r
+      -f\r
+      \r
+       \r
+     Specify output file for generated script. Default is STDOUT.\r
+       \r
+      \r
+     \r
+\r
+     \r
+      -F format\r
+      \r
+       \r
+     Specify format of the archive.\r
+        It is not necessary to specify the format, since pg_restore will \r
+        determine the format automatically. If specified, it can be one of the following:\r
+       \r
+\r
+       \r
+\r
+        \r
+         t\r
+         \r
+          \r
+           archive is a TAR archive. Using this archive format allows reordering and/or \r
+           exclusion of schema elements at the time the database is restored. It is also possible to limit which \r
+           data is reloaded at restore time.\r
+          \r
+         \r
+        \r
+\r
+        \r
+         c\r
+         \r
+          \r
+           archive is in the custom format from pg_dump. This is the most flexible format \r
+           in that it allows reordering of data load as well as schema elements. \r
+           This format is also compressed by default.\r
+          \r
+         \r
+        \r
+\r
+       \r
+\r
+      \r
+     \r
+\r
+     \r
+      -i index\r
+      \r
+       \r
+   Restore definition for named index only.\r
+       \r
+      \r
+     \r
+\r
+     \r
+      -l\r
+      \r
+       \r
+        List the contents of the archive. The output of this command can be used with the '-U, --use-list' option\r
+        to restrict and reorder the items that are restored.\r
+       \r
+      \r
+     \r
+\r
+     
+      -N
+      
+       \r
+        Restore items in the original dump order. By default pg_dump will dump items in an order convenient \r
+        to pg_dump, then save the archive in a modified OID order. This option overrides the OID ordering.
+       
+      
+     
+
+     
+      -o
+      
+       
+        Restore items in the OID order. By default pg_dump will dump items in an order convenient \r
+        to pg_dump, then save the archive in a modified OID order. This option enforces strict OID ordering.\r
+       
+      
+     
+
+     
+      -O
+      
+       
+        Prevent any attempt to restore original object ownership. Objects will be owned by the username used\r
+        to attach to the database.\r
+       
+      
+     
+\r
+     \r
+      -P procedure-name\r
+      \r
+       \r
+        Specify a procedure or function to be restored.\r
+       \r
+      \r
+     \r
+\r
+     \r
+      -r\r
+      \r
+       \r
+        Restore items in modified OID order. By default pg_dump will dump items in an order convenient \r
+        to pg_dump, then save the archive in a modified OID order. Most objects\r
+        will be restored in OID order, but some things (eg. RULES & INDEXES) will be restored at the end of\r
+        the process irrespective of their OIDs. This option is the default. \r
+       \r
+      \r
+     \r
+
+     \r
+      -R\r
+      \r
+       \r
+     Prohibit pg_restore from issuing any \connect \r
+        statements or reconnecting to the database if directly connected.\r
+       \r
+      \r
+     \r
+\r
+     \r
+      -s\r
+      \r
+       \r
+   Restore the schema (definitions), no data. Sequence values will be reset.\r
+       \r
+      \r
+     \r
+\r
+     \r
+      -S username\r
+      \r
+       \r
+        Specify the superuser username to use when disabling triggers and/or setting ownership of schema elements.\r
+        By default, pg_restore will use the current username if it is a superuser.\r
+       \r
+      \r
+     \r
+
+     \r
+      -t table\r
+      \r
+       \r
+   Restore schema/data for table only.\r
+       \r
+      \r
+     \r
+\r
+     \r
+      -T trigger\r
+      \r
+       \r
+     Restore definition of trigger only.\r
+       \r
+      \r
+     \r
+\r
+     
+      -u
+      
+       
+   Use password authentication. Prompts for username and password.
+       
+      
+     
+
+     \r
+      -U list-file\r
+      \r
+       \r
+     Restore elements in list-file only, and in the\r
+        order they appear in the file. Lines can be moved and may also be commented out by placing a ';' at the \r
+        start of the line.\r
+       \r
+      \r
+     \r
+\r
+     
+      -v
+      
+       
+   Specifies verbose mode.
+       
+      
+     
+
+     
+      -x
+      
+       
+   Prevent restoration of ACLs (grant/revoke commands).
+       
+      
+     
+
+    
+   
+   
+    pg_restore also accepts 
+    the following command line arguments for connection parameters:
+
+    
+     
+      -h host
+      
+       
+   Specifies the hostname of the machine on which the 
+   postmaster
+   is running.  Defaults to using a local Unix domain socket
+   rather than an IP connection.
+       
+      
+     
+
+     
+      -p port
+      
+       
+   Specifies the Internet TCP/IP port or local Unix domain socket file 
+   extension on which the postmaster
+   is listening for connections.  The port number defaults to 5432,
+   or the value of the PGPORT
+   environment variable (if set).
+       
+      
+     
+
+    
+   
+  
+
+  
+   
+    2000-10-11
+   
+   </div>
<div class="diff add">+    Outputs</div>
<div class="diff add">+   
+   
+    pg_restore will create a script file,
+    write to stdout, or restore a database directly.
+
+    
+     
+      
+Connection to database 'template1' failed.
+connectDB() failed: Is the postmaster running and accepting connections
+            at 'UNIX Socket' on port 'port'?
+       
+      
+       
+   pg_restore could not attach to the 
+   postmaster 
+   process on the specified host and port.  If you see this message,
+   ensure that the postmaster 
+   is running on the proper host and that you have specified the proper
+   port.  If your site uses an authentication system, ensure that you
+   have obtained the required authentication credentials.
+       
+      
+     
+
+     
+      
+Connection to database 'dbname' failed.
+FATAL 1:  SetUserId: user 'username' is not in 'pg_shadow'
+       
+      
+       
+   You do not have a valid entry in the relation pg_shadow
+   and and will not be allowed to access Postgres. 
+   Contact your Postgres administrator.
+       
+      
+     
+
+    
+   
+
+   
+    
+     When a direct database connection is specified using the -d option, pg_restore \r
+     internally executes  SQL statements. If you  have problems running \r
+     pg_restore,
+     make sure you are able to select information from the database using, for
+     example, psql.
+    
+   
+  
+ 
+
+ 
+  
+   2000-10-11
+  
+  </div>
<div class="diff add">+   Description</div>
<div class="diff add">+  
+  
+   pg_restore is a utility for restoring a\r
+      Postgres database dumped by pg_dump\r
+      from any one of the non-plain-text output formats.\r
+  
+
+  
+   The archive files, new with this relase, contain enough information for \r
+   pg_restore to rebuild the database, but also allow \r
+   pg_restore to be selective about what is restored, \r
+   or even to reorder the items prior to being restored. The archive files should \r
+   also be portable across architectures. pg_dump will \r
+   produce the queries necessary to re-generate all user-defined types, functions, \r
+   tables, indices, aggregates, and operators.  In addition, all the data is copied \r
+   out (in text format for scripts) so that it can be readily copied in again.\r
+  
+\r
+  \r
+   pg_restore reads the archive file and outputs the appropriate \r
+   SQL in the required order based on the command parameters. Obviously, it can not restore \r
+   information that is not present in the dump file; so if the dump is made using the \r
+   'dump data as inserts' option, pg_restore will not be able to\r
+   load the data using COPY statements.\r
+  \r
+\r
+  \r
+   The most flexible output file format is the new 'custom' format (-Fc). It allows for \r
+   selection and reordering of all archived items, and is compressed by default. The TAR \r
+   format (-Ft) is not compressed and it is not possible to reorder\r
+   data load, but it is otherwise quite flexible.\r
+  \r
+\r
+  \r
+   To reorder the items, it is first necessary to dump the contents of the archive:\r
+   \r
+    $ pg_restore acrhive.file --list > archive.lis    \r
+   \r
+   This file consists of a header and one line for each item, eg.\r
+   \r
+;\r
+; Archive created at Fri Jul 28 22:28:36 2000\r
+;     dbname: birds\r
+;     TOC Entries: 74\r
+;     Compression: 0\r
+;     Dump Version: 1.4-0\r
+;     Format: CUSTOM\r
+;\r
+;\r
+; Selected TOC Entries:\r
+;\r
+2; 145344 TABLE species postgres\r
+3; 145344 ACL species\r
+4; 145359 TABLE nt_header postgres\r
+5; 145359 ACL nt_header\r
+6; 145402 TABLE species_records postgres\r
+7; 145402 ACL species_records\r
+8; 145416 TABLE ss_old postgres\r
+9; 145416 ACL ss_old\r
+10; 145433 TABLE map_resolutions postgres\r
+11; 145433 ACL map_resolutions\r
+12; 145443 TABLE hs_old postgres\r
+13; 145443 ACL hs_old\r
+\r
+\r
+   Where semi-colons are comment delimiters, and the numbers at the start of lines refer to the \r
+   internal archive ID assigned to each item. Lines in the file can be commented out, deleted, \r
+   and/or reordered. For example,\r
+   \r
+10; 145433 TABLE map_resolutions postgres\r
+;2; 145344 TABLE species postgres\r
+;4; 145359 TABLE nt_header postgres\r
+6; 145402 TABLE species_records postgres\r
+;8; 145416 TABLE ss_old postgres\r
+   \r
+  \r
+  \r
+   Could be used as input to pg_restore and would only restore \r
+   items 10 and 6, in that order.\r
+   \r
+    $ pg_restore acrhive.file --use=archive.lis    \r
+   \r
+  \r
+\r
+ 
+
+ 
+  
+   2000-10-11
+  
+  </div>
<div class="diff add">+   Notes</div>
<div class="diff add">+  
+  
+   See the pg_dump section for details on limitation of\r
+   pg_dump.\r
+  \r
+  
+   The limitations of pg_restore are detailed below.
+
+   
+    
+     
+      When restoring data to a table, pg_restore emits queries \r
+      to disable triggers on user tables before inserting the data then emits queries to \r
+      re-enable them after the data has been inserted.  If the restore is stopped in the \r
+      middle, the system catalogs may be left in the wrong state.
+     
+    
+
+    
+     
+      pg_restore will not restore BLOBs for a single table. If \r
+      an archive contains BLOBs, then all BLOBs will be restored. 
+     
+    
+
+   
+  
+ 
+
+ 
+  
+   2000-10-11
+  
+  </div>
<div class="diff add">+   Usage</div>
<div class="diff add">+  
+  
+   To create a custom archive for a database of the same name as the user:
+
+   
+$ pg_dump -Fc > db.out
+   
+  
+
+  \r
+   To reload this database:\r
+\r
+   \r
+$ pg_restore db.out | psql -e database\r
+   \r
+  \r
+\r
+  \r
+   To dump a database called mydb that contains BLOBs to a TAR file:\r
+\r
+   \r
+$ pg_dump -Ft mydb --blobs > db.tar\r
+   \r
+  \r
+\r
+  \r
+   To reload this database (with BLOBs) to an existing db called newdb:\r
+\r
+   \r
+$ pg_restore db.tar --db=newdb\r
+   \r
+  \r
+\r
+\r
+ 
+
+
+