rdelaage
/
postgresql
mirror of https://git.postgresql.org/git/postgresql.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Try to improve the clarity of the psql documentation for the \d family of 

commands, as per recent discussion.  Includes suggestions from Adrian Klaver
and Filip Rembialkowski.
This commit is contained in:
Tom Lane 2009-12-24 23:36:39 +00:00
parent 0ef5910d6d
commit 5b7d2a9465
1 changed files with 111 additions and 99 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

210
doc/src/sgml/ref/psql-ref.sgml
View File

@ -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=&gt;
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=&gt;
</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=&gt;
</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=&gt;
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=&gt;
</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=&gt;
<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=&gt;
<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=&gt;
<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=&gt;
<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=&gt;
<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=&gt;
<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=&gt;
<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=&gt;
<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=&gt;
<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=&gt;
<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=&gt;
</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=&gt;
</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=&gt;
</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=&gt;
<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=&gt;
<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=&gt;
<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=&gt;
<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=&gt;
<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=&gt;
<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=&gt;
</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=&gt;
<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 &mdash; 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 &mdash; this is
equivalent to using the pattern <literal>*</>.
To see all objects in the database, use the pattern <literal>*.*</>.
</para>
</refsect3>
</refsect2>