diff options
Diffstat (limited to 'doc/src')
| -rw-r--r-- | doc/src/sgml/ref/pg_dump.sgml | 84 | ||||
| -rw-r--r-- | doc/src/sgml/ref/pg_restore.sgml | 49 |
2 files changed, 38 insertions, 95 deletions
diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml index 80dd35041f9..73ab39cef10 100644 --- a/doc/src/sgml/ref/pg_dump.sgml +++ b/doc/src/sgml/ref/pg_dump.sgml @@ -1,5 +1,5 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.64 2003/09/11 21:42:20 momjian Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.65 2003/09/23 22:48:53 tgl Exp $ PostgreSQL documentation --> @@ -318,16 +318,16 @@ PostgreSQL documentation <term><option>--no-owner</option></term> <listitem> <para> - Do not output commands to set the - object ownership to match the original database. Typically, - <application>pg_dump</application> issues - (<application>psql</application>-specific) <command>\connect</command> - statements to set ownership of schema elements. See also - under <option>-R</option> and <option>-X - use-set-session-authorization</option>. Note that - <option>-O</option> does not prevent all reconnections to the - database, only the ones that are exclusively used for - ownership adjustments. + Do not output commands to set + ownership of objects to match the original database. + By default, <application>pg_dump</application> issues + <command>SET SESSION AUTHORIZATION</command> + statements to set ownership of created schema elements. + These statements + will fail when the script is run unless it is started by a superuser + (or the same user that owns all of the objects in the script). + To make a script that can be restored by any user, but will give + that user ownership of all the objects, specify <option>-O</>. </para> <para> @@ -343,27 +343,8 @@ PostgreSQL documentation <term><option>--no-reconnect</option></term> <listitem> <para> - Prohibit <application>pg_dump</application> - from outputting a script that would require reconnections to - the database while being restored. An average restoration - script usually has to reconnect several times as different - users to set the original ownerships of the objects. This - option is a rather blunt instrument because it makes - <application>pg_dump</application> lose this ownership information, - <emphasis>unless</emphasis> you use the <option>-X - use-set-session-authorization</option> option. - </para> - - <para> - One possible reason why reconnections during restore might not - be desired is if the access to the database requires manual - interaction (e.g., passwords). - </para> - - <para> - This option is only meaningful for the plain-text format. For - the other formats, you may specify the option when you - call <command>pg_restore</command>. + This option is obsolete but still accepted for backwards + compatibility. </para> </listitem> </varlistentry> @@ -385,8 +366,7 @@ PostgreSQL documentation <para> Specify the superuser user name to use when disabling triggers. This is only relevant if <option>--disable-triggers</> is used. - (Usually, it's better to specify - <option>--use-set-session-authorization</>, and then start the + (Usually, it's better to leave this out, and instead start the resulting script as superuser.) </para> </listitem> @@ -444,32 +424,10 @@ PostgreSQL documentation <term><option>--use-set-session-authorization</></term> <listitem> <para> - Normally, if a (plain-text mode) script generated by - <application>pg_dump</application> must alter the current database - user (e.g., to set correct object ownerships), it uses the - <application>psql</application> <command>\connect</command> command. - This command actually opens a new connection, which might - require manual interaction (e.g., passwords). If you use the - <option>-X use-set-session-authorization</option> option, then - <application>pg_dump</application> will instead output <xref - linkend="sql-set-session-authorization" endterm="sql-set-session-authorization-title"> commands. This has - the same effect, but it requires that the user restoring the - database from the generated script be a database superuser. - This option effectively overrides the <option>-R</option> - option. - </para> - - <para> - Since <xref linkend="sql-set-session-authorization" endterm="sql-set-session-authorization-title"> is a - standard SQL command, whereas <command>\connect</command> only - works in <application>psql</application>, this option also enhances - the theoretical portability of the output script. - </para> - - <para> - This option is only meaningful for the plain-text format. For - the other formats, you may specify the option when you - call <command>pg_restore</command>. + This option is obsolete but still accepted for backwards + compatibility. + <application>pg_dump</application> now always behaves in the + way formerly selected by this option. </para> </listitem> </varlistentry> @@ -490,10 +448,8 @@ PostgreSQL documentation <para> Presently, the commands emitted for <option>--disable-triggers</> must be done as superuser. So, you should also specify - a superuser name with <option>-S</>, or preferably specify - <option>--use-set-session-authorization</> and then be careful to - start the resulting script as a superuser. If you give neither - option, the entire script must be run as superuser. + a superuser name with <option>-S</>, or preferably be careful to + start the resulting script as a superuser. </para> <para> diff --git a/doc/src/sgml/ref/pg_restore.sgml b/doc/src/sgml/ref/pg_restore.sgml index 1600925af84..88319e2e344 100644 --- a/doc/src/sgml/ref/pg_restore.sgml +++ b/doc/src/sgml/ref/pg_restore.sgml @@ -1,4 +1,4 @@ -<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.42 2003/09/11 21:42:20 momjian Exp $ --> +<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.43 2003/09/23 22:48:53 tgl Exp $ --> <refentry id="APP-PGRESTORE"> <refmeta> @@ -261,10 +261,16 @@ <term><option>--no-owner</option></term> <listitem> <para> - Prevent any attempt to restore original object - ownership. Objects will be owned by the user name used to - attach to the database. See also under <option>-R</option> and - <option>-X use-set-session-authorization</option>. + Do not output commands to set + ownership of objects to match the original database. + By default, <application>pg_restore</application> issues + <command>SET SESSION AUTHORIZATION</command> + statements to set ownership of created schema elements. + These statements will fail unless the initial connection to the + database is made by a superuser + (or the same user that owns all of the objects in the script). + With <option>-O</option>, any user name can be used for the + initial connection, and this user will own all the created objects. </para> </listitem> </varlistentry> @@ -311,20 +317,8 @@ <term><option>--no-reconnect</option></term> <listitem> <para> - While restoring an archive, <application>pg_restore</application> - typically has to reconnect to the database several times with - different user names to set the correct ownership of the - created objects. If this is undesirable (e.g., because manual - interaction (passwords) would be necessary for each - reconnection), this option prevents - <application>pg_restore</application> from issuing any reconnection - requests. (A connection request while in plain text mode, not - connected to a database, is made by putting out a <xref - linkend="app-psql"> <command>\connect</command> command.) - However, this option is a rather blunt instrument because it - makes <application>pg_restore</application> lose all object ownership - information, <emphasis>unless</emphasis> you use the - <option>-X use-set-session-authorization</option> option. + This option is obsolete but still accepted for backwards + compatibility. </para> </listitem> </varlistentry> @@ -397,16 +391,10 @@ <term><option>--use-set-session-authorization</option></term> <listitem> <para> - Normally, if restoring an archive requires altering the - current database user (e.g., to set correct object - ownerships), a new connection to the database must be opened, - which might require manual interaction (e.g., passwords). If - you use the <option>-X use-set-session-authorization</option> option, - then <application>pg_restore</application> will instead use the <xref - linkend="sql-set-session-authorization" endterm="sql-set-session-authorization-title"> command. This has - the same effect, but it requires that the user restoring the - archive is a database superuser. This option effectively - overrides the <option>-R</option> option. + This option is obsolete but still accepted for backwards + compatibility. + <application>pg_restore</application> now always behaves in the + way formerly selected by this option. </para> </listitem> </varlistentry> @@ -428,8 +416,7 @@ Presently, the commands emitted for <option>--disable-triggers</> must be done as superuser. So, you should also specify a superuser name with <option>-S</>, or - preferably specify <option>--use-set-session-authorization</> and - run <application>pg_restore</application> as a + preferably run <application>pg_restore</application> as a <productname>PostgreSQL</> superuser. </para> </listitem> |