-
-
-
- Application
-
-
-
-
-
-
Postgres interactive client
-
-
-
-
- 1999-07-20
-
-
-psql [ dbname ]
-psql -A [ -c query ] [ -d dbname ]
- -e -E [ -f filename ] [ -F separator ]
- [ -h hostname ] -Hln [ -o filename ]
- [ -p port ] -qsSt [ -T table_o ] -ux
- [ dbname ]
-
+
+
+
+ Application
+
+
+
+
+
+
+
PostgreSQL interactive terminal
+
+
+
+
+
+ 1999-10-26
+
+
+ psql [ options ] [ dbname [ user ] ]
-
- 1998-09-26
-
-
</div>
<div class="diff rem">- Inputs</div>
<div class="diff rem">-
+
+ 1998-09-26
+
+
+
Input
psql accepts many command-line arguments,
a rich set of meta-commands, and the full
SQL language
- supported by
Postgres. The most common
- command-line arguments are:
-
-
-
- dbname
-
- The name of an existing database to access.
- dbname
- defaults to the value of the
- USER
- environment variable or, if that's not set, to the Unix account name of the
- current user.
-
-
-
-
-
- -c query
-
- A single query to run.
psql will exit on completion.
-
-
-
-
-
-
- The full set of command-line arguments and meta-commands are described in a subsequent
- section.
-
-
- There are some environment variables which can be used in liu of
- command line arguments.
- Additionally, the
Postgres frontend library used by
- looks for other optional environment variables to configure, for example,
- the style of date/time representation and the local time zone. Refer
- to the chapter on libpq in the
- Programmer's Guide for more details.
-
- You may set any of the following environment variables to avoid
- specifying command-line options:
-
-
-
- PGHOST
-
- The
DNS host name of the database server.
- Setting PGHOST to a non-zero-length string causes
- to be used, rather than the default local Unix domain sockets.
-
-
-
-
-
- PGPORT
-
- The port number on which a
Postgres server is listening.
- Defaults to 5432.
-
-
-
-
-
- PGTTY
-
- The target for display of messages from the client support library.
- Not required.
-
-
-
-
-
- PGOPTION
-
- If PGOPTION
- is specified, then the options it contains are parsed
- before
- any command-line options.
-
-
-
-
-
- PGREALM
-
- PGREALM
- only applies if
- authentication is in use.
- If this environment variable is set,
Postgres- will attempt authentication with servers for this realm and will use
- separate ticket files to avoid conflicts with local ticket files.
- See the PostgreSQL Administrator's Guide
- for additional information on
-
-
-
-
-
+ supported by
PostgreSQL.
+
-
- 1998-09-26
-
-
</div>
<div class="diff rem">- Outputs</div>
<div class="diff rem">-
- returns 0 to the shell on successful completion of all queries,
- 1 for errors, 2 for abrupt disconnection from the backend.
- will also return 1 if the connection to a database could not be made for
- any reason.
-
- The default TAB delimiter is used.
-
+
+ 1998-10-26
+
+
+
Output
+
psql returns 0 to the shell on successful
+ completion of all queries, 1 for fatal errors, 2 for abrupt disconnection
+ from the backend, and 3 if a non-interactive script stopped because an
SQL+ command or psql meta-command resulted in an error.
+
-
+
-
+
- 1998-09-26
+ 1998-10-26
-
</div>
<div class="diff rem">- Description</div>
<div class="diff rem">-
+
+
Description
+
-
psql is a character-based front-end to
- It enables you to
- type in queries interactively, issue them to
Postgres,
- and see the query
- results.
+
psql is a character-based front-end to
+
PostgreSQL. It enables you to type in queries
+ interactively, issue them to
PostgreSQL, and see
+ the query results. In addition, it provides a number of meta-commands and
+ various shell-like features to facilitate writing scripts and automating a wide
+ variety of tasks.
+
- is a
Postgres client application. Hence, a
- must be running on the database server host before
- is executed. In addition, the correct parameters to identify
- the database server, such as the
- may need to be specified
- as described below.
+
PostgreSQL client application. Hence, a
+
postmaster process must be running on the database
+ server host before
psql is executed. In addition,
+ the correct parameters to identify the database server, such as the
+
postmaster host name, may need to be specified as
+ described below.
+
- When
- starts, it reads SQL commands from
- /etc/psqlrc
- and then from
- $(HOME)/.psqlrc
- This allows SQL commands like
- SET
- which can be used to set the date style to be run at the start of
- every session.
+ When
psql starts, it reads
SQL and psql commands
+ from /etc/psqlrc and then from
+ $HOME/.psqlrc
+ This allows commands like
\set or the
SQL command
+ , which can be used to set a variety of options,
+ to be run at the start of every session.
-
- 1998-09-26
-
-
</div>
<div class="diff rem">- Connecting To A Database</div>
<div class="diff rem">-
- attempts to make a connection to the database at the hostname and
- port number specified on the command line. If the connection could not
- be made for any reason (e.g. insufficient privileges, postmaster is not
- running on the server, etc)
- will return an error that says
- Connection to database failed.
-
- The reason for the connection failure is not provided.
-
+
+ 1998-09-26
+
+
+
Connecting To A Database
+
+
psql attempts to make a connection to the
+ database name at the hostname and port number, and with the user name
+ specified on the command line. If any of these are omitted, the
+
libpq client library, upon which
+
psql is built, will choose defaults.
+ (This will usually mean the environment variables PGDATABASE,
+ PGHOST, PGPORT, PQUSER,
+ respectively, if they are set. Otherwise the default host is the local host
+ via Unix domain sockets, the default port is decided at compile time,
+ the default user is the system user name, and the default database is
+ the one with the same name as the user.)
+
+
+ If the connection could not be made for any reason (e.g., insufficient
+ privileges, postmaster is not running on the server, etc.),
+
psql will return an error and terminate.
+
-
- 1998-09-26
-
-
</div>
<div class="diff rem">- Entering Queries</div>
<div class="diff rem">-
- In normal operation,
-
psql provides a prompt with the name of the
- database that
psql is current connected to
- followed by the string "=>".
- For example,
+
+ 1998-09-26
+
+
+
Entering Queries
+
+ In normal operation,
psql provides a prompt with
+ the name of the database that
psql is currently
+ connected to followed by the string "=>". For example,
$ psql testdb
-Welcome to the POSTGRESQL interactive sql monitor:
- Please read the file COPYRIGHT for copyright terms of POSTGRESQL
-[PostgreSQL 6.5.0 on i686-pc-linux-gnu, compiled by gcc 2.7.2.3]
-
- type \? for help on slash commands
- type \q to quit
- type \g or terminate with semicolon to execute query
- You are currently connected to the database: testdb
-
+Welcome to psql, the PostgreSQL interactive terminal.
+(Please type \copyright to see the distribution terms of PostgreSQL.)
+
+Type \h for help with SQL commands,
+ \? for help on internal slash commands,
+ \q to quit,
+ \g or terminate with semicolon to execute query.
testdb=>
-
+
+
At the prompt, the user may type in
SQL queries.
- Unless the -S option
- is set, input lines are sent to the backend when a query-terminating
- semicolon is reached.
-
- Whenever a query is executed,
-
psql also polls for asynchronous notification
- events generated by LISTEN and NOTIFY.
-
- can be used in a pipe sequence, and automatically detects when it
- is not listening or talking to a real tty.
-
+ Ordinarily, input lines are sent to the backend when a query-terminating
+ semicolon is reached. If the database server reports success, the query
+ results are displayed on the screen.
+
+
+ Whenever a query is executed,
psql also polls
+ for asynchronous notification events generated by
+ and
+ .
+
+
+
psql can be used in a pipe sequence, and
+ automatically detects when it is not used interactively.
+
+
+
+
+
+ 1998-09-26
+
-
-
Paging To Screen
+
<application>psql</application> Meta-Commands
-
-
Author
- From Brett McCormick on the mailing list 1998-04-04.
+ Anything you enter in
psql that begins with an
+ unquoted backslash is a
psql meta-command.
+ Anything else is
SQL and simply goes into the current
+ query buffer (and once you have at least one complete query, it gets
+ automatically submitted to the backend). For this reason,
+
psql meta-commands are more commonly called
+ slash or backslash commands.
-
- To affect the paging behavior of your psql output,
- set or unset your PAGER environment variable. I always have to set mine
- before it will pause. And of course you have to do this before
- starting the program.
-
+ T
he format of a psql command is the backslash, + followed immediately by a command verb, then any arguments. The arguments
+ are separated from the command verb and each other by any number of white
+ space characters.
+
- In csh/tcsh or other C shells:
+ To include whitespace into an argument you must quote it with either single
+ or double quotes. Anything contained in single quotes (except for a
+ backslash-escaped single quote itself) is taken literally as the argument.
+ Anything contained in double quotes is furthermore subject to C-like
+ substitutions for \n (new line), \t (tab),
+ \digits,
+ \0digits, and
+ \0xdigits
+ (the character with the given decimal, octal, or hexadecimal code).
+
-% unsetenv PAGER
-
+ If an unquoted argument begins with a dollar sign ($),
+ it is taken as a variable and the value of the variable is taken as the
+ argument instead. Inside double quotes, variable values can be substituted
+ by enclosing the name in a ${...} sequence. See also under
+
.
+
- while in sh/bash or other Bourne shells:
+ Arguments that are quoted in back-ticks
(`)
+ are taken as a command line
+ that is passed to the shell. The output of the command (with a trailing
+ newline removed) is taken as the argument value. Back-ticks are subject to
+ the same substitution rules as double-quotes.
+
-% unset PAGER
-
-
-
-
+ Parsing for arguments stops when another unquoted backslash occurs. This
+ is taken as the beginning of a new meta-command. The special sequence
+ \\
+ (two backslashes) marks the end of arguments and continues parsing
+
SQL queries, if any. That way
SQL and
+
psql commands can be freely mixed on a line.
+ In any case, the arguments of a meta-command cannot continue beyond the end
+ of the line.
+
+
+ The following meta-commands are defined:
+
+
+
+ \a
+
+ If the current table output format is unaligned, switch to aligned.
+ If it is not unaligned, set it to unaligned. This command is
+ kept for backwards compatibility. See \pset for a
+ general solution.
+
+
+
+
+
+ \C [ title ]
+
+ Set the title of any tables being printed as the result of a query or
+ unset any such title. This command is equivalent to
+ \pset title title.
+ (The name of this
+ command derives from caption
, as it was previously only
+ used to set the caption in an
HTML table.)
+
+
+
+
+
+ \connect (or \c) [ dbname [ username ] ]
+
+ Establishes a connection to a new database and/or under a user name. The
+ previous connection is closed.
+ If dbname is -
+ the current database name is assumed.
+
+
+ If username is omitted or
+ - the current user name is assumed. If
+ username is ?
+
psql will prompt for the new user name
+ interactively.
+
+
+ As a special rule, \connect without any arguments will connect
+ to the default database as the default user (as you would have gotten
+ by starting
psql without any arguments).
+
+
+ If the connection attempt failed (wrong username, access denied, etc.) the
+ previous connection will be kept, if and only if
psql is
+ in interactive mode. When executing a non-interactive script, processing
+ will immediately stop with an error. This distinction was chosen as a user
+ convenience against typos on the one hand, and a safety mechanism that
+ scripts are not accidentally acting on the wrong database on the other hand.
+
+
+
+
+
+ \copy [ binary ] table
+ [ with oids ] { from | to }
+ filename [ with delimiters
+ 'character' ]
+
+
+
+ Performs a frontend (client) copy. This is an operation that runs an
+ but instead of the backend reading or writing the specified file, and
+ consequently requiring backend access and special user privilege,
+ as well as being bound to the file system accessible by the backend,
+
psql reads or writes the
+ file and routes the data to or from the backend onto the local file system.
+
+
+ The syntax of the command is in analogy to the
SQL+ COPY command, see its description for the details.
+ Note that because of this, special parsing rules apply to the
+ \copy command. In particular, the variable
+ substitution rules and backslash escapes do not apply.
+
+
+
+ This operation is not as efficient as the
SQL + COPY command because all data must pass through the
+ client/server IP or socket connection. For large amounts of data this other
+ technique may be preferable.
+
+
+
+
+
+
+ \copyright
+
+ Shows the copyright and distribution terms of
PostgreSQL.
+
+
+
+
+
+ \d relation
+
+
+ Shows all column of relation
+ (which could be a table, view, index, or sequence),
+ 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 are also listed.
+ If the relation is a view, the view definition is also shown.
+ If the variable description is set, any comments associated
+ with a table columns are shown as well.
+
+
+
+ If \d is called without any arguments, it is
+ equivalent to \dtvs which will show a list
+ of all tables, views, and sequences. This is purely a convenience
+ measure.
+
+
+
+
+
+
+ \da [ pattern ]
+
+
+ Lists all available aggregate functions, together with the data type they operate on.
+ If pattern
+ (a regular expression) is specified, only matching aggregates are shown.
+ If the variable description is set, comments are listed for
+ each function as well.
+
+
+
+
+
+ \dd [ object ]
+
+ Shows the descriptions of object
+ (which can be a regular expression), or of all objects if no argument is given.
+ (Object
covers aggregates, functions, operators, types, relations
+ (tables, views, indices, sequences, large objects), rules, and triggers.) For example:
+=> \dd version
+ Object descriptions
+ Name | What | Description
+---------+----------+---------------------------
+ version | function | PostgreSQL version string
+(1 row)
+
+
+
+ Descriptions for objects can be generated with the COMMENT ON
+
+
+
+
PostgreSQL stores the object descriptions in the
+ pg_description system table.
+
+
+
+
+
+
+
+
+ \df [ pattern ]
+
+
+ Lists available functions, together with their argument and return types.
+ If pattern
+ (a regular expression) is specified, only matching functions are shown.
+ If the variable description is set, comments are listed for
+ each function as well.
+
+
+
+
+
+
+ \distvS [ pattern ]
+
+
+ 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.
+
+
+ If pattern is specified,
+ it is a regular expression restricts the listing to those objects
+ whose name matches. If the variable description is set,
+ each object is listed with its associated description, if any.
+
+
+
+
+
+
+ \dl
+
+ This is an alias for \lo_list, which shows a list of large objects.
+
+
+
+
+
+
+ \do [ name ]
+
+ Lists available operators with their operand and return types.
+ If name
+ is specified, only operators with that name will be shown.
+ (Note that, unlike with similar commands, this is not a regular expression
+ because operator names were likely to interfere with regular expression
+ meta-characters.)
+
+ If the variable description is set, comments are listed for
+ each operator.
+
+
+
+
+
+
+ \dp [ pattern ]
+
+ This is an alias for \z which was included for its
+ greater mnemonic value (display permissions
).
+
+
+
+
+
+
+ \dT [ pattern ]
+
+ List all data types or only those that match pattern.
+ If the variable description is set, each type is listed with
+ its associated description.
+
+
+
+
+
+
+ \edit (or \e) [ filename ]
+
+
+ If filename is specified,
+ the file is edited and after the editor exit its content is copied
+ back to the query buffer. If no argument is given, the current query
+ buffer is copied to a temporary file which is then edited in the same
+ fashion.
+
+
+ The new query buffer is then re-parsed according to the normal rules of
+
psql, where the whole buffer is treated as
+ a single line. (Thus you cannot make scripts
this way,
+ use \i for that.) In particular, this means that
+ if the query ends (or rather contains) a semicolon, it is immediately
+ executed. In other cases it will merely wait in the query buffer.
+
+
+
+
psql searches the environment variables
+ PSQL_EDITOR, EDITOR, and VISUAL
+ (in that order) for an editor to use. If all of them are unset,
+ /bin/vi is run.
+
+
+
+
+
+
+
+ \echo text [ ... ]
+
+ Prints the arguments to the standard output. This can be useful to
+ intersperse information in the output of scripts. For example:
+=> \echo `date`
+Tue Oct 26 21:40:57 CEST 1999
+
+
+
+
+ If you use the \o command to redirect your query output
+ you may wish to use \qecho instead of this command.
+
+
+
+
+
+
+
+ \f [ string ]
+
+
+ Sets the field separator for unaligned query output. The default is |
+ (a pipe
symbol). See also \pset for a generic way
+ of setting output options.
+
+
+
+
+
+
+ \g [ { filename | |command } ]
+
+
+ Sends the current query input buffer to the backend and optionally
+ saves the output in filename
+ or pipes the output into a separate Unix shell to execute
+ command. A blank \g
+ is virtually equivalent to a semicolon. A \g with argument
+ is a one-shot
alternative to the \o command.
+
+
+
+
+
+ \help (or \h) [ command ]
+
+ Give syntax help on the specified
SQL command.
+ If
command is not a defined SQL command+ or if command is not specified,
+ list all the commands for which syntax help is
+ available. If command
+ is an asterisk (*
), then
+ syntax help on all
SQL commands is shown.
+
+
+
+ To simplify typing, commands that consists of several words do not have to be quoted.
+ Thus it is fine to type \help alter table.
+
+
+
+
+
+
+
+ \H
+
+ Turns on
HTML query output format. If the
HTML+ format is already on, it is switched back to the default aligned text format. This
+ command is for compatibility and convenience, but see \pset about
+ setting other output options.
+
+
+
+
+
+
+ \i filename
+
+ Reads input from the file filename
+ and executes it as though it has been typed on the keyboard.
+
+
+ If you want to see the lines on the screen as they are read you must set
+ the variable echo.
+
+
+
+
+
+
+
+ \l (or \list)
+
+ List all the databases in the server as well as their owners. If the
+ variable description is set, any descriptions for
+ the databases are shown as well. If your
PostgreSQL+ installation was
+ compiled with multibyte encoding support, the encoding scheme of each
+ database is shown as well.
+
+
+
+
+
+
+ \lo_export loid filename
+
+
+ Reads the large object with
OID loid+ from the database and writes it to filename.
+ Note that this is subtly different from the server function lo_export,
+ which acts with the permissions of the user that the database server runs as and
+ on the server's file system.
+
+
+ Use
\lo_list to find out the large object's
OID.
+
+
+
+ See the description of the lo_transaction variable for
+ important information concerning all large object operations.
+
+
+
+
+
+
+
+ \lo_import filename [ comment ]
+
+
+ Stores the file into a
PostgreSQL large object
.
+ Optionally, it associates the given comment with the object. Example:
+foo=> \lo_import '/home/me/pictures/photo.xcf' 'a picture of me'
+lo_import 152801
+
+ The response indicates that the large object received object id 152801
+ which one ought to remember if one wants to access the object every again.
+ For that reason it is recommended to always associate a human-readable
+ comment with every object. Those can then be seen with the
+ \lo_list command.
+
+
+ Note that this command is subtly different from the server-side lo_import
+ because it acts as the local user on the local file system, rather than the server's
+ user and file system.
+
+
+
+ See the description of the lo_transaction variable for
+ important information concerning all large object operations.
+
+
+
+
+
+
+ \lo_list
+
+ Shows a list of all
PostgreSQL large
+ objects currently stored in the database along with their owners.
+ If the variable description is set, the associated
+ comments are shown as well.
+
+
+
+
+
+ \lo_unlink loid
+
+
+ Deletes the large object with
OID loid+ from the database.
+
+
+
+ Use
\lo_list to find out the large object's
OID.
+
+
+
+ See the description of the lo_transaction variable for
+ important information concerning all large object operations.
+
+
+
+
+
+
+
+ \o [ {filename | |command} ]
+
+
+ Saves future query results to the file
+ filename or pipe future
+ results into a separate Unix shell to execute
+ command.
+ If no arguments are specified, the query output will be reset to
+ stdout.
+
+
+ Query results
includes all tables and notices obtained
+ from the database server, as well as output of various backslash
+ commands that query the database (such as \d).
+
+
+
+ To intersperse text output in between query results, use \qecho.
+
+
+
+
+
+
+
+ \p
+
+ Print the current query buffer to the standard output.
+
+
+
+
+
+
+ \pset parameter [ value ]
+
+
+ This command sets options affecting the output of query result tables.
+ parameter describes which option
+ is to be set. The semantics of value
+ depend thereon.
+
+
+ Adjustable printing options are:
+
+
+ format
+
+ Sets the output format to one of unaligned,
+ aligned, html, or latex.
+ Unique abbreviations are allowed. (That would mean one letter is enough.)
+
+
+ Unaligned
writes all fields of a tuple on a line, separated
+ by the currently active field separator. This is intended to create output
+ that might be intended to be read in by other programs (tab-separated,
+ comma-separated).
+ Aligned
mode is the
+ standard, human-readable, nicely formatted text output that is default.
+ The
HTML
and
LaTeX
modes
+ put out tables that are intended to be included in documents using the
+ respective mark-up language. They are not complete documents! (This might
+ not be so dramatic in
HTML, but in LaTeX you must
+ have a complete document wrapper.)
+
+
+
+
+
+ border
+
+ The second argument must be a number. In general, the higher the number
+ the more borders and lines the tables will have, but this depends on
+ the particular format. In
HTML mode, this will
+ translate directly into the border=... attribute, in
+ the others only values 0 (no border), 1 (internal dividing lines), and 2
+ (table frame) make sense.
+
+
+
+
+
+ expanded (or x)
+
+ Toggles between regular and expanded format. When expanded format is
+ enabled, all output has two columns with the field name on the left
+ and the data on the right. This mode is useful if the data wouldn't
+ fit on the screen in the normal horizontal
mode.
+
+
+ Expanded mode is support by all four output modes.
+
+
+
+
+
+ null
+
+ The second argument is a string that should be printed whenever a field
+ is null. The default is not to print anything, which can easily be mistaken
+ for, say, an empty string. There one might choose to write
+ \pset null "(null)".
+
+
+
+
+
+ fieldsep
+
+ Specifies the field separator to be used in unaligned output mode. That way
+ one can create, for example, tab- or comma-separated output, which other
+ programs might prefer. To set a tab as field separator, type
+ \pset fieldsep "\t". The default field separator is
+ |
(a pipe
symbol).
+
+
+
+
+
+ tuples_only (or t)
+
+ Toggles between tuples only and full display. Full display may show
+ extra information such as column headers, titles, and various footers.
+ In tuples only mode, only actual table data is shown.
+
+
+
+
+
+ title [ text ]
+
+ Sets the table title for any subsequently printed tables. This can be
+ used to give your output descriptive tags. If no argument is given,
+ the title is unset.
+
+
+
+ This formerly only affected
HTML mode. You can now
+ set titles in any output format.
+
+
+
+
+
+
+ tableattr (or T) [ text ]
+
+ Allows you to specify any attributes to be places inside the
HTML+ table tag. This could for example be
+ cellpadding or bgcolor. Note that you
+ probably don't want to specify border here, as
+ that is already taken care of by \pset border.
+
+
+
+
+
+
+ pager
+
+ Toggles the list of a pager to do table output. If the environment variable
+ PAGER is set, the output is piped to the specified program.
+ Otherwise /bin/more is assumed.
+
+
+ In any case,
psql only uses the pager if it
+ seems appropriate. That means among other things that the output is to
+ a terminal and that the table would normally not fit on the screen.
+ Because of the modular nature of the printing routines it is not always
+ possible to predict the number of lines that will actually be printed.
+ For that reason
psql might not appear very
+ discriminating about when to use the pager and when not to.
+
+
+
+
+ Illustrations on how these different formats look can be seen in
+ the section.
+
+
+
+ There are various shortcut commands for \pset. See
+ \a, \C, \H,
+ \t, \T, and \x.
+
+
+
+
+ It is an error to call \pset without arguments. In the future
+ this call might show the current status of all printing options.
+
+
+
+
+
+
+
+
+ \q
+
+
+
+
+
+
+
+ \qecho text [ ... ]
+
+ This command is identical to \echo except that
+ all output will be written to the query output channel, as set by
+ \o.
+
+
+
+
+
+
+ \r
+
+ Resets (clears) the query buffer.
+
+
+
+
+
+
+ \s [ filename ]
+
+ Print or save the command line history to
+ filename.
+ If filename is omitted,
+ the history is written to the standard output.
+ This option is only available if
psql is
+ configured to use the
GNU history library.
+
+
+
+ As of
psql version 6.6 it is no longer
+ necessary, in fact, to save the command history as that will be done
+ automatically on program termination. The history is then
+ also automatically loaded every time
psql+ starts up.
+
+
+
+
+
+
+
+ \set [ name [ value ]]
+
+
+ Sets the internal variable name
+ to value. If no second argument
+ is given, the variable is unset (which is different from setting it to,
+ for example, and empty string: \set foo ''). If no
+ arguments are given, all currently defined variables are listed with their
+ values.
+
+
+ Valid variable names can contain lower-case characters, digits, and
+ underscores. In particular, no upper-case characters are allowed, as
+ those are reserved for certain magic
variables and
+ environment variables. See the section about
psql+ variables for details.
+
+
+ Although you are welcome to set any variable to anything you want to,
+
psql treats several variables special.
+ They are documented in the section about variables.
+
+
+
+ This command is totally separate from the
SQL command
+ .
+
+
+
+
+
+
+
+ \t
+
+ Toggles the display of output column name headings and row count footer.
+ This command is equivalent to \pset tuples_only and
+ is provided for convenience.
+
+
+
+
+
+
+ \T table_options
+
+ Allows you to specify options to be placed within the table
+ tag in
HTML tabular output mode. This command is
+ equivalent to \pset tableattr table_options.
+
+
+
+
+
+
+ \w {filename | |command}
+
+ Outputs the current query buffer to the file filename
+ or pipes it to the Unix command command.
+
+
+
+
+
+
+ \x
+
+ Toggles extended row format mode. As such it is equivalent to
+ \pset expanded.
+
+
+
+
+
+
+ \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.
+
+
+
+
+
+ The commands and
+
+ are used to set access permissions.
+
+
+
+
+
+
+
+ \! [ command ]
+
+ Escapes to a separate Unix shell or executes the Unix command
+ command.
+
+
+
+
+
+
+ \?
+
+ Get help information about the slash (\
) commands.
+
+
+
-
+
+
+
+
+
+
+
- 1998-09-26
+ 1998-09-26
-
</div>
<div class="diff rem">- Command-line Options</div>
<div class="diff rem">-
+
+
Command-line Options
+
- understands the following command-line options:
+ If so configured,
psql understands both standard
+ Unix short options, and
GNU-style long options. Since the
+ latter are not available on all systems, you are advised to consider carefully
+ whether to use them, if you are writing scripts, etc. For support on the
+
PostgreSQL mailing lists, you are asked to only
+ use the standard short options.
+
-
+ Many command line options are equivalent to an internal slash command or to
+ setting some variable. Those will not be explained in detail here. Instead,
+ you are asked to look them up in the respective section.
+
+
+
- -A
-
+ -A, --no-align
+
- Turn off fill justification when printing out table elements.
+ Switches to unaligned output mode. (The default output mode is otherwise
+ aligned.)
-
+
+
- -c query
-
+ -c, --command query
+
- Specifies that
- is to execute one query string,
- query,
- and then exit. This is useful for shell scripts, typically in
- conjunction with the option in shell scripts.
+ is to execute one query string, query,
+ and then exit. This is useful for shell scripts, typically in
+ conjunction with the option.
-
-
-
-
- -d dbname
-
- Specifies the name of the database to connect to. This is equivalent to specifying
- dbname as the last field in the
- command line.
+ query must be either a query string
+ that is completely parseable by the backend (i.e., it contains no
psql+ specific features), or it is a single backslash command. Thus
+ you cannot mix
SQL and
psql+ meta-commands. To achieve this you could pipe the string into
+
psql and finish it with a a
\q,
+ like so: echo "select * from foo; \q" | psql.
-
+
-
- -e
-
- Echo the query sent to the backend
-
-
-
- -E
-
+ -d, --dbname dbname
+
- Echo the actual query generated by \d and other backslash commands
+ Specifies the name of the database to connect to. This is equivalent to specifying
+ dbname as the first non-option
+ argument on the command line.
-
+
-
- -f filename
-
- Use the file filename
- as the source of queries instead of reading queries interactively.
- This file must be specified for and visible to the client frontend.
-
-
-
- -F separator
-
+ -e, --echo
+
- Use separator
- as the field separator.
- The default is an ASCII vertical bar ("|").
+ In non-interactive mode, all lines are printed to the screen as they are read.
+ This is equivalent to setting the variable echo.
-
+
-
- -h hostname
-
- Specifies the host name of the machine on which the
- is running.
- Without this option, communication is performed using
- local Unix domain sockets.
-
-
-
- -H
-
+ -E, --echo-all
+
- Turns on
- tabular output.
+ Echos the actual queries generated by \d and other backslash commands.
+ You can use this if you wish to include similar functionality into
+ your own programs. This is equivalent to setting the variable
+
echo_secret from within
psql.
-
+
-
- -l
-
- Lists all available databases, then exit. Other non-connection options are ignored.
-
-
-
- -n
-
+ -f, --file filename
+
- Do not use the readline library for input line editing and command history.
+ Use the file filename
+ as the source of queries instead of reading queries interactively.
+ After the file is processed,
terminates.
+ This in many ways equivalent to the internal command \i.
-
+
-
- -o filename
-
- Put all output into file filename.
- The path must be writable by the client.
-
-
-
- -p port
-
+ -F, --field-sep separator
+
- Specifies the TCP/IP port or, by omission, the local Unix domain socket file
- extension on which the
- is listening for connections. Defaults to the value of the
- PGPORT
- environment variable, if set, or to 5432.
+ Use separator as the field separator.
+ This is equivalent to \pset fieldsep or \f.
-
+
-
- -q
-
- Specifies that
- should do its work quietly. By default, it
- prints welcome and exit messages and prompts for each query.
- If this option is used, none of this happens. This is useful with the
- option.
-
-
-
- -s
-
+ -h, --host hostname
+
- Run in single-step mode where the user is prompted for each query before
- it is sent to the backend.
+ Specifies the host name of the machine on which the
+ Without this option, communication is performed using
+ local Unix domain sockets.
-
+
-
- -S
-
- Runs in single-line mode where each query is terminated by a newline,
- instead of a semicolon.
-
-
-
- -t
-
+ -H, --html
+
- Turn off printing of column names and result row count.
- This is useful with the
-
- option in shell scripts.
+ Turns on
HTML tabular output. This is equivalent
+ to \pset format html or the \H
+ command.
-
+
+
- -T table_options
-
+ -l, --list
+
- Allows you to specify options to be placed within the
-
table ... tag for
HTML 3.0- tabular output.For example, border
- will give you tables with borders.
- This must be used in conjunction with the option.
+ Lists all available databases, then exits. Other non-connection options
+ are ignored. This is similar to the internal command \list.
-
+
-
- -u
-
- Asks the user for the user name and password before connecting to the database.
- If the database does not require password authentication then these are
- ignored. If the option is not used (and the PGPASSWORD environment variable
- is not set) and the database requires password authentication, then the
- connection will fail. The user name is ignored anyway.
-
-
-
- -x
-
+ -n, --no-readline
+
- Turns on extended row format mode. When enabled each row will have its column
- names printed on the left with the column values printed on the right.
- This is useful for rows which are otherwise too long to fit into
- one screen line. HTML row output supports this mode also.
+ Do not use the readline library for input line editing and command history.
-
+
-
-
- You may set environment variables to avoid typing some of the above
- options. See the section on environment variables below.
-
-
-
-
- 1998-09-26
-
-
</div>
<div class="diff rem">- <application>psql</application> Meta-Commands</div>
<div class="diff rem">-
- Anything you enter in
psql - that begins with an unquoted backslash is a
psql- meta-command. Anything else is
SQL- and simply goes into the current query buffer
- (and once you have at least one complete query, it gets automatically
- submitted to the backend).
-
psql meta-commands are also called slash commands.
-
- The format of a
psql command is the backslash,
- followed immediately by
- a command verb, then any arguments. The arguments are separated from the
- command verb and each other by any number of white space characters.
-
- With single character command verbs, you don't actually need to separate the
- command verb from the argument with white space, for historical reasons.
- You should anyway.
-
- The following meta-commands are defined:
-
- \a>
-
+ -o, --out filename>
+
- Toggle field alignment when printing out table elements.
+ Put all query output into file filename.
+ This is equivalent to the command \o.
-
+
-
- \C caption
-
- Set the HTML3.0 table caption to
- caption
.
-
-
-
- \connect meter"ceable> [ username ]
-
+ -p, --port port
+
- Establish a connection to a new database, using the default
- username if none is specified.
- The previous connection is closed.
+ Specifies the TCP/IP port or, by omission, the local Unix domain socket file
+ extension on which the
postmaster+ is listening for connections. Defaults to the value of the
+ PGPORT environment variable or, if not set, to the port
+ specified at compile time, usually 5432.
-
+
-
- \copy meter"ceable> { FROM | TO } filename
-
-
- Perform a frontend (client) copy. This is an operation that runs a SQL COPY command,
- but instead of the backend reading or writing the specified file, and
- consequently requiring backend access and special user privilege,
-
psql reads or writes the
- file and routes the data to or from the backend. The default
- tab
- delimiter is used.
-
-
- This operation is not as efficient as the
SQL - COPY command because all data must pass through the
- client/server IP or socket connection. For large amounts of data this other
- technique may be preferable.
-
-
-
-
- \d [ table ]
-
+ -P, --pset assignment
+
- List tables in the database, or if
- class="parameter">table
- is specified, list the columns in that table.
- If table name is specified as an asterisk (*
),
- list all tables and column information for each tables.
+ Allows you to specify printing options in the style of \pset
+ on the command line. Note that here you have to separate name and value with
+ an equal sign instead of a space. Thus to set the output format to LaTeX, you
+ could write -P format=latex.
-
+
-
- \da
-
- List all available aggregates.
-
-
-
- \dd object
-
+ -q
+
- List the description from pg_description
- of the specified object.
+ Specifies that
psql should do its work quietly.
+ By default, it prints welcome messages, various informational output and
+ prompts for each query.
+ If this option is used, none of this happens. This is useful with the
+
option. Within
psql you can
+ also set the quiet variable to achieve the same effect.
-
- Not all objects have a description in pg_description.
- This meta-command can be useful to get a quick description of a native
-
-
-
+
+
- \df
-
+ -s, --single-step
+
- List functions.
+ Run in single-step mode. That means the user is prompted before each query
+ is sent to the backend, with the option to cancel execution as well.
+ Use this to debug scripts.
-
+
-
- \di
-
- List only indexes.
-
-
-
- \do
-
+ -S, --single-line
+
- List only operators.
+ Runs in single-line mode where a newline sends a query, in addition to a semicolon.
-
-
-
- \ds
-
+
- List only sequences.
+ This mode is provided for those who insist on it, but you are not necessarily
+ encouraged to use it. In particular, if you mix
SQL and
+ meta-commands on a line the order of execution might not always be clear to
+ the unexperienced user. Moral: Unless you exclusively type short queries,
+ avoid using this mode.
-
+
+
+
- \dS
-
+ -t, --tuples-only
+
- List system tables and indexes.
+ Turn off printing of column names and result row count footers, etc.
+ It is completely equivalent to the \t.
-
+
+
- \dt>
-
+ -T, --table-attr table_options>
+
- List only non-system tables.
+ Allows you to specify options to be placed within the
HTML+ table tag. See \pset for details.
-
+
+
- \dT
-
+ -u
+
- List types.
+ Makes
psql prompt for the user name and password
+ before connecting to the database.
-
-
-
- \e [ filename ]
-
- Edit the current query buffer or the contents of the file
- filename.
+ This option is deprecated, as it is conceptually flawed. (Prompting for
+ a non-default user name and prompting for a password because the
+ backend requires it are really two different things.) You are encouraged
+ to look at the and options instead.
-
+
-
- \E [ filename ]
-
- Edit the current query buffer or the contents of the file
- filename
- and execute it upon editor exit.
-
-
-
- \f [ separator ]
-
+ -U, --username username
+
- Set the field separator. Default is a single blank space.
-
-
+ Connects to the database as the user username
+ instead of the default. (You must have permission to do so, of course.) If
+ issues an interactive prompt for the user name.
+
+
+
- \g [ { filename | |command } ]
-
+ -v, --variable, --set assignment
+
- Send the current query input buffer to the backend and optionally
- save the output in filename
- or pipe the output into a separate Unix shell to execute
- command.
+ Performs a variable assignment, like the \set internal command.
+ Note that you must separate name and value, if any, by an equal sign on the command
+ line.
-
+
-
- \h [ command ]
-
- Give syntax help on the specified SQL command.
- If command is not a defined SQL command
- (or is not documented in
psql), or if
- command is not specified,
- list all the commands for which syntax help is
- available. If command
- is an asterisk (*
), then
- give syntax help on all SQL commands.
-
-
-
- \H
-
+ -V, --version
+
- Toggle
HTML3 output. This is equivalent to
- the
- command-line option.
+ Shows version information about
psql and your
+
PostgreSQL database server, if it could be reached.
-
-
-
- \i filename
-
- Read queries from the file filename
- into the query input buffer.
+ The output looks similar to this:
+~$ psql -V
+Server: PostgreSQL 6.5.2 on i586-pc-linux-gnu, compiled by egcs
+psql 6.6.0 on i586-pc-linux-gnu, compiled by gcc 2.8.1 (Oct 27 1999 15:15:04), long options,
+readline, history, locale, assert checks
+
+ The Server
line is identical to the one returned by the
+ backend function version() and thus might vary
+ if you query different servers by using different connection
+ options.
-
-
-
- \l
-
- List all the databases in the server.
+ The
psql
line is compiled into the
psql+ binary. It shows you which
PostgreSQL release
+ it was distributed with and what optional features were compiled into it.
+ Although in general (as in the example above) you can use
psql+ and database servers from different versions (if they don't differ too much)
+ this is not recommended or
+ even necessary. The optional features indicate only
psql's
+ capabilities but if
psql was configured with
+ the same source tree as the rest of the distribution, it gives you an
+ indication about other parts of the installation as well.
-
+
-
- \m
-
- Toggle the old monitor-like table display, which includes border characters
- surrounding the table.
- This is standard SQL output.
- By default,
psql includes only field separators
- between columns.
-
-
-
- \o [ { filename | |command } ]
-
+ -W
+
- Save future query results to the file
- filename or pipe future
- results into a separate Unix shell to execute
- command.
- If no arguments are specified, send query results to
- stdout.
+ Requests that
psql should 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
+ \connect.
-
-
-
- \p
-
- Print the current query buffer.
+ As of version 6.6,
psql automatically issues a
+ password prompt whenever the backend 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 backend requires password authentication
+ the content of the environment variable PGPASSWORD is
+ taken. If this is not set, the connection attempt will fail.
-
-
-
- \q
-
+
+ If you are considering setting the variable PGPASSWORD to do
+ authentication, you have a problem.
-
+
+
-
- \r
-
- Reset(clear) the query buffer.
-
-
-
- \s [ filename ]
-
+ -x
+
- Print or save the command line history to
- filename.
- If filename is omitted,
- do not save subsequent commands to a history file.
- This option is only available if
psql is
- configured to use readline.
+ Turns on extended row format mode. This is equivalent to the command
+ \x.
-
+
-
- \t
-
- Toggle display of output column name headings and row count footer (defaults to on).
-
-
-
+
+
-
- \T table_options
-
- Allows you to specify options to be placed within the
- table ... tag
- tabular output.For example, border
- will give you tables with borders.
- This must be used in conjunction with the \H meta-command.
-
-
-
+ You may set environment variables to avoid typing some of the above
+ options. See the section Connection To A Database
above
+ and in particular the documentation of the
libpq+ client library.
+
+
-
- \x
-
- Toggles extended row format mode. When enabled each row will have its column
- names printed on the left with the column values printed on the right.
- This is useful for rows which are otherwise too long to fit into
- one screen line.
HTML row output mode supports this flag too.
-
-
-
-
- \w filename
-
- Write the current query buffer to the file
- filename.
-
-
-
+
+
+ 1998-09-27
+
-
- \z
-
+
Advanced features
+
+
+ Variables
+
+
psql provides variable substitution features
+ similar to common Unix command shells. Variables are simply name/values
+ pairs, where the value can be any string of any length. To set variables,
+ use the
psql meta-command
\set:
+testdb=> \set foo bar
+
+ sets the variable foo
to the value bar
. To retrieve
+ the content of the variable, precede the name with a dollar-sign and use it
+ as the argument of any slash command:
+testdb=> \echo $foo
+bar
+
+ Alternatively, the value can also be interpolated into a double-quoted (or backtick-quoted)
+ string, like so:
+testdb=> \echo "foo is now ${foo}."
+foo is now bar.
+
+ (The curly braces are required. This is not
Perl.) No variable substitution
+ will be performed in single-quoted strings or in any of the backslash commands
+ that have special parsing rules (\copy, \help).
+
+
+
+ The arguments of \set are subject to the same substitution
+ rules as with other commands. Thus you can construct interesting references
+ such as \set "${foo}bar" 'something' and get variable
+ variables of
Perl or
PHP+ fame. Unfortunately (or fortunately?), there is not way to do anything useful
+ with these constructs. (\echo ${${foo}} doesn't work.) On the
+ other hand, \set bar $foo is a perfectly valid way to copy
+ a variable.
+
+
+
+
psql's internal variable names can consist of
+ lower-case letters, numbers, and underscores in any order and any number of
+ them. Upper-case letters are not allowed. (There is a reason for that. Keep reading.)
+ If you attempt to refer to a variable that does not consist of those
+ characters
psql first checks if it is the name of
+ one of several defined magic
variables. Those variables you cannot
+ set but they always have a value. By convention they all start with an
+ upper-case letter. Finally, if no match is found that way, the value of
+ the respective environment variable is substituted.
+
+
+ Currently, the following magic
variables are defined:
+ Version which contains a string with the version of
+ Port, User are the currently active
+ connection options.
+
+
+ A number of regular variables are treated specially by
psql.
+ They indicate certain option settings that can be changed at runtime
+ by altering the value of the variable. Although you can use these
+ variables for any other purpose, this is not recommended, as the
+ program behavior might grow really strange really quickly. Note that the
+ majority variables are boolean
variables, that is, they
+ only care whether or not are they set, not what to. A list of all specially
+ treated variables follows.
+
+
+ description
+
+ If set, the various \d* commands as well as
+ \l and \lo_list show object
+ descriptions along with the normal information. (Except for
+ \dd which always shows descriptions as this
+ is its very purpose.)
+
+
+
+
+
+ die_on_error
+
+ By default, if non-interactive scripts encounter an error, such as a
+ malformed
SQL query or internal meta-command,
+ processing continues. This is often less than desirable. If this variable
+ is set, script processing will immediately terminate. If the script was
+ called from another script it will terminate in the same fashion.
+ If the outermost script was not called from an interactive
psql+ session but rather using the
option,
psql+ will return error code 3, to distinguish this case from fatal
+ error conditions (error code 1).
+
+
+
+
+
+ echo
+
+ If set, all lines from a script are written to the standard output before they
+ are executed. To specify this on program startup, in conjunction with the
+ option perhaps, use the switch .
+
+
+
+
+
+ echo_secret
+
+ When this variable is set and a backslash command queries the database, the query
+ is first shown. This way you can study the
PostgreSQL+ internals and provide similar functionality in your own programs. If you set the
+ variable to the value noexec
, the queries are just shown but are
+ not actually sent to the backend and executed.
+
+
+
+
+
+ lo_transaction
+
+ If you use the
PostgreSQL large object interface to store
+ data that does not fit into one tuple specially all the operations must be contained
+ in a transaction block. (See the documentation of the large object interface for
+ more information.) Since
psql has no way to keep track if
+ you already have a transaction in progress when you call one of its internal commands
+ \lo_export, \lo_import, \lo_unlink
+ it must take some arbitrary action. This action could either be to roll back any transaction
+ that might already be in progress, or to commit any such transaction, or to do nothing
+ at all. In the latter case you must provide you own BEGIN/END
+ block or the results are unpredictable (usually resulting in the desired action not being
+ performed anyway).
+
+
+ To choose what you want to do you set this variable to one of
+ rollback
, commit
, or nothing
. The default is
+ to roll back the transaction. If you just want to load one or a few objects this is fine.
+ However, if you intend to transfer many large objects, it might be advisable to
+ provide one explicit transaction block around all commands.
+
+
+
+
+
+ prompt1, prompt2, prompt3
+
+ These specify what the prompt
psql issues is
+ supposed to look like. See
+
+ below.
+
+
+
+
+
+ quiet
+
+ This variable is equivalent to the command line option .
+ It is probably not too useful in interactive mode.
+
+
+
+
+
+ singleline
+
+ This variable is set be the command line options . You
+ can unset or reset it at run time.
+
+
+
+
+
+ singlestep
+
+ This variable is equivalent to the command line option .
+
+
+
+
+
+ sql_interpol
+
+ The escape character for
SQL variable interpolation. See below.
+
+
+
+
+
+
+
+
+
+
+
+
+
+ An additional useful feature of
psql variables
+ is that you can substitute (interpolate
) them into
+ regular
SQL statements. In order not to break existing
+
SQL statements, you must choose your own special
+ character that tells
psql that you wish to
+ interpolate the value of a variable here. You do this by setting the
+ variable sql_interpol. Only the first character will be
+ looked at. You can set this variable to anything you want but, for instance,
+ letters, numbers, semicolons, or backslashes will not make your life easier.
+ Reasonable choices include the dollar ($
) and pound
+ (#
) signs.
+testdb=> \set sql_interpol '#'
+
+
+
+ Once this is set up, whenever
psql sees the
+ magic character where it would expect a query, it will continue scanning
+ until it sees the same character again and will interpret anything in
+ between as a variable name.
+testdb=> \set foo 'my_table'
+testdb=> SELECT * FROM #foo#;
+
+ would then query the table my_table. The value of the
+ variable is copied literally, so it can even contain unbalanced quotes or
+ backslash commands. You must make sure that it makes sense where you put it.
+
+
+ One possible application of this mechanism is to copy the contents of a file
+ into a field. First load the file into a variable and then proceed as above.
+testdb=> \set content `cat my_file.txt`
+testdb=> INSERT INTO my_table VALUES ('#content#');
+
+ One possible problem with this approach is that my_file.txt
+ might contain single quotes. These need to be escaped so that
+ they don't cause a syntax error when the second line is processed. This
+ could be done with the program
sed:
+testdb=> \set content `sed -e "s/'/\\\\\\'/g" < my_file.txt`
+
+ Observe the correct number of backslashes (6)! You can resolve it this way: After
+
psql has parsed this line, it passes
+ sed -e "s/'/\\\'/g" < my_file.txt to the shell. The shell
+ will do it's own thing inside the double quotes and execute sed
+ with the arguments -e and s/'/\\'/g.
+ When
sed parses this it will replace the two
+ backslashes with a single one and then do the substitution. Perhaps at
+ one point you thought it was great that all Unix commands use the same
+ escape character. And this is ignoring the fact that you might have to
+ escape all backslashes as well because
SQL text constants
+ are also subject to certain interpretations. In that case you might
+ be better off preparing the file externally.
+
+
+
+
+
+
+ Prompting
+
+ The prompts
psql issues can be customized to
+ your preference. The three variables prompt1, prompt2,
+ and prompt3 contain strings and special escape sequences
+ that describe the appearance of the prompt. Prompt 1 is the normal prompt
+ that is issued when
psql requests a new query.
+ Prompt 2 is issued when more input is expected during query input because
+ the query was not terminated with a semicolon or a quote was not closed.
+ Prompt 3 is issued when you run an
SQL COPY+ command and you are expected to type in the tuples on the terminal.
+
+
+ The value of the respective prompt variable is printed literally, except where
+ a percent sign (%
) is encountered. Depending on the next
+ character, certain other text is substituted instead. Defined substitutions are:
+
+
+
+ %M
+
The hostname of the database server (or .
if Unix domain socket).+
+
+
+ %m
+
The hostname of the database server truncated after the first dot.+
+
+
+ %>
+
The port number at which the database server is listening.+
+
+
+ %n
+
The username you are connected as (not your local system user name).+
+
+
+ %/
+
The name of the current database.+
+
+
+ %~
+
Like %/, but the output is ~
(tilde) if the database+ is your default database.
+
+
+
+ %#
+
If the username is postgres, a #
, otherwise a >
.+
+
+
+ %R
+ In prompt 1 normally =
, but ^
if in single-line mode, and
+ !
if the session is disconnected from the database (which can only
+ happen if \connect fails).
+ In prompt 2 the sequence is replaced by -
, *
, a single quote,
+ or a double quote, depending on whether
psql expects more input
+ because the query wasn't terminated yet, because you are inside a /* ... */
+ comment, or because you are inside a quote.
+ In prompt 3 the sequence doesn't resolve to anything.
+
+
+
+
+ %digits
+ If digits starts with 0x
+ the rest of the characters are interpreted at a hexadecimal digit and the
+ character with the corresponding code is subsituted. If the first digit is 0
+ the characters are interpreted as on octal number and the corresponding character
+ is substituted. Otherwise a decimal number is assumed.
+
+
+
+
+ %$name$
+ The value of the
psql,
magic
, or environment
+ variable name. See the section
+
+ for details.
+
+
+
+
+ %`command`
+ The output of command, similar to
+ ordinary back-tick
substitution.
+
+
+
+
+
+ To insert a percent sign into your prompt, write %%. The
+ default prompts are equivalent to '%/%R%# ' for prompts 1
+ and 2, and '>> ' for prompt 3.
+
+
+
+
+
+
+
+
+ Examples
+
+
+ This section only shows a few examples specific to
psql.
+ If you want to learn
SQL or get familiar with
+
PostgreSQL, you might wish to read the Tutorial that
+ is included in the distribution.
+
+
+
+ The first example shows how to spread a query over several lines of input.
+ Notice the changing prompt.
+testdb=> CREATE TABLE my_table (
+testdb-> first int4 not null default 0,
+testdb-> second text
+testdb-> );
+CREATE
+
+ Now look at the table definition again:
+testdb=> \d my_table
+ Table "my_table"
+ Attribute | Type | Info
+-----------+------+--------------------
+ first | int4 | not null default 0
+ second | text |
+
+
+ At this point you decide to change the prompt to something more
+ interesting:
+testdb=> \set prompt1 '%n@%m %~%R%# '
+peter@localhost testdb=>
+
+ Let's assume you have filled the table with data and want to take a look at it:
+peter@localhost testdb=> SELECT * FROM my_table;
+ first | second
+-------+--------
+ 1 | one
+ 2 | two
+ 3 | three
+ 4 | four
+(4 rows)
+
+
+ Notice how the int4 colums in right aligned while the text column in left aligned.
+ You can make this table look differently by using the \pset
+ command.
+peter@localhost testdb=> \pset border 2
+Border style is 2.
+peter@localhost testdb=> SELECT * FROM my_table;
++-------+--------+
+| first | second |
++-------+--------+
+| 1 | one |
+| 2 | two |
+| 3 | three |
+| 4 | four |
++-------+--------+
+(4 rows)
+
+peter@localhost testdb=> \pset border 0
+Border style is 0.
+peter@localhost testdb=> SELECT * FROM my_table;
+first second
+----- ------
+ 1 one
+ 2 two
+ 3 three
+ 4 four
+(4 rows)
+
+peter@localhost testdb=> \pset border 1
+Border style is 1.
+peter@localhost testdb=> \pset format unaligned
+Output format is unaligned.
+peter@localhost testdb=> \pset fieldsep ","
+Field separator is ",".
+peter@localhost testdb=> \pset tuples_only
+Showing only tuples.
+peter@localhost testdb=> SELECT second, first FROM my_table;
+one,1
+two,2
+three,3
+four,4
+
+ Alternatively, use the short commands:
+peter@localhost testdb=> \a \t \x
+Output format is aligned.
+Tuples only is off.
+Expanded display is on.
+peter@localhost testdb=> SELECT * FROM my_table;
+-[ RECORD 1 ]-
+first | 1
+second | one
+-[ RECORD 2 ]-
+first | 2
+second | two
+-[ RECORD 3 ]-
+first | 3
+second | three
+-[ RECORD 4 ]-
+first | 4
+second | four
+
+
+
+
+
+
+
+
+ 1999-10-27
+
+
+
Appendix
+
+
+
Bugs and Issues
+
+
+
- Produces a list of all tables in the database with their appropriate ACLs
- (grant/revoke permissions) listed.
+ 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 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. For example
+testdb=> \foo
+Field separator is "oo".
+
+ is perhaps not what one would expect.
-
-
+
-
- \! [ command ]
-
+
- Escape to a separate Unix shell or execute the Unix command
- command.
+ There are about three different parsers in
psql,
+ in addition to the backend
SQL parser, all doing their own thing
+ and attempting to get along with each other. Sometimes they do, sometimes
+ they don't. An excellent example of this can be seen in section
+
.
+ Changing this situation, however, is beyond feasability.
-
-
+
-
- \?
-
+
- Get help information about the slash (\
) commands.
+ Several string buffers are assigned fixed sizes at compile time. These
+ are usually based on certain settings about what the backend can accept
+ for a particular quantity. If you use
psql with
+ a different backend than the one it was configured for, you might encounter
+ these limits sooner rather than later.
-
-
-
-
-
+
+
+
+
+
+
+
History and Lineage
+
+
psql first appeared in
Postgres95+ to complement and later replace the
monitor program. (You see this
+ name here or there in really old files. The author has never had the pleasure to use this
+ program though.) An uncountable number of people have added features since to reflect
+ the enhancements in the actual database server.
+
+
+ The present version is the result of a major clean-up and re-write in 1999 by
+
Peter Eisentraut in preparation for release 7.0.+ Many people had again contributed their ideas. The author would also like
+ to recognize the influence of
tcsh at a number
+ of places.
+
+
+
+
+
<acronym>GNU</acronym> readline
+
+ A great deal of
psql's convenience is owed to it
+ using the
GNU readline and history library for accepting
+ and storing user input. To verify whether your copy of
psql+ was compiled with readline support, execute psql -V and check the
+ output for the words readline
and history
.
+
+
+ If you have the readline library installed but
psql+ does not seem to use it, you must make sure that
PostgreSQL's
+ top-level configure script finds it. configure
+ needs to find both the library libreadline.a
+ (or libreadline.so on systems with shared libraries)
+ and the header files readline.h and
+ history.h (or readline/readline.h and
+ readline/history.h) in appropriate directories. If
+ you have the library and header files installed in an obscure place you
+ must tell configure about them, for example:
+$ ./configure --with-includes=/opt/gnu/include --with-libraries=/opt/gnu/lib ...
+
+ Then you have to recompile
psql (not necessarily
+ the entire code tree).
+
+
+ The
GNU readline library can be obtained from the
GNU+ project's
FTP server at
ftp://ftp.gnu.org.+
+
+
+
+
projects / postgresql.git / commitdiff