diff options
Diffstat (limited to 'doc/src')
| -rw-r--r-- | doc/src/sgml/ref/pg_dump.sgml | 34 | ||||
| -rw-r--r-- | doc/src/sgml/ref/pg_dumpall.sgml | 50 | ||||
| -rw-r--r-- | doc/src/sgml/ref/pg_restore.sgml | 11 |
3 files changed, 74 insertions, 21 deletions
diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml index 08cad68199f..11582dd1c82 100644 --- a/doc/src/sgml/ref/pg_dump.sgml +++ b/doc/src/sgml/ref/pg_dump.sgml @@ -46,9 +46,10 @@ PostgreSQL documentation </para> <para> - <application>pg_dump</application> only dumps a single database. To backup - global objects that are common to all databases in a cluster, such as roles - and tablespaces, use <xref linkend="app-pg-dumpall"/>. + <application>pg_dump</application> only dumps a single database. + To back up an entire cluster, or to back up global objects that are + common to all databases in a cluster (such as roles and tablespaces), + use <xref linkend="app-pg-dumpall"/>. </para> <para> @@ -142,7 +143,8 @@ PostgreSQL documentation switch is therefore only useful to add large objects to dumps where a specific schema or table has been requested. Note that blobs are considered data and therefore will be included when - --data-only is used, but not when --schema-only is. + <option>--data-only</option> is used, but not + when <option>--schema-only</option> is. </para> </listitem> </varlistentry> @@ -197,6 +199,17 @@ PostgreSQL documentation </para> <para> + With <option>--create</option>, the output also includes the + database's comment if any, and any configuration variable settings + that are specific to this database, that is, + any <command>ALTER DATABASE ... SET ...</command> + and <command>ALTER ROLE ... IN DATABASE ... SET ...</command> + commands that mention this database. + Access privileges for the database itself are also dumped, + unless <option>--no-acl</option> is specified. + </para> + + <para> This option is only meaningful for the plain-text format. For the archive formats, you can specify the option when you call <command>pg_restore</command>. @@ -1231,10 +1244,6 @@ CREATE DATABASE foo WITH TEMPLATE template0; <command>ANALYZE</command> after restoring from a dump file to ensure optimal performance; see <xref linkend="vacuum-for-statistics"/> and <xref linkend="autovacuum"/> for more information. - The dump file also does not - contain any <command>ALTER DATABASE ... SET</command> commands; - these settings are dumped by <xref linkend="app-pg-dumpall"/>, - along with database users and other installation-wide settings. </para> <para> @@ -1326,6 +1335,15 @@ CREATE DATABASE foo WITH TEMPLATE template0; </para> <para> + To reload an archive file into the same database it was dumped from, + discarding the current contents of that database: + +<screen> +<prompt>$</prompt> <userinput>pg_restore -d postgres --clean --create db.dump</userinput> +</screen> + </para> + + <para> To dump a single table named <literal>mytab</literal>: <screen> diff --git a/doc/src/sgml/ref/pg_dumpall.sgml b/doc/src/sgml/ref/pg_dumpall.sgml index 5196a211b1e..4a639f2d41e 100644 --- a/doc/src/sgml/ref/pg_dumpall.sgml +++ b/doc/src/sgml/ref/pg_dumpall.sgml @@ -36,13 +36,10 @@ PostgreSQL documentation of a cluster into one script file. The script file contains <acronym>SQL</acronym> commands that can be used as input to <xref linkend="app-psql"/> to restore the databases. It does this by - calling <xref linkend="app-pgdump"/> for each database in a cluster. + calling <xref linkend="app-pgdump"/> for each database in the cluster. <application>pg_dumpall</application> also dumps global objects - that are common to all databases. + that are common to all databases, that is, database roles and tablespaces. (<application>pg_dump</application> does not save these objects.) - This currently includes information about database users and - groups, tablespaces, and properties such as access permissions - that apply to databases as a whole. </para> <para> @@ -50,7 +47,7 @@ PostgreSQL documentation databases you will most likely have to connect as a database superuser in order to produce a complete dump. Also you will need superuser privileges to execute the saved script in order to be - allowed to add users and groups, and to create databases. + allowed to add roles and create databases. </para> <para> @@ -308,7 +305,7 @@ PostgreSQL documentation <listitem> <para> Use conditional commands (i.e. add an <literal>IF EXISTS</literal> - clause) to clean databases and other objects. This option is not valid + clause) to drop databases and other objects. This option is not valid unless <option>--clean</option> is also specified. </para> </listitem> @@ -500,10 +497,11 @@ PostgreSQL documentation <para> The option is called <literal>--dbname</literal> for consistency with other client applications, but because <application>pg_dumpall</application> - needs to connect to many databases, database name in the connection - string will be ignored. Use <literal>-l</literal> option to specify - the name of the database used to dump global objects and to discover - what other databases should be dumped. + needs to connect to many databases, the database name in the + connection string will be ignored. Use the <literal>-l</literal> + option to specify the name of the database used for the initial + connection, which will dump global objects and discover what other + databases should be dumped. </para> </listitem> </varlistentry> @@ -658,6 +656,17 @@ PostgreSQL documentation </para> <para> + The <option>--clean</option> option can be useful even when your + intention is to restore the dump script into a fresh cluster. Use of + <option>--clean</option> authorizes the script to drop and re-create the + built-in <literal>postgres</literal> and <literal>template1</literal> + databases, ensuring that those databases will retain the same properties + (for instance, locale and encoding) that they had in the source cluster. + Without the option, those databases will retain their existing + database-level properties, as well as any pre-existing contents. + </para> + + <para> Once restored, it is wise to run <command>ANALYZE</command> on each database so the optimizer has useful statistics. You can also run <command>vacuumdb -a -z</command> to analyze all @@ -665,6 +674,18 @@ PostgreSQL documentation </para> <para> + The dump script should not be expected to run completely without errors. + In particular, because the script will issue <command>CREATE ROLE</command> + for every role existing in the source cluster, it is certain to get a + <quote>role already exists</quote> error for the bootstrap superuser, + unless the destination cluster was initialized with a different bootstrap + superuser name. This error is harmless and should be ignored. Use of + the <option>--clean</option> option is likely to produce additional + harmless error messages about non-existent objects, although you can + minimize those by adding <option>--if-exists</option>. + </para> + + <para> <application>pg_dumpall</application> requires all needed tablespace directories to exist before the restore; otherwise, database creation will fail for databases in non-default @@ -688,10 +709,13 @@ PostgreSQL documentation <screen> <prompt>$</prompt> <userinput>psql -f db.out postgres</userinput> </screen> - (It is not important to which database you connect here since the + It is not important to which database you connect here since the script file created by <application>pg_dumpall</application> will contain the appropriate commands to create and connect to the saved - databases.) + databases. An exception is that if you specified <option>--clean</option>, + you must connect to the <literal>postgres</literal> database initially; + the script will attempt to drop other databases immediately, and that + will fail for the database you are connected to. </para> </refsect1> diff --git a/doc/src/sgml/ref/pg_restore.sgml b/doc/src/sgml/ref/pg_restore.sgml index 9946b94e84d..a2ebf75ebb5 100644 --- a/doc/src/sgml/ref/pg_restore.sgml +++ b/doc/src/sgml/ref/pg_restore.sgml @@ -127,6 +127,17 @@ </para> <para> + With <option>--create</option>, <application>pg_restore</application> + also restores the database's comment if any, and any configuration + variable settings that are specific to this database, that is, + any <command>ALTER DATABASE ... SET ...</command> + and <command>ALTER ROLE ... IN DATABASE ... SET ...</command> + commands that mention this database. + Access privileges for the database itself are also restored, + unless <option>--no-acl</option> is specified. + </para> + + <para> When this option is used, the database named with <option>-d</option> is used only to issue the initial <command>DROP DATABASE</command> and <command>CREATE DATABASE</command> commands. All data is restored into the |