<!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/ipcclean.sgml,v 1.10 2003/11/29 19:51:39 pgsql Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/ipcclean.sgml,v 1.11 2005/01/04 03:58:16 tgl Exp $
PostgreSQL documentation
-->
<refnamediv>
<refname>ipcclean</refname>
- <refpurpose>remove shared memory and semaphores from a
n aborted <productname>PostgreSQL</productname> server</refpurpose>
+ <refpurpose>remove shared memory and semaphores from a
failed <productname>PostgreSQL</productname> server</refpurpose>
</refnamediv>
<indexterm zone="app-ipcclean">
</para>
<para>
- The script makes assumption about the format of output of the
+ The script makes assumptions about the output format of the
<command>ipcs</command>
utility which may not be true across different operating systems.
- Therefore, it may not work on your particular OS.
+ Therefore, it may not work on your particular OS. It's wise to
+ look at the script before trying it.
</para>
</refsect1>
-<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/pg_config-ref.sgml,v 1.18 2004/08/02 12:34:14 momjian Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/pg_config-ref.sgml,v 1.19 2005/01/04 03:58:16 tgl Exp $ -->
<refentry id="app-pgconfig">
<refmeta>
</para>
<para>
- In releases prior to <productname>PostgreSQL</> 7.1, before the
+ In releases prior to <productname>PostgreSQL</> 7.1, before
<command>pg_config</command> came to be, a method for finding the
equivalent configuration information did not exist.
</para>
<!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.74 2004/10/21 22:48:54 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.75 2005/01/04 03:58:16 tgl Exp $
PostgreSQL documentation
-->
</para>
<para>
- Dumps can be output in script or archive file formats. The script
- files are in plain-text format and contain the SQL commands required
+ Dumps can be output in script or archive file formats. Script
+ dumps are plain-text files containing the SQL commands required
to reconstruct the database to the state it was in at the time it was
- saved. To restore these scripts, use <xref linkend="app-psql">. They
+ saved. To restore from such a script, feed it to <xref
+ linkend="app-psql">. Script files
can be used to reconstruct the database even on other machines and
- other architectures, with some modifications even on other SQL
+ other architectures; with some modifications even on other SQL
database products.
</para>
<para>
- The alternative archive file formats that are meant to be used with
- <xref linkend="app-pgrestore"> to rebuild the database, and they also
+ The alternative archive file formats must be used with
+ <xref linkend="app-pgrestore"> to rebuild the database. They
allow <application>pg_restore</application> to be selective about
what is restored, or even to reorder the items prior to being
- restored. The archive files are also designed to be portable across
+ restored. The archive formats also allow saving and restoring
+ <quote>large objects</>, which is not possible in a script dump.
+ The archive files are also designed to be portable across
architectures.
</para>
by default. The <application>tar</application> format
(<option>-Ft</option>) is not compressed and it is not possible to
reorder data when loading, but it is otherwise quite flexible;
- moreover, it can be manipulated with other tools such as
+ moreover, it can be manipulated with standard Unix tools such as
<command>tar</command>.
</para>
<title>Options</title>
<para>
- The following command-line options are used to control the output format.
+ The following command-line options control the content and
+ format of the output.
<variablelist>
<varlistentry>
<term><replaceable class="parameter">dbname</replaceable></term>
<listitem>
<para>
- Specifies the name of the database to be dumped. If this is
- not specified, the environment variable
- <envar>PGDATABASE</envar> is used. If that is not set, the
- user name specified for the connection is used.
+ Specifies the name of the database to be dumped. If this is
+ not specified, the environment variable
+ <envar>PGDATABASE</envar> is used. If that is not set, the
+ user name specified for the connection is used.
</para>
</listitem>
</varlistentry>
<term><option>--data-only</></term>
<listitem>
<para>
- Dump only the data, not the object definitions (schema)
+ Dump only the data, not the schema (data definitions).
</para>
<para>
This option is only meaningful for the plain-text format. For
- the other formats, you may specify the option when you
+ the archive formats, you may specify the option when you
call <command>pg_restore</command>.
</para>
</listitem>
<term><option>--blobs</></term>
<listitem>
<para>
- Include large objects in dump.
+ Include large objects in the dump. A non-text output format
+ must be selected.
</para>
</listitem>
</varlistentry>
<listitem>
<para>
Output commands to clean (drop)
- database objects prior to (the commands for) creating them.
+ database objects prior to (the commands for) creating them.
</para>
<para>
This option is only meaningful for the plain-text format. For
- the other formats, you may specify the option when you
+ the archive formats, you may specify the option when you
call <command>pg_restore</command>.
</para>
</listitem>
<term><option>--create</></term>
<listitem>
<para>
- Begin the output with a command to create the
- database itself and reconnect to the created database. (With a
- script of this form, it doesn't matter which database you connect
- to before running the script.)
+ Begin the output with a command to create the
+ database itself and reconnect to the created database. (With a
+ script of this form, it doesn't matter which database you connect
+ to before running the script.)
</para>
<para>
This option is only meaningful for the plain-text format. For
- the other formats, you may specify the option when you
+ the archive formats, you may specify the option when you
call <command>pg_restore</command>.
</para>
</listitem>
<term><option>--inserts</option></term>
<listitem>
<para>
- Dump data as <command>INSERT</command> commands (rather
- than <command>COPY</command>). This will make restoration very slow;
- it is mainly useful for making dumps that can be loaded into
- non-<productname>PostgreSQL</productname> databases. Note that
- the restore may fail altogether if you have rearranged column order.
- The <option>-D</option> option is safer, though even slower.
+ Dump data as <command>INSERT</command> commands (rather
+ than <command>COPY</command>). This will make restoration very slow;
+ it is mainly useful for making dumps that can be loaded into
+
non-<productname>PostgreSQL</productname> databases. Note that
+ the restore may fail altogether if you have rearranged column order.
+ The <option>-D</option> option is safer, though even slower.
</para>
</listitem>
</varlistentry>
<term><option>--attribute-inserts</option></term>
<listitem>
<para>
- Dump data as <command>INSERT</command> commands with explicit
- column names (<literal>INSERT INTO
- <replaceable>table</replaceable>
- (<replaceable>column</replaceable>, ...) VALUES
- ...</literal>). This will make restoration very slow; it is mainly
- useful for making dumps that can be loaded into
- non-<productname>PostgreSQL</productname> databases.
+ Dump data as <command>INSERT</command> commands with explicit
+ column names (<literal>INSERT INTO
+ <replaceable>table</replaceable>
+ (<replaceable>column</replaceable>, ...) VALUES
+ ...</literal>). This will make restoration very slow; it is mainly
+ useful for making dumps that can be loaded into
+
non-<productname>PostgreSQL</productname> databases.
</para>
</listitem>
</varlistentry>
<term><option>--file=<replaceable class="parameter">file</replaceable></option></term>
<listitem>
<para>
- Send output to the specified file. If this is omitted, the
- standard output is used.
+ Send output to the specified file. If this is omitted, the
+ standard output is used.
</para>
</listitem>
</varlistentry>
<listitem>
<para>
Selects the format of the output.
- <replaceable>format</replaceable> can be one of the following:
+ <replaceable>format</replaceable> can be one of the following:
<variablelist>
<varlistentry>
<para>
In this mode, <application>pg_dump</application> makes no
attempt to dump any other database objects that objects in the
- selected schema may depend upon. Therefore, there is no
+ selected schema may depend upon. Therefore, there is no
guarantee that the results of a single-schema dump can be
successfully restored by themselves into a clean database.
</para>
<term><option>--oids</></term>
<listitem>
<para>
- Dump object identifiers (<acronym>OID</acronym>s) for every
- table. Use this option if your application references the <acronym>OID</>
- columns in some way (e.g., in a foreign key constraint).
- Otherwise, this option should not be used.
+ Dump object identifiers (<acronym>OID</acronym>s) as part of the
+ data for every table. Use this option if your application references
+ the <acronym>OID</>
+ columns in some way (e.g., in a foreign key constraint).
+ Otherwise, this option should not be used.
</para>
</listitem>
</varlistentry>
<listitem>
<para>
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 database objects.
- 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</>.
+ ownership of objects to match the original database.
+ By default, <application>pg_dump</application> issues
+ <command>ALTER OWNER</> or
+ <command>SET SESSION AUTHORIZATION</command>
+ statements to set ownership of created database objects.
+ 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>
This option is only meaningful for the plain-text format. For
- the other formats, you may specify the option when you
+ the archive formats, you may specify the option when you
call <command>pg_restore</command>.
</para>
</listitem>
<listitem>
<para>
This option is obsolete but still accepted for backwards
- compatibility.
+ compatibility.
</para>
</listitem>
</varlistentry>
<term><option>--schema-only</option></term>
<listitem>
<para>
- Dump only the object definitions (schema), not data.
+ Dump only the object definitions (schema), not data.
</para>
</listitem>
</varlistentry>
<listitem>
<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 leave this out, and instead start the
- resulting script as superuser.)
+ This is only relevant if <option>--disable-triggers</> is used.
+ (Usually, it's better to leave this out, and instead start the
+ resulting script as superuser.)
</para>
</listitem>
</varlistentry>
<term><option>--table=<replaceable class="parameter">table</replaceable></option></term>
<listitem>
<para>
- Dump data for <replaceable class="parameter">table</replaceable>
- only. It is possible for there to be
- multiple tables with the same name in different schemas; if that
- is the case, all matching tables will be dumped. Specify both
- <option>--schema</> and <option>--table</> to select just one table.
+ Dump data for <replaceable class="parameter">table</replaceable>
+ only. It is possible for there to be
+ multiple tables with the same name in different schemas; if that
+ is the case, all matching tables will be dumped. Specify both
+ <option>--schema</> and <option>--table</> to select just one table.
</para>
<note>
<para>
In this mode, <application>pg_dump</application> makes no
attempt to dump any other database objects that the selected table
- may depend upon. Therefore, there is no guarantee
+ may depend upon. Therefore, there is no guarantee
that the results of a single-table dump can be successfully
restored by themselves into a clean database.
</para>
<term><option>--verbose</></term>
<listitem>
<para>
- Specifies verbose mode. This will cause
- <application>pg_dump</application> to output detailed object
+ Specifies verbose mode. This will cause
+
<application>pg_dump</application> to output detailed object
comments and start/stop times to the dump file, and progress
messages to standard error.
</para>
<term><option>--no-acl</></term>
<listitem>
<para>
- Prevent dumping of access privileges (grant/revoke commands).
+ Prevent dumping of access privileges (grant/revoke commands).
</para>
</listitem>
</varlistentry>
<para>
This option is only meaningful for the plain-text format. For
- the other formats, you may specify the option when you
+ the archive formats, you may specify the option when you
call <command>pg_restore</command>.
</para>
</listitem>
<term><option>--use-set-session-authorization</></term>
<listitem>
<para>
- Output SQL standard SET SESSION AUTHORIZATION commands instead
- of OWNER TO commands. This makes the dump more standards compatible,
- but depending on the history of the objects in the dump, may not
- restore properly.
+ Output SQL standard SET SESSION AUTHORIZATION commands instead
+ of OWNER TO commands. This makes the dump more standards compatible,
+ but depending on the history of the objects in the dump, may not
+ restore properly.
</para>
</listitem>
</varlistentry>
<term><option>--port=<replaceable class="parameter">port</replaceable></option></term>
<listitem>
<para>
- Specifies the TCP port or local Unix domain socket file
- extension on which the server is listening for connections.
- Defaults to the <envar>PGPORT</envar> environment variable, if
- set, or a compiled-in default.
+ Specifies the TCP port or local Unix domain socket file
+ extension on which the server is listening for connections.
+ Defaults to the <envar>PGPORT</envar> environment variable, if
+ set, or a compiled-in default.
</para>
</listitem>
</varlistentry>
<para>
Members of tar archives are limited to a size less than 8 GB.
(This is an inherent limitation of the tar file format.) Therefore
- this format cannot be used if the textual representation of a table
+ this format cannot be used if the textual representation of any one table
exceeds that size. The total size of a tar archive and any of the
other output formats is not limited, except possibly by the
operating system.
<!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/pg_dumpall.sgml,v 1.46 2004/07/19 21:39:46 momjian Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/pg_dumpall.sgml,v 1.47 2005/01/04 03:58:16 tgl Exp $
PostgreSQL documentation
-->
<para>
<application>pg_dumpall</application> needs to connect several
- times to the <productname>PostgreSQL</productname> server and might be asking for
+ times to the <productname>PostgreSQL</productname> server (once per
+ database). If you use password authentication it is likely to ask for
a password each time. It is convenient to have a
<filename>$HOME/.pgpass</> file in such cases.
</para>
<title>Options</title>
<para>
- The following command-line options are used to control the content and
+ The following command-line options control the content and
format of the output.
<variablelist>
<term><option>--data-only</></term>
<listitem>
<para>
- Dump only the data, not the schema (data definitions).
+ Dump only the data, not the schema (data definitions).
</para>
</listitem>
</varlistentry>
<term><option>--clean</option></term>
<listitem>
<para>
- Include SQL commands to clean (drop) the databases before
- recreating them.
+ Include SQL commands to clean (drop) the databases before
+ recreating them.
</para>
</listitem>
</varlistentry>
<term><option>--inserts</option></term>
<listitem>
<para>
- Dump data as <command>INSERT</command> commands (rather
- than <command>COPY</command>). This will make restoration very
- slow, but it makes the output more portable to other SQL database
- management systems.
+ Dump data as <command>INSERT</command> commands (rather
+ than <command>COPY</command>). This will make restoration very slow;
+ it is mainly useful for making dumps that can be loaded into
+ non-<productname>PostgreSQL</productname> databases. Note that
+ the restore may fail altogether if you have rearranged column order.
+ The <option>-D</option> option is safer, though even slower.
</para>
</listitem>
</varlistentry>
<term><option>--attribute-inserts</option></term>
<listitem>
<para>
- Dump data as <command>INSERT</command> commands with explicit
- column names (<literal>INSERT INTO
- <replaceable>table</replaceable>
- (<replaceable>column</replaceable>, ...) VALUES
- ...</literal>). This will make restoration very slow,
- but it is necessary if you desire to rearrange column ordering.
+ Dump data as <command>INSERT</command> commands with explicit
+ column names (<literal>INSERT INTO
+ <replaceable>table</replaceable>
+ (<replaceable>column</replaceable>, ...) VALUES
+ ...</literal>). This will make restoration very slow; it is mainly
+ useful for making dumps that can be loaded into
+ non-<productname>PostgreSQL</productname> databases.
</para>
</listitem>
</varlistentry>
<term><option>--globals-only</option></term>
<listitem>
<para>
- Dump only global objects (users and groups), no databases.
+ Dump only global objects (users and groups), no databases.
</para>
</listitem>
</varlistentry>
<term><option>--oids</></term>
<listitem>
<para>
- Dump object identifiers (<acronym>OID</acronym>s) for every
- table. Use this option if your application references the OID
- columns in some way (e.g., in a foreign key constraint).
- Otherwise, this option should not be used.
+ Dump object identifiers (<acronym>OID</acronym>s) as part of the
+ data for every table. Use this option if your application references
+ the <acronym>OID</>
+ columns in some way (e.g., in a foreign key constraint).
+ Otherwise, this option should not be used.
</para>
</listitem>
</varlistentry>
<listitem>
<para>
Do not output commands to set
- ownership of objects to match the original database.
- By default, <application>pg_dumpall</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</>.
+ ownership of objects to match the original database.
+ By default, <application>pg_dumpall</application> issues
+ <command>ALTER OWNER</> or
+ <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>
</listitem>
</varlistentry>
<term><option>--schema-only</option></term>
<listitem>
<para>
- Dump only the schema (data definitions), no data.
+ Dump only the object definitions (schema), not data.
</para>
</listitem>
</varlistentry>
<listitem>
<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 leave this out, and instead start the
- resulting script as superuser.)
+ This is only relevant if <option>--disable-triggers</> is used.
+ (Usually, it's better to leave this out, and instead start the
+ resulting script as superuser.)
</para>
</listitem>
</varlistentry>
<term><option>--verbose</></term>
<listitem>
<para>
- Specifies verbose mode. This will cause
- <application>pg_dumpall</application> to output start/stop
+ Specifies verbose mode. This will cause
+
<application>pg_dumpall</application> to output start/stop
times to the dump file, and progress messages to standard error.
It will also enable verbose output in <application>pg_dump</>.
</para>
<term><option>--no-acl</></term>
<listitem>
<para>
- Prevent dumping of access privileges (grant/revoke commands).
+ Prevent dumping of access privileges (grant/revoke commands).
</para>
</listitem>
</varlistentry>
<term><option>--use-set-session-authorization</></term>
<listitem>
<para>
- Output SQL standard SET SESSION AUTHORIZATION commands instead
- of OWNER TO commands. This makes the dump more standards compatible,
- but depending on the history of the objects in the dump, may not
- restore properly.
+ Output SQL standard SET SESSION AUTHORIZATION commands instead
+ of OWNER TO commands. This makes the dump more standards compatible,
+ but depending on the history of the objects in the dump, may not
+ restore properly.
</para>
</listitem>
</varlistentry>
<term>-h <replaceable>host</replaceable></term>
<listitem>
<para>
- Specifies the host name of the machine on which the database
- server is running. If the value begins with a slash, it is
- used as the directory for the Unix domain socket. The default
- is taken from the <envar>PGHOST</envar> environment variable,
- if set, else a Unix domain socket connection is attempted.
+ Specifies the host name of the machine on which the database
+ server is running. If the value begins with a slash, it is
+ used as the directory for the Unix domain socket. The default
+ is taken from the <envar>PGHOST</envar> environment variable,
+ if set, else a Unix domain socket connection is attempted.
</para>
</listitem>
</varlistentry>
<term>-p <replaceable>port</replaceable></term>
<listitem>
<para>
- Specifies the TCP port or local Unix domain socket file
- extension on which the server is listening for connections.
- Defaults to the <envar>PGPORT</envar> environment variable, if
- set, or a compiled-in default.
+ Specifies the TCP port or local Unix domain socket file
+ extension on which the server is listening for connections.
+ Defaults to the <envar>PGPORT</envar> environment variable, if
+ set, or a compiled-in default.
</para>
</listitem>
</varlistentry>
-<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.48 2004/08/20 04:20:22 momjian Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.49 2005/01/04 03:58:16 tgl Exp $ -->
<refentry id="APP-PGRESTORE">
<refmeta>
<term><option>--data-only</option></term>
<listitem>
<para>
- Restore only the data, not the schema (data definitions).
+ Restore only the data, not the schema (data definitions).
</para>
</listitem>
</varlistentry>
<term><option>--clean</option></term>
<listitem>
<para>
- Clean (drop) database objects before recreating them.
+ Clean (drop) database objects before recreating them.
</para>
</listitem>
</varlistentry>
<term><option>--format=<replaceable class="parameter">format</replaceable></option></term>
<listitem>
<para>
- Specify format of the archive. It is not necessary to specify
- the format, since <application>pg_restore</application> will
- determine the format automatically. If specified, it can be
- one of the following:
+ Specify format of the archive. It is not necessary to specify
+
the format, since <application>pg_restore</application> will
+ determine the format automatically. If specified, it can be
+ one of the following:
<variablelist>
<varlistentry>
<term><option>--ignore-version</option></term>
<listitem>
<para>
- Ignore database version checks.
+ Ignore database version checks.
</para>
</listitem>
</varlistentry>
<term><option>--index=<replaceable class="parameter">index</replaceable></option></term>
<listitem>
<para>
- Restore definition of named index only.
+ Restore definition of named index only.
</para>
</listitem>
</varlistentry>
<listitem>
<para>
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.
+ ownership of objects to match the original database.
+ By default, <application>pg_restore</application> issues
+ <command>ALTER OWNER</> or
+ <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>
<listitem>
<para>
Restore the named function only. Be careful to spell the function
- name and arguments exactly as they appear in the dump file's table
- of contents.
+ name and arguments exactly as they appear in the dump file's table
+ of contents.
</para>
</listitem>
</varlistentry>
<listitem>
<para>
This option is obsolete but still accepted for backwards
- compatibility.
+ compatibility.
</para>
</listitem>
</varlistentry>
<listitem>
<para>
Specify the superuser user name to use when disabling triggers.
- This is only relevant if <option>--disable-triggers</> is used.
+ This is only relevant if <option>--disable-triggers</> is used.
</para>
</listitem>
</varlistentry>
<term><option>--verbose</option></term>
<listitem>
<para>
- Specifies verbose mode.
+ Specifies verbose mode.
</para>
</listitem>
</varlistentry>
<term><option>--no-acl</option></term>
<listitem>
<para>
- Prevent restoration of access privileges (grant/revoke commands).
+ Prevent restoration of access privileges (grant/revoke commands).
</para>
</listitem>
</varlistentry>
<term><option>--use-set-session-authorization</option></term>
<listitem>
<para>
- Output SQL standard SET SESSION AUTHORIZATION commands instead
- of OWNER TO commands. This makes the dump more standards compatible,
- but depending on the history of the objects in the dump, may not
- restore properly.
+ Output SQL standard SET SESSION AUTHORIZATION commands instead
+ of OWNER TO commands. This makes the dump more standards compatible,
+ but depending on the history of the objects in the dump, may not
+ restore properly.
</para>
</listitem>
</varlistentry>
<listitem>
<para>
This option is only relevant when performing a data-only restore.
- It instructs <application>pg_restore</application> to execute commands
- to temporarily disable triggers on the target tables while
- the data is reloaded. Use this if you have referential
- integrity checks or other triggers on the tables that you
- do not want to invoke during data reload.
+
It instructs <application>pg_restore</application> to execute commands
+ to temporarily disable triggers on the target tables while
+ the data is reloaded. Use this if you have referential
+ integrity checks or other triggers on the tables that you
+ do not want to invoke during data reload.
</para>
<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 run <application>pg_restore</application> as a
- <productname>PostgreSQL</> superuser.
+ <option>--disable-triggers</> must be done as superuser. So, you
+ should also specify a superuser name with <option>-S</>, or
+
preferably run <application>pg_restore</application> as a
+
<productname>PostgreSQL</> superuser.
</para>
</listitem>
</varlistentry>
<term><option>--host=<replaceable class="parameter">host</replaceable></option></term>
<listitem>
<para>
- Specifies the host name of the machine on which the server is
- running. If the value begins with a slash, it is used as the
- directory for the Unix domain socket. The default is taken
- from the <envar>PGHOST</envar> environment variable, if set,
- else a Unix domain socket connection is attempted.
+ Specifies the host name of the machine on which the server is
+ running. If the value begins with a slash, it is used as the
+ directory for the Unix domain socket. The default is taken
+ from the <envar>PGHOST</envar> environment variable, if set,
+ else a Unix domain socket connection is attempted.
</para>
</listitem>
</varlistentry>
<term><option>--port=<replaceable class="parameter">port</replaceable></option></term>
<listitem>
<para>
- Specifies the TCP port or local Unix domain socket file
- extension on which the server is listening for connections.
- Defaults to the <envar>PGPORT</envar> environment variable, if
- set, or a compiled-in default.
+ Specifies the TCP port or local Unix domain socket file
+ extension on which the server is listening for connections.
+ Defaults to the <envar>PGPORT</envar> environment variable, if
+ set, or a compiled-in default.
</para>
</listitem>
</varlistentry>
<!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.126 2004/12/28 23:17:38 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.127 2005/01/04 03:58:16 tgl Exp $
PostgreSQL documentation
-->
<term><option>--echo-all</></term>
<listitem>
<para>
- Print all the lines to the screen as they are read. This is more
+ Print all input lines to standard output as they are read. This is more
useful for script processing rather than interactive mode. This is
equivalent to setting the variable <varname>ECHO</varname> to
<literal>all</literal>.
<replaceable class="parameter">command</replaceable> must be either
a command string that is completely parsable by the server (i.e.,
it contains no <application>psql</application> specific features),
- or it is a single backslash command. Thus you cannot mix
+ or a single backslash command. Thus you cannot mix
<acronym>SQL</acronym> and <application>psql</application>
meta-commands. To achieve that, you could pipe the string into
<application>psql</application>, like this: <literal>echo "\x \\
<term><option>--echo-queries</></term>
<listitem>
<para>
- Show all commands that are sent to the server. This is equivalent
+ Copy all SQL commands sent to the server to standard output as well.
+ This is equivalent
to setting the variable <varname>ECHO</varname> to
<literal>queries</literal>.
</para>
<listitem>
<para>
Echo the actual queries generated by <command>\d</command> and other backslash
- commands. You can use this if you wish to include similar
- functionality into your own programs. This is equivalent to
+ commands. You can use this to study <application>psql</application>'s
+ internal operations. This is equivalent to
setting the variable <varname>ECHO_HIDDEN</varname> from within
<application>psql</application>.
</para>
<term><option>--list</></term>
<listitem>
<para>
- List all available databases, then exits. Other non-connection
+ List all available databases, then exit. Other non-connection
options are ignored. This is similar to the internal command
<command>\list</command>.
</para>
<listitem>
<para>
Turn off printing of column names and result row count footers,
- etc. It is completely equivalent to the <command>\t</command>
- meta-command.
+ etc. This is equivalent to the <command>\t</command> command.
</para>
</listitem>
</varlistentry>
<term><option>--version</></term>
<listitem>
<para>
- Show the <application>psql</application> version.
+ Print the <application>psql</application> version and exit.
</para>
</listitem>
</varlistentry>
<term><option>--password</></term>
<listitem>
<para>
- Requests that <application>psql</application> should prompt for a
+ Cause <application>psql</application> to prompt for a
password before connecting to a database. This will remain set for
the entire session, even if you change the database connection
with the meta-command <command>\connect</command>.
requests password authentication. Because this is currently based
on a hack, the automatic recognition might mysteriously fail,
hence this option to force a prompt. If no password prompt is
- issued and the server requires password authentication the
+ issued and the server requires password authentication, the
connection attempt will fail.
</para>
</listitem>
<listitem>
<para>
Show help about <application>psql</application> command line
- arguments.
+ arguments, and exit.
</para>
</listitem>
</varlistentry>
Ordinarily, input lines are sent to the server when a
command-terminating semicolon is reached. An end of line does not
terminate a command. Thus commands can be spread over several lines for
- clarity. If the command was sent and without error, the results of the command
- are displayed on the screen.
+ clarity. If the command was sent and executed without error, the results
+ of the command are displayed on the screen.
</para>
<para>
Anything you enter in <application>psql</application> that begins
with an unquoted backslash is a <application>psql</application>
meta-command that is processed by <application>psql</application>
- itself. These commands are what makes
- <application>psql</application> interesting for administration or
+ itself. These commands help make
+ <application>psql</application> more useful for administration or
scripting. Meta-commands are more commonly called slash or backslash
commands.
</para>
If the current table output format is unaligned, it is switched to aligned.
If it is not unaligned, it is set to unaligned. This command is
kept for backwards compatibility. See <command>\pset</command> for a
- general solution.
+ more general solution.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>\db [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
+ <term><literal>\db+ [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
<listitem>
<para>
<varlistentry>
<term><literal>\dn [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
+ <term><literal>\dn+ [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
<listitem>
<para>
<application>psql</application> searches the environment
variables <envar>PSQL_EDITOR</envar>, <envar>EDITOR</envar>, and
<envar>VISUAL</envar> (in that order) for an editor to use. If
- all of them are unset, <filename>/bin/vi</filename> is run.
+ all of them are unset, <filename>vi</filename> is used on Unix
+ systems, <filename>notepad.exe</filename> on Windows systems.
</para>
</tip>
</listitem>
<listitem>
<para>
Sends the current query input buffer to the server and
- optionally saves the output in <replaceable
+ optionally stores the query's output in <replaceable
class="parameter">filename</replaceable> or pipes the output
- into a separate Unix shell to execute <replaceable
+ into a separate Unix shell executing <replaceable
class="parameter">command</replaceable>. A bare
<literal>\g</literal> is virtually equivalent to a semicolon. A
<literal>\g</literal> with argument is a <quote>one-shot</quote>
<listitem>
<para>
This command is identical to <command>\echo</command> except
- that all output will be written to the query output channel, as
+ that the output will be written to the query output channel, as
set by <command>\o</command>.
</para>
</listitem>
<listitem>
<para>
If set to <literal>all</literal>, all lines
- entered or from a script are written to the standard output
+ entered from the keyboard or from a script are written to the standard output
before they are parsed or executed. To select this behavior on program
start-up, use the switch <option>-a</option>. If set to
<literal>queries</literal>,
disconnected from the database (which can happen if
<command>\connect</command> fails). In prompt 2 the sequence is
replaced by <literal>-</literal>, <literal>*</literal>, a single quote,
- or a double quote, depending on whether
+ a double quote, or a dollar sign, depending on whether
<application>psql</application> expects more input because the
command wasn't terminated yet, because you are inside a
<literal>/* ... */</literal> comment, or because you are inside
- a quote. In prompt 3 the sequence doesn't produce anything.
+ a quoted or dollar-escaped string. In prompt 3 the sequence doesn't
+ produce anything.
</para>
</listitem>
</varlistentry>
<application>psql</application> starts up. Tab-completion is also
supported, although the completion logic makes no claim to be an
<acronym>SQL</acronym> parser. If for some reason you do not like the tab completion, you
- can turn if off by putting this in a file named
+ can turn it off by putting this in a file named
<filename>.inputrc</filename> in your home directory:
<programlisting>
$if psql
<programlisting>
testdb=> <userinput>CREATE TABLE my_table (</userinput>
testdb(> <userinput> first integer not null default 0,</userinput>
-testdb(> <userinput> second text</userinput>
-testdb-> <userinput>);</userinput>
+testdb(> <userinput> second text)</userinput>
+testdb-> <userinput>;</userinput>
CREATE TABLE
</programlisting>
Now look at the table definition again:
(4 rows)
</programlisting>
- You can make this table look differently by using the
+ You can display tables in different ways by using the
<command>\pset</command> command:
<programlisting>
peter@localhost testdb=> <userinput>\pset border 2</userinput>
<!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.78 2004/11/27 21:27:07 petere Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.79 2005/01/04 03:58:16 tgl Exp $
PostgreSQL documentation
-->
</para>
</listitem>
+ <listitem>
+ <para>
+ The actual output rows are computed using the
+ <command>SELECT</command> output expressions for each selected
+ row. (See
+ <xref linkend="sql-select-list" endterm="sql-select-list-title">
+ below.)
+ </para>
+ </listitem>
+
<listitem>
<para>
Using the operators <literal>UNION</literal>,
</para>
</listitem>
- <listitem>
- <para>
- The actual output rows are computed using the
- <command>SELECT</command> output expressions for each selected
- row. (See
- <xref linkend="sql-select-list" endterm="sql-select-list-title">
- below.)
- </para>
- </listitem>
-
<listitem>
<para>
If the <literal>ORDER BY</literal> clause is specified, the
appears within an aggregate function.
</para>
</refsect2>
+
+ <refsect2 id="sql-select-list">
+ <title id="sql-select-list-title"><command>SELECT</command> List</title>
+
+ <para>
+ The <command>SELECT</command> list (between the key words
+ <literal>SELECT</> and <literal>FROM</>) specifies expressions
+ that form the output rows of the <command>SELECT</command>
+ statement. The expressions can (and usually do) refer to columns
+ computed in the <literal>FROM</> clause. Using the clause
+ <literal>AS <replaceable
+ class="parameter">output_name</replaceable></literal>, another
+ name can be specified for an output column. This name is
+ primarily used to label the column for display. It can also be
+ used to refer to the column's value in <literal>ORDER BY</> and
+ <literal>GROUP BY</> clauses, but not in the <literal>WHERE</> or
+ <literal>HAVING</> clauses; there you must write out the
+ expression instead.
+ </para>
+
+ <para>
+ Instead of an expression, <literal>*</literal> can be written in
+ the output list as a shorthand for all the columns of the selected
+ rows. Also, one can write <literal><replaceable
+ class="parameter">table_name</replaceable>.*</literal> as a
+ shorthand for the columns coming from just that table.
+ </para>
+ </refsect2>
<refsect2 id="SQL-UNION">
<title id="sql-union-title"><literal>UNION</literal> Clause</title>
<para>
The result of <literal>UNION</> does not contain any duplicate
rows unless the <literal>ALL</> option is specified.
- <literal>ALL</> prevents elimination of duplicates.
+ <literal>ALL</> prevents elimination of duplicates. (Therefore,
+ <literal>UNION ALL</> is usually significantly quicker than
+ <literal>UNION</>; use <literal>ALL</> when you can.)
</para>
<para>
<para>
The result of <literal>INTERSECT</literal> does not contain any
duplicate rows unless the <literal>ALL</> option is specified.
- With <literal>ALL</>, a row that has m duplicates in the left
- table and n duplicates in the right table will appear min(m,n)
- times in the result set.
+ With <literal>ALL</>, a row that has <replaceable>m</> duplicates in the
+ left table and <replaceable>n</> duplicates in the right table will appear
+ min(<replaceable>m</>,<replaceable>n</>) times in the result set.
</para>
<para>
C</literal> will be read as <literal>A UNION (B INTERSECT
C)</literal>.
</para>
+
+ <para>
+ Currently, <literal>FOR UPDATE</> may not be specified either for
+ an <literal>INTERSECT</> result or for any input of an <literal>INTERSECT</>.
+ </para>
</refsect2>
<refsect2 id="SQL-EXCEPT">
<para>
The result of <literal>EXCEPT</literal> does not contain any
duplicate rows unless the <literal>ALL</> option is specified.
- With <literal>ALL</>, a row that has m duplicates in the left
- table and n duplicates in the right table will appear max(m-n,0)
- times in the result set.
+ With <literal>ALL</>, a row that has <replaceable>m</> duplicates in the
+ left table and <replaceable>n</> duplicates in the right table will appear
+ max(<replaceable>m</>-<replaceable>n</>,0) times in the result set.
</para>
<para>
unless parentheses dictate otherwise. <literal>EXCEPT</> binds at
the same level as <literal>UNION</>.
</para>
- </refsect2>
-
- <refsect2 id="sql-select-list">
- <title id="sql-select-list-title"><command>SELECT</command> List</title>
-
- <para>
- The <command>SELECT</command> list (between the key words
- <literal>SELECT</> and <literal>FROM</>) specifies expressions
- that form the output rows of the <command>SELECT</command>
- statement. The expressions can (and usually do) refer to columns
- computed in the <literal>FROM</> clause. Using the clause
- <literal>AS <replaceable
- class="parameter">output_name</replaceable></literal>, another
- name can be specified for an output column. This name is
- primarily used to label the column for display. It can also be
- used to refer to the column's value in <literal>ORDER BY</> and
- <literal>GROUP BY</> clauses, but not in the <literal>WHERE</> or
- <literal>HAVING</> clauses; there you must write out the
- expression instead.
- </para>
-
+
<para>
- Instead of an expression, <literal>*</literal> can be written in
- the output list as a shorthand for all the columns of the selected
- rows. Also, one can write <literal><replaceable
- class="parameter">table_name</replaceable>.*</literal> as a
- shorthand for the columns coming from just that table.
+ Currently, <literal>FOR UPDATE</> may not be specified either for
+ an <literal>EXCEPT</> result or for any input of an <literal>EXCEPT</>.
</para>
</refsect2>
When using <literal>LIMIT</>, it is a good idea to use an
<literal>ORDER BY</> clause that constrains the result rows into a
unique order. Otherwise you will get an unpredictable subset of
- the query's rows---you may be asking for the tenth through
+ the query's rows — you may be asking for the tenth through
twentieth rows, but tenth through twentieth in what ordering? You
don't know what ordering unless you specify <literal>ORDER BY</>.
</para>
<!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/select_into.sgml,v 1.31 2004/09/26 23:48:07 neilc Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/select_into.sgml,v 1.32 2005/01/04 03:58:16 tgl Exp $
PostgreSQL documentation
-->
<para>
Prior to <productname>PostgreSQL</> 8.0, the table created by
- <command>SELECT INTO</command> always included OIDs. Furthermore,
- these OIDs were newly generated: they were distinct from the OIDs
- of any of the rows in the source tables of the <command>SELECT
- INTO</command> statement. Therefore, if <command>SELECT
- INTO</command> was frequently executed, the OID counter would be
- rapidly incremented. As of <productname>PostgreSQL</> 8.0, the
+ <command>SELECT INTO</command> always included OIDs.
+ As of <productname>PostgreSQL</> 8.0, the
inclusion of OIDs in the table created by <command>SELECT
INTO</command> is controlled by the
<xref linkend="guc-default-with-oids"> configuration variable. This
<!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/show.sgml,v 1.36 2004/08/03 20:32:32 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/show.sgml,v 1.37 2005/01/04 03:58:16 tgl Exp $
PostgreSQL documentation
-->
<listitem>
<para>
True if the current session authorization identifier has
- superuser privileges.
+ superuser privileges.
</para>
</listitem>
</varlistentry>
<term><literal>ALL</literal></term>
<listitem>
<para>
- Show the values of all configurations parameters.
+ Show the values of all configuration parameters.
</para>
</listitem>
</varlistentry>
Show all settings:
<programlisting>
SHOW ALL;
- name | setting
--------------------------------+---------------------------------------
- australian_timezones | off
- authentication_timeout | 60
- checkpoint_segments | 3
+ name | setting
+--------------------------------+----------------------------------------------
+ add_missing_from | on
+ archive_command | unset
+ australian_timezones | off
.
.
.
- wal_debug | off
- wal_sync_method | fdatasync
-(94 rows)
+ work_mem | 1024
+ zero_damaged_pages | off
+(140 rows)
</programlisting>
</para>
</refsect1>
<simplelist type="inline">
<member><xref linkend="SQL-SET" endterm="SQL-SET-title"></member>
+ <member><xref linkend="SQL-RESET" endterm="SQL-RESET-title"></member>
</simplelist>
</refsect1>
<!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/update.sgml,v 1.30 2004/08/08 01:48:31 momjian Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/update.sgml,v 1.31 2005/01/04 03:58:16 tgl Exp $
PostgreSQL documentation
-->
</para>
</refsect1>
+ <refsect1>
+ <title>Notes</title>
+
+ <para>
+ When joining the target table to other tables using a <replaceable
+ class="PARAMETER">fromlist</replaceable>, be careful that the join
+ produces at most one output row for each row to be modified. In
+ other words, a target row mustn't join to more than one row from
+ the other table(s). If it does, then only one of the join rows
+ will be used to update the target row, but which one will be used
+ is not readily predictable.
+ </para>
+
+ <para>
+ Because of this indeterminancy, referencing other tables only within
+ sub-selects is safer, though often harder to read and slower than
+ using a join.
+ </para>
+ </refsect1>
+
<refsect1>
<title>Examples</title>
projects / postgresql / commitdiff