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