From 039cb479884abc28ee494f6cf6c5e7ec26b88fc8 Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Sat, 10 Aug 2002 03:56:24 +0000 Subject: psql backslash commands are schema-aware. Pattern matching behavior follows recent pghackers discussion. This commit includes all the relevant fixes from Greg Mullane's patch of 24-June. --- doc/src/sgml/ref/grant.sgml | 17 ++-- doc/src/sgml/ref/psql-ref.sgml | 203 ++++++++++++++++++++++------------------- 2 files changed, 118 insertions(+), 102 deletions(-) (limited to 'doc/src') diff --git a/doc/src/sgml/ref/grant.sgml b/doc/src/sgml/ref/grant.sgml index a1384409cf3..5a66973e32d 100644 --- a/doc/src/sgml/ref/grant.sgml +++ b/doc/src/sgml/ref/grant.sgml @@ -1,5 +1,5 @@ @@ -249,16 +249,17 @@ GRANT { { CREATE | USAGE } [,...] | ALL [ PRIVILEGES ] } - Use 's \z command + Use 's \dp command to obtain information about existing privileges, for example: -lusitania=> \z mytable - Access privileges for database "lusitania" - Table | Access privileges ----------+--------------------------------------- - mytable | {=r,miriam=arwdRxt,"group todos=arw"} +lusitania=> \dp mytable + Access privileges for database "lusitania" + Schema | Table | Access privileges +--------+---------+--------------------------------------- + public | mytable | {=r,miriam=arwdRxt,"group todos=arw"} +(1 row) - The entries shown by \z are interpreted thus: + The entries shown by \dp are interpreted thus: =xxxx -- privileges granted to PUBLIC uname=xxxx -- privileges granted to a user diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml index b9f8554abfb..48370d1e214 100644 --- a/doc/src/sgml/ref/psql-ref.sgml +++ b/doc/src/sgml/ref/psql-ref.sgml @@ -1,5 +1,5 @@ @@ -538,7 +538,7 @@ testdb=> - To include whitespace into an argument you must quote it with a + To include whitespace into an argument you may quote it with a single quote. To include a single quote into such an argument, precede it by a backslash. Anything contained in single quotes is furthermore subject to C-like substitutions for @@ -551,25 +551,24 @@ testdb=> If an unquoted argument begins with a colon (:), - it is taken as a variable and the value of the variable is taken as - the argument instead. + it is taken as a psql variable and the value of the + variable is used as the argument instead. Arguments that are quoted in backticks (`) are taken as a command line that is passed to - the shell. The output of the command (with a trailing newline + the shell. The output of the command (with any trailing newline removed) is taken as the argument value. The above escape sequences also apply in backticks. - Some commands take the name of an SQL identifier + Some commands take an SQL identifier (such as a table name) as argument. These arguments follow the syntax rules of SQL regarding double quotes: an - identifier without double quotes is coerced to lower-case. For all - other commands double quotes are not special and will become part of - the argument. + identifier without double quotes is coerced to lower-case, while + whitespace within double quotes is included in the argument. @@ -732,18 +731,17 @@ testdb=> - \d relation + \d [ pattern ] - Shows all columns of relation (which could be a - table, view, index, or sequence), their types, and any special + For each relation (table, view, index, or sequence) matching the + pattern, show all + columns, their types, and any special attributes such as NOT NULL or defaults, if - any. If the relation is, in fact, a table, any defined indices, - primary keys, unique constraints and check constraints are also - listed. If the relation is a view, the view definition is also - shown. + 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.) @@ -753,7 +751,8 @@ testdb=> - If \d is called without any arguments, it is + 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 measure. @@ -776,34 +775,35 @@ testdb=> - \dd [ object ] + \dd [ pattern ] - Shows the descriptions of object (which can be a regular - expression), or of all objects if no argument is given. + Shows the descriptions of objects matching the pattern, or of all visible objects if + no argument is given. But in either case, only objects that have + a description are listed. (Object covers aggregates, functions, operators, types, relations (tables, views, indexes, sequences, large objects), rules, and triggers.) For example: => \dd version - Object descriptions - Name | What | Description ----------+----------+--------------------------- - version | function | PostgreSQL version string + Object descriptions + Schema | Name | Object | Description +------------+---------+----------+--------------------------- + pg_catalog | version | function | PostgreSQL version string (1 row) - Descriptions for objects can be generated with the + Descriptions for objects can be created with the COMMENT ON SQL command. PostgreSQL stores the object - descriptions in the pg_description system table. + descriptions in the pg_description system table. @@ -816,7 +816,7 @@ testdb=> Lists all available domains (derived types). If pattern (a regular expression) + class="parameter">pattern is specified, only matching domains are shown. @@ -830,7 +830,7 @@ testdb=> Lists available functions, together with their argument and return types. If pattern (a regular expression) + class="parameter">pattern is specified, only matching functions are shown. If the form \df+ is used, additional information about each function, including language and description, is shown. @@ -844,18 +844,17 @@ testdb=> - This is not the actual command name: The letters i, s, t, v, S + This is not the actual command name: the letters i, s, t, v, S stand for index, sequence, table, view, and system table, - respectively. You can specify any or all of them in any order to - obtain a listing of them, together with who the owner is. + respectively. You can specify any or all of these letters, in any + order, to obtain a listing of all the matching objects. + If + is appended to the command name, each object is + listed with its associated description, if any. - If pattern is - specified, it is a regular expression that restricts the listing - to those objects whose name matches. If one appends a - + to the command name, each object is listed with - its associated description, if any. + If a pattern is + specified, only objects whose name matches the pattern are listed. @@ -873,12 +872,12 @@ testdb=> - \do [ name ] + \do [ pattern ] Lists available operators with their operand and return types. - If name is - specified, only operators with that name will be shown. + If a pattern is + specified, only operators whose name matches the pattern are listed. @@ -888,9 +887,17 @@ testdb=> \dp [ pattern ] - This is an alias for \z which was included - for its greater mnemonic value (display - permissions). + Produces a list of all available tables with their + associated access permissions. + If a pattern is + specified, only tables whose name matches the pattern are listed. + + + + The commands and + + are used to set access permissions. See + for more information. @@ -912,7 +919,7 @@ testdb=> \du [ pattern ] - Lists all configured users or only those that match pattern. @@ -1608,57 +1615,23 @@ lo_import 152801 \z [ pattern ] - Produces a list of all tables in the database with their - appropriate access permissions listed. If an argument is given - it is taken as a regular expression which limits the listing to - those tables which match it. - - - - -test=> \z -Access permissions for database "test" - Relation | Access permissions -----------+------------------------------------- - my_table | {"=r","joe=arwR", "group staff=ar"} -(1 row ) - - Read this as follows: - - - - - "=r": PUBLIC has read - (SELECT) permission on the table. - - - - - - "joe=arwR": User joe has - read, write (UPDATE, - DELETE), append - (INSERT) permissions, and permission to - create rules on the table. - - - - - - "group staff=ar": Group - staff has SELECT and - INSERT permission. - - - + Produces a list of all available tables with their + associated access permissions. + If a pattern is + specified, only tables whose name matches the pattern are listed. The commands and - are used to set access permissions. + are used to set access permissions. See + for more information. + + This is an alias for \dp (display + permissions). + @@ -1688,6 +1661,46 @@ Access permissions for database "test" + + + The various \d commands accept a pattern parameter to specify the + object name(s) to be displayed. Patterns are interpreted similarly + to SQL identifiers, in that unquoted letters are forced to lowercase, + while double quotes (") protect letters from case conversion + and allow incorporation of whitespace into the identifier. Within + double quotes, paired double quotes reduce to a single double quote in + the resulting name. For example, FOO"BAR"BAZ is interpreted + as fooBARbaz, and "A weird"" name" becomes + A weird" name. + + + + More interestingly, \d patterns allow the use of + * to mean any sequence of characters, and + ? to mean any single character. (This notation + is comparable to Unix shell filename patterns.) Advanced users can + also use regular-expression notations such as character classes, for + example [0-9] to match any digit. To make any of + these pattern-matching characters be interpreted literally, surround it + with double quotes. + + + + A pattern that contains an (unquoted) dot is interpreted as a schema + name pattern followed by an object name pattern. For example, + \dt foo*.bar* displays all tables in schemas whose name + starts with foo and whose table name + starts with bar. If no dot appears, then the pattern + matches only objects that are visible in the current schema search path. + + + + Whenever the pattern parameter + is omitted completely, the \d commands display all objects + that are visible in the current schema search path. To see all objects + in the database, use the pattern *.*. + @@ -2402,11 +2415,12 @@ $ ./configure --with-includes=/opt/gnu/include --with-libs=/opt/gnu/lib ... - In some earlier life psql allowed the - first argument to start directly after the (single-letter) - command. For compatibility this is still supported to some extent + In an earlier life psql allowed the + first argument of a single-letter backslash command to start + directly after the command, without intervening whitespace. For + compatibility this is still supported to some extent, but I am not going to explain the details here as this use is - discouraged. But if you get strange messages, keep this in mind. + discouraged. If you get strange messages, keep this in mind. For example testdb=> \foo @@ -2421,7 +2435,8 @@ Field separator is "oo", psql only works smoothly with servers of the same version. That does not mean other combinations will fail outright, but subtle and not-so-subtle problems might come - up. + up. Backslash commands are particularly likely to fail if the + server is of a different version. -- cgit v1.2.3