diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml
index dc8a4819dfe14e6f879e75bba9cab0f6c84b8845..5b8bb836b182de4c7c17b43698133d6994d5cbac 100644
--- a/doc/src/sgml/ref/psql-ref.sgml
+++ b/doc/src/sgml/ref/psql-ref.sgml
@@ -1,5 +1,5 @@
<!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.235 2009/11/25 20:26:30 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.236 2009/12/24 23:36:39 tgl Exp $
PostgreSQL documentation
-->
@@ -635,8 +635,7 @@ testdb=>
meta-command that is processed by <application>psql</application>
itself. These commands help make
<application>psql</application> more useful for administration or
- scripting. Meta-commands are more commonly called slash or backslash
- commands.
+ scripting. Meta-commands are often called slash or backslash commands.
</para>
<para>
@@ -684,8 +683,9 @@ testdb=>
</para>
<para>
- Parsing for arguments stops when another unquoted backslash occurs.
- This is taken as the beginning of a new meta-command. The special
+ Parsing for arguments stops at the end of the line, or when another
+ unquoted backslash is found. An unquoted backslash
+ is taken as the beginning of a new meta-command. The special
sequence <literal>\\</literal> (two backslashes) marks the end of
arguments and continues parsing <acronym>SQL</acronym> commands, if
any. That way <acronym>SQL</acronym> and
@@ -846,24 +846,26 @@ testdb=>
</varlistentry>
<varlistentry>
- <term><literal>\d[S+] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
+ <term><literal>\d[S+] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
<listitem>
<para>
For each relation (table, view, index, or sequence) matching the
<replaceable class="parameter">pattern</replaceable>, show all
- columns, their types, the tablespace (if not the default) and any special
- attributes such as <literal>NOT NULL</literal> or defaults, if
- any. Associated indexes, constraints, rules, and triggers are
- also shown, as is the view definition if the relation is a view.
- (<quote>Matching the pattern</> is defined below.)
+ columns, their types, the tablespace (if not the default) and any
+ special attributes such as <literal>NOT NULL</literal> or defaults.
+ Associated indexes, constraints, rules, and triggers are
+ also shown.
+ (<quote>Matching the pattern</> is defined in
+ <xref linkend="APP-PSQL-patterns" endterm="APP-PSQL-patterns-title">
+ below.)
</para>
<para>
The command form <literal>\d+</literal> is identical, except that
more information is displayed: any comments associated with the
columns of the table are shown, as is the presence of OIDs in the
- table.
+ table, and the view definition if the relation is a view.
</para>
<para>
@@ -877,7 +879,7 @@ testdb=>
If <command>\d</command> is used without a
<replaceable class="parameter">pattern</replaceable> argument, it is
equivalent to <command>\dtvs</command> which will show a list of
- all tables, views, and sequences. This is purely a convenience
+ all visible tables, views, and sequences. This is purely a convenience
measure.
</para>
</note>
@@ -885,11 +887,11 @@ testdb=>
</varlistentry>
<varlistentry>
- <term><literal>\da[S] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
+ <term><literal>\da[S] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
<listitem>
<para>
- Lists all available aggregate functions, together with their
+ Lists aggregate functions, together with their
return type and the data types they operate on. If <replaceable
class="parameter">pattern</replaceable>
is specified, only aggregates whose names match the pattern are shown.
@@ -902,11 +904,11 @@ testdb=>
<varlistentry>
- <term><literal>\db[+] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
+ <term><literal>\db[+] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
<listitem>
<para>
- Lists all available tablespaces. If <replaceable
+ Lists tablespaces. If <replaceable
class="parameter">pattern</replaceable>
is specified, only tablespaces whose names match the pattern are shown.
If <literal>+</literal> is appended to the command name, each object
@@ -917,10 +919,10 @@ testdb=>
<varlistentry>
- <term><literal>\dc[S] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
+ <term><literal>\dc[S] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
<listitem>
<para>
- Lists all available conversions between character-set encodings.
+ Lists conversions between character-set encodings.
If <replaceable class="parameter">pattern</replaceable>
is specified, only conversions whose names match the pattern are
listed.
@@ -933,10 +935,10 @@ testdb=>
<varlistentry>
- <term><literal>\dC [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
+ <term><literal>\dC [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
<listitem>
<para>
- Lists all available type casts.
+ Lists type casts.
If <replaceable class="parameter">pattern</replaceable>
is specified, only casts whose source or target types match the
pattern are listed.
@@ -946,7 +948,7 @@ testdb=>
<varlistentry>
- <term><literal>\dd[S] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
+ <term><literal>\dd[S] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
<listitem>
<para>
Shows the descriptions of objects matching the <replaceable
@@ -979,7 +981,7 @@ testdb=>
<varlistentry>
- <term><literal>\ddp [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
+ <term><literal>\ddp [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
<listitem>
<para>
Lists default access privilege settings. An entry is shown for
@@ -1002,12 +1004,12 @@ testdb=>
<varlistentry>
- <term><literal>\dD[S] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
+ <term><literal>\dD[S] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
<listitem>
<para>
- Lists all available domains. If <replaceable
+ Lists domains. If <replaceable
class="parameter">pattern</replaceable>
- is specified, only matching domains are shown.
+ is specified, only domains whose names match the pattern are shown.
By default, only user-created objects are shown; supply a
pattern or the <literal>S</literal> modifier to include system
objects.
@@ -1017,10 +1019,10 @@ testdb=>
<varlistentry>
- <term><literal>\des[+] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
+ <term><literal>\des[+] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
<listitem>
<para>
- Lists all foreign servers (mnemonic: <quote>external
+ Lists foreign servers (mnemonic: <quote>external
servers</quote>).
If <replaceable class="parameter">pattern</replaceable> is
specified, only those servers whose name matches the pattern
@@ -1033,10 +1035,10 @@ testdb=>
<varlistentry>
- <term><literal>\deu[+] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
+ <term><literal>\deu[+] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
<listitem>
<para>
- Lists all user mappings (mnemonic: <quote>external
+ Lists user mappings (mnemonic: <quote>external
users</quote>).
If <replaceable class="parameter">pattern</replaceable> is
specified, only those mappings whose user names match the
@@ -1056,10 +1058,10 @@ testdb=>
<varlistentry>
- <term><literal>\dew[+] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
+ <term><literal>\dew[+] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
<listitem>
<para>
- Lists all foreign-data wrappers (mnemonic: <quote>external
+ Lists foreign-data wrappers (mnemonic: <quote>external
wrappers</quote>).
If <replaceable class="parameter">pattern</replaceable> is
specified, only those foreign-data wrappers whose name matches
@@ -1072,40 +1074,42 @@ testdb=>
<varlistentry>
- <term><literal>\df[antwS+] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
+ <term><literal>\df[antwS+] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
<listitem>
<para>
- Lists available functions, together with their arguments,
- return types, and their function types: 'agg' (aggregate),
- 'normal', 'trigger', and 'window'. To display only functions
- of a specific type, use the corresponding letters <literal>a</>,
- <literal>n</>, <literal>t</>, or <literal>w</>. If <replaceable
+ Lists functions, together with their arguments, return types, and
+ function types, which are classified as <quote>agg</> (aggregate),
+ <quote>normal</>, <quote>trigger</>, or <quote>window</>.
+ To display only functions
+ of specific type(s), add the corresponding letters <literal>a</>,
+ <literal>n</>, <literal>t</>, or <literal>w</> to the command.
+ If <replaceable
class="parameter">pattern</replaceable> is specified, only
functions whose names match the pattern are shown. If the
form <literal>\df+</literal> is used, additional information
about each function, including volatility, language, source
code and description, is shown. By default, only user-created
- objects are shown; supply a pattern or the <literal>S</literal>
+ objects are shown; supply a pattern or the <literal>S</literal>
modifier to include system objects.
</para>
- <note>
+ <tip>
<para>
To look up functions taking arguments or returning values of a specific
- type, use your pager's search capability to scroll through the <literal>\df</>
- output.
+ type, use your pager's search capability to scroll through the
+ <literal>\df</> output.
</para>
- </note>
+ </tip>
</listitem>
</varlistentry>
<varlistentry>
- <term><literal>\dF[+] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
+ <term><literal>\dF[+] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
<listitem>
<para>
- Lists available text search configurations.
+ Lists text search configurations.
If <replaceable class="parameter">pattern</replaceable> is specified,
only configurations whose names match the pattern are shown.
If the form <literal>\dF+</literal> is used, a full description of
@@ -1116,10 +1120,10 @@ testdb=>
</varlistentry>
<varlistentry>
- <term><literal>\dFd[+] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
+ <term><literal>\dFd[+] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
<listitem>
<para>
- Lists available text search dictionaries.
+ Lists text search dictionaries.
If <replaceable class="parameter">pattern</replaceable> is specified,
only dictionaries whose names match the pattern are shown.
If the form <literal>\dFd+</literal> is used, additional information
@@ -1130,10 +1134,10 @@ testdb=>
</varlistentry>
<varlistentry>
- <term><literal>\dFp[+] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
+ <term><literal>\dFp[+] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
<listitem>
<para>
- Lists available text search parsers.
+ Lists text search parsers.
If <replaceable class="parameter">pattern</replaceable> is specified,
only parsers whose names match the pattern are shown.
If the form <literal>\dFp+</literal> is used, a full description of
@@ -1144,10 +1148,10 @@ testdb=>
</varlistentry>
<varlistentry>
- <term><literal>\dFt[+] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
+ <term><literal>\dFt[+] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
<listitem>
<para>
- Lists available text search templates.
+ Lists text search templates.
If <replaceable class="parameter">pattern</replaceable> is specified,
only templates whose names match the pattern are shown.
If the form <literal>\dFt+</literal> is used, additional information
@@ -1158,10 +1162,10 @@ testdb=>
<varlistentry>
- <term><literal>\dg[+] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
+ <term><literal>\dg[+] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
<listitem>
<para>
- Lists all database roles. If <replaceable
+ Lists database roles. If <replaceable
class="parameter">pattern</replaceable> is specified, only
those roles whose names match the pattern are listed.
(This command is now effectively the same as <literal>\du</literal>).
@@ -1173,10 +1177,10 @@ testdb=>
<varlistentry>
- <term><literal>\di[S+] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
- <term><literal>\ds[S+] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
- <term><literal>\dt[S+] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
- <term><literal>\dv[S+] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
+ <term><literal>\di[S+] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
+ <term><literal>\ds[S+] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
+ <term><literal>\dt[S+] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
+ <term><literal>\dv[S+] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
<listitem>
<para>
@@ -1185,19 +1189,16 @@ testdb=>
<literal>t</literal>, and <literal>v</literal>
stand for index, sequence, table, and view, respectively.
You can specify any or all of
- these letters, in any order, to obtain a listing of all the
- matching objects. For example, <literal>\dit</> lists indexes
+ these letters, in any order, to obtain a listing of objects
+ of these types. For example, <literal>\dit</> lists indexes
and tables. If <literal>+</literal> is
appended to the command name, each object is listed with its
physical size on disk and its associated description, if any.
- By default, only user-created objects are shown; supply a
- pattern or the <literal>S</literal> modifier to include system
- objects.
- </para>
-
- <para>
If <replaceable class="parameter">pattern</replaceable> is
specified, only objects whose names match the pattern are listed.
+ By default, only user-created objects are shown; supply a
+ pattern or the <literal>S</literal> modifier to include system
+ objects.
</para>
</listitem>
</varlistentry>
@@ -1215,12 +1216,12 @@ testdb=>
<varlistentry>
- <term><literal>\dn[+] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
+ <term><literal>\dn[+] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
<listitem>
<para>
- Lists available schemas (namespaces). If <replaceable
- class="parameter">pattern</replaceable> (a regular expression)
+ Lists schemas (namespaces). If <replaceable
+ class="parameter">pattern</replaceable>
is specified, only schemas whose names match the pattern are listed.
Non-local temporary schemas are suppressed. If <literal>+</literal>
is appended to the command name, each object is listed with its associated
@@ -1231,10 +1232,10 @@ testdb=>
<varlistentry>
- <term><literal>\do[S] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
+ <term><literal>\do[S] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
<listitem>
<para>
- Lists available operators with their operand and return types.
+ Lists operators with their operand and return types.
If <replaceable class="parameter">pattern</replaceable> is
specified, only operators whose names match the pattern are listed.
By default, only user-created objects are shown; supply a
@@ -1246,13 +1247,14 @@ testdb=>
<varlistentry>
- <term><literal>\dp [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
+ <term><literal>\dp [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
<listitem>
<para>
- Lists available tables, views and sequences with their
+ Lists tables, views and sequences with their
associated access privileges.
If <replaceable class="parameter">pattern</replaceable> is
- specified, only tables, views and sequences whose names match the pattern are listed.
+ specified, only tables, views and sequences whose names match the
+ pattern are listed.
</para>
<para>
@@ -1266,30 +1268,32 @@ testdb=>
</varlistentry>
<varlistentry>
- <term><literal>\drds [ <replaceable class="parameter">role-pattern</replaceable> [ <replaceable class="parameter">database-pattern </replaceable> ] ]</literal></term>
+ <term><literal>\drds [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">role-pattern</replaceable></link> [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">database-pattern</replaceable></link> ] ]</literal></term>
<listitem>
<para>
- Lists defined configuration settings. These settings can be role-specific,
- database-specific, or both. <literal>role-pattern</literal> and
- <literal>database-pattern</literal> are used to select
- specific roles and database to list, respectively; if omitted, or * is specified,
- all settings are listed, including those not role-specific or database-specific,
- respectively.
+ Lists defined configuration settings. These settings can be
+ role-specific, database-specific, or both.
+ <replaceable>role-pattern</replaceable> and
+ <replaceable>database-pattern</replaceable> are used to select
+ specific roles and databases to list, respectively. If omitted, or if
+ <literal>*</> is specified, all settings are listed, including those
+ not role-specific or database-specific, respectively.
</para>
<para>
The <xref linkend="sql-alterrole" endterm="sql-alterrole-title"> and
<xref linkend="sql-alterdatabase" endterm="sql-alterdatabase-title">
- commands are used to define per-database role configuration settings.
+ commands are used to define per-role and per-database configuration
+ settings.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><literal>\dT[S+] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
+ <term><literal>\dT[S+] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
<listitem>
<para>
- Lists available data types.
+ Lists data types.
If <replaceable class="parameter">pattern</replaceable> is
specified, only types whose names match the pattern are listed.
If <literal>+</literal> is appended to the command name, each type is
@@ -1304,10 +1308,10 @@ testdb=>
<varlistentry>
- <term><literal>\du[+] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
+ <term><literal>\du[+] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
<listitem>
<para>
- Lists all database roles. If <replaceable
+ Lists database roles. If <replaceable
class="parameter">pattern</replaceable> is specified, only
those roles whose names match the pattern are listed.
If the form <literal>\du+</literal> is used, additional information
@@ -2132,7 +2136,8 @@ lo_import 152801
<varlistentry>
- <term><literal>\w</literal> {<replaceable class="parameter">filename</replaceable> | <replaceable class="parameter">|command</replaceable>}</term>
+ <term><literal>\w</literal> <replaceable class="parameter">filename</replaceable></term>
+ <term><literal>\w</literal> <literal>|</><replaceable class="parameter">command</replaceable></term>
<listitem>
<para>
Outputs the current query buffer to the file <replaceable
@@ -2155,13 +2160,14 @@ lo_import 152801
<varlistentry>
- <term><literal>\z [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
+ <term><literal>\z [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
<listitem>
<para>
- Produces a list of all available tables, views and sequences with their
+ Lists tables, views and sequences with their
associated access privileges.
If a <replaceable class="parameter">pattern</replaceable> is
- specified, only tables,views and sequences whose names match the pattern are listed.
+ specified, only tables, views and sequences whose names match the
+ pattern are listed.
</para>
<para>
@@ -2179,7 +2185,7 @@ lo_import 152801
Escapes to a separate Unix shell or executes the Unix command
<replaceable class="parameter">command</replaceable>. The
arguments are not further interpreted, the shell will see them
- as is.
+ as-is.
</para>
</listitem>
</varlistentry>
@@ -2224,11 +2230,25 @@ lo_import 152801
the table named <literal>fooFOObar</>.
</para>
+ <para>
+ Whenever the <replaceable class="parameter">pattern</replaceable> parameter
+ is omitted completely, the <literal>\d</> commands display all objects
+ that are visible in the current schema search path — this is
+ equivalent to using <literal>*</> as the pattern.
+ (An object is said to be <firstterm>visible</> if its
+ containing schema is in the search path and no object of the same
+ kind and name appears earlier in the search path. This is equivalent to the
+ statement that the object can be referenced by name without explicit
+ schema qualification.)
+ To see all objects in the database regardless of visibility,
+ use <literal>*.*</> as the pattern.
+ </para>
+
<para>
Within a pattern, <literal>*</> matches any sequence of characters
(including no characters) and <literal>?</> matches any single character.
(This notation is comparable to Unix shell file name patterns.)
- For example, <literal>\dt int*</> displays all tables whose names
+ For example, <literal>\dt int*</> displays tables whose names
begin with <literal>int</>. But within double quotes, <literal>*</>
and <literal>?</> lose these special meanings and are just matched
literally.
@@ -2270,14 +2290,6 @@ lo_import 152801
expression special characters are matched literally in operator name
patterns (i.e., the argument of <literal>\do</>).
</para>
-
- <para>
- Whenever the <replaceable class="parameter">pattern</replaceable> parameter
- is omitted completely, the <literal>\d</> commands display all objects
- that are visible in the current schema search path — this is
- equivalent to using the pattern <literal>*</>.
- To see all objects in the database, use the pattern <literal>*.*</>.
- </para>
</refsect3>
</refsect2>