From 5b7d2a9465bda7aef9a1f64427224ec76b2583b3 Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Thu, 24 Dec 2009 23:36:39 +0000 Subject: [PATCH] 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. --- doc/src/sgml/ref/psql-ref.sgml | 210 +++++++++++++++++---------------- 1 file changed, 111 insertions(+), 99 deletions(-) diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml index dc8a4819df..5b8bb836b1 100644 --- a/doc/src/sgml/ref/psql-ref.sgml +++ b/doc/src/sgml/ref/psql-ref.sgml @@ -1,5 +1,5 @@ @@ -635,8 +635,7 @@ testdb=> meta-command that is processed by psql itself. These commands help make psql 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. @@ -684,8 +683,9 @@ testdb=> - 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 \\ (two backslashes) marks the end of arguments and continues parsing SQL commands, if any. That way SQL and @@ -846,24 +846,26 @@ testdb=> - \d[S+] [ pattern ] + \d[S+] [ pattern ] For each relation (table, view, index, or sequence) matching the pattern, show all - columns, their types, the tablespace (if not the default) and any special - attributes such as NOT NULL or defaults, if - any. Associated indexes, constraints, rules, and triggers are - also shown, as is the view definition if the relation is a view. - (Matching the pattern is defined below.) + columns, their types, the tablespace (if not the default) and any + special attributes such as NOT NULL or defaults. + Associated indexes, constraints, rules, and triggers are + also shown. + (Matching the pattern is defined in + + below.) The command form \d+ 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. @@ -877,7 +879,7 @@ testdb=> If \d is used without a pattern argument, it is equivalent to \dtvs 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. @@ -885,11 +887,11 @@ testdb=> - \da[S] [ pattern ] + \da[S] [ pattern ] - Lists all available aggregate functions, together with their + Lists aggregate functions, together with their return type and the data types they operate on. If pattern is specified, only aggregates whose names match the pattern are shown. @@ -902,11 +904,11 @@ testdb=> - \db[+] [ pattern ] + \db[+] [ pattern ] - Lists all available tablespaces. If pattern is specified, only tablespaces whose names match the pattern are shown. If + is appended to the command name, each object @@ -917,10 +919,10 @@ testdb=> - \dc[S] [ pattern ] + \dc[S] [ pattern ] - Lists all available conversions between character-set encodings. + Lists conversions between character-set encodings. If pattern is specified, only conversions whose names match the pattern are listed. @@ -933,10 +935,10 @@ testdb=> - \dC [ pattern ] + \dC [ pattern ] - Lists all available type casts. + Lists type casts. If pattern is specified, only casts whose source or target types match the pattern are listed. @@ -946,7 +948,7 @@ testdb=> - \dd[S] [ pattern ] + \dd[S] [ pattern ] Shows the descriptions of objects matching the - \ddp [ pattern ] + \ddp [ pattern ] Lists default access privilege settings. An entry is shown for @@ -1002,12 +1004,12 @@ testdb=> - \dD[S] [ pattern ] + \dD[S] [ pattern ] - Lists all available domains. If pattern - 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 S modifier to include system objects. @@ -1017,10 +1019,10 @@ testdb=> - \des[+] [ pattern ] + \des[+] [ pattern ] - Lists all foreign servers (mnemonic: external + Lists foreign servers (mnemonic: external servers). If pattern is specified, only those servers whose name matches the pattern @@ -1033,10 +1035,10 @@ testdb=> - \deu[+] [ pattern ] + \deu[+] [ pattern ] - Lists all user mappings (mnemonic: external + Lists user mappings (mnemonic: external users). If pattern is specified, only those mappings whose user names match the @@ -1056,10 +1058,10 @@ testdb=> - \dew[+] [ pattern ] + \dew[+] [ pattern ] - Lists all foreign-data wrappers (mnemonic: external + Lists foreign-data wrappers (mnemonic: external wrappers). If pattern is specified, only those foreign-data wrappers whose name matches @@ -1072,40 +1074,42 @@ testdb=> - \df[antwS+] [ pattern ] + \df[antwS+] [ pattern ] - 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 a, - n, t, or w. If agg (aggregate), + normal, trigger, or window. + To display only functions + of specific type(s), add the corresponding letters a, + n, t, or w to the command. + If pattern is specified, only functions whose names match the pattern are shown. If the form \df+ 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 S + objects are shown; supply a pattern or the S modifier to include system objects. - + To look up functions taking arguments or returning values of a specific - type, use your pager's search capability to scroll through the \df - output. + type, use your pager's search capability to scroll through the + \df output. - + - \dF[+] [ pattern ] + \dF[+] [ pattern ] - Lists available text search configurations. + Lists text search configurations. If pattern is specified, only configurations whose names match the pattern are shown. If the form \dF+ is used, a full description of @@ -1116,10 +1120,10 @@ testdb=> - \dFd[+] [ pattern ] + \dFd[+] [ pattern ] - Lists available text search dictionaries. + Lists text search dictionaries. If pattern is specified, only dictionaries whose names match the pattern are shown. If the form \dFd+ is used, additional information @@ -1130,10 +1134,10 @@ testdb=> - \dFp[+] [ pattern ] + \dFp[+] [ pattern ] - Lists available text search parsers. + Lists text search parsers. If pattern is specified, only parsers whose names match the pattern are shown. If the form \dFp+ is used, a full description of @@ -1144,10 +1148,10 @@ testdb=> - \dFt[+] [ pattern ] + \dFt[+] [ pattern ] - Lists available text search templates. + Lists text search templates. If pattern is specified, only templates whose names match the pattern are shown. If the form \dFt+ is used, additional information @@ -1158,10 +1162,10 @@ testdb=> - \dg[+] [ pattern ] + \dg[+] [ pattern ] - Lists all database roles. If pattern is specified, only those roles whose names match the pattern are listed. (This command is now effectively the same as \du). @@ -1173,10 +1177,10 @@ testdb=> - \di[S+] [ pattern ] - \ds[S+] [ pattern ] - \dt[S+] [ pattern ] - \dv[S+] [ pattern ] + \di[S+] [ pattern ] + \ds[S+] [ pattern ] + \dt[S+] [ pattern ] + \dv[S+] [ pattern ] @@ -1185,19 +1189,16 @@ testdb=> t, and v 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, \dit lists indexes + these letters, in any order, to obtain a listing of objects + of these types. For example, \dit lists indexes and tables. If + 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 S modifier to include system - objects. - - - If pattern is specified, only objects whose names match the pattern are listed. + By default, only user-created objects are shown; supply a + pattern or the S modifier to include system + objects. @@ -1215,12 +1216,12 @@ testdb=> - \dn[+] [ pattern ] + \dn[+] [ pattern ] - Lists available schemas (namespaces). If pattern (a regular expression) + Lists schemas (namespaces). If pattern is specified, only schemas whose names match the pattern are listed. Non-local temporary schemas are suppressed. If + is appended to the command name, each object is listed with its associated @@ -1231,10 +1232,10 @@ testdb=> - \do[S] [ pattern ] + \do[S] [ pattern ] - Lists available operators with their operand and return types. + Lists operators with their operand and return types. If pattern 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=> - \dp [ pattern ] + \dp [ pattern ] - Lists available tables, views and sequences with their + Lists tables, views and sequences with their associated access privileges. If pattern 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. @@ -1266,30 +1268,32 @@ testdb=> - \drds [ role-pattern [ database-pattern ] ] + \drds [ role-pattern [ database-pattern ] ] - Lists defined configuration settings. These settings can be role-specific, - database-specific, or both. role-pattern and - database-pattern 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. + role-pattern and + database-pattern are used to select + specific roles and databases to list, respectively. If omitted, or if + * is specified, all settings are listed, including those + not role-specific or database-specific, respectively. The and - commands are used to define per-database role configuration settings. + commands are used to define per-role and per-database configuration + settings. - \dT[S+] [ pattern ] + \dT[S+] [ pattern ] - Lists available data types. + Lists data types. If pattern is specified, only types whose names match the pattern are listed. If + is appended to the command name, each type is @@ -1304,10 +1308,10 @@ testdb=> - \du[+] [ pattern ] + \du[+] [ pattern ] - Lists all database roles. If pattern is specified, only those roles whose names match the pattern are listed. If the form \du+ is used, additional information @@ -2132,7 +2136,8 @@ lo_import 152801 - \w {filename | |command} + \w filename + \w |command Outputs the current query buffer to the file - \z [ pattern ] + \z [ pattern ] - Produces a list of all available tables, views and sequences with their + Lists tables, views and sequences with their associated access privileges. If a pattern 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. @@ -2179,7 +2185,7 @@ lo_import 152801 Escapes to a separate Unix shell or executes the Unix command command. The arguments are not further interpreted, the shell will see them - as is. + as-is. @@ -2224,11 +2230,25 @@ lo_import 152801 the table named fooFOObar. + + Whenever the pattern parameter + is omitted completely, the \d commands display all objects + that are visible in the current schema search path — this is + equivalent to using * as the pattern. + (An object is said to be 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 *.* as the pattern. + + Within a pattern, * matches any sequence of characters (including no characters) and ? matches any single character. (This notation is comparable to Unix shell file name patterns.) - For example, \dt int* displays all tables whose names + For example, \dt int* displays tables whose names begin with int. But within double quotes, * and ? 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 \do). - - - Whenever the pattern parameter - is omitted completely, the \d commands display all objects - that are visible in the current schema search path — this is - equivalent to using the pattern *. - To see all objects in the database, use the pattern *.*. -