Provided by: postgresql-client-8.4_8.4.4-2_i386 bug

NAME

       psql - PostgreSQL interactive terminal

SYNOPSIS

       psql [ option... ]  [ dbname
        [ username ]  ]

DESCRIPTION

       psql  is  a  terminal-based  front-end to PostgreSQL. It enables you to
       type in queries interactively, issue them to PostgreSQL,  and  see  the
       query  results.   Alternatively, input can be from a file. 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.

OPTIONS

       -a

       --echo-all
              Print  all input lines to standard output as they are read. This
              is more useful for script  processing  rather  than  interactive
              mode. This is equivalent to setting the variable ECHO to all.

       -A

       --no-align
              Switches  to  unaligned output mode. (The default output mode is
              otherwise aligned.)

       -c command

       --command command
              Specifies that psql is to execute one command  string,  command,
              and then exit. This is useful in shell scripts.

              command  must  be  either  a  command  string that is completely
              parsable by the server  (i.e.,  it  contains  no  psql  specific
              features),  or  a  single backslash command. Thus you cannot mix
              SQL and psql meta-commands with this option.  To  achieve  that,
              you  could  pipe  the  string  into psql, like this: echo ’\x \\
              SELECT * FROM foo;’ | psql.  (\\ is the separator meta-command.)

              If  the  command string contains multiple SQL commands, they are
              processed in a single transaction,  unless  there  are  explicit
              BEGIN/COMMIT  commands  included in the string to divide it into
              multiple transactions. This is different from the behavior  when
              the same string is fed to psql’s standard input.

       -d dbname

       --dbname dbname
              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.

              If  this  parameter  contains  an  =  sign,  it  is treated as a
              conninfo string. See in the documentation for more  information.

       -e

       --echo-queries
              Copy  all  SQL commands sent to the server to standard output as
              well.  This is  equivalent  to  setting  the  variable  ECHO  to
              queries.

       -E

       --echo-hidden
              Echo  the  actual  queries  generated  by \d and other backslash
              commands. You can use this to study psql’s internal  operations.
              This  is  equivalent  to  setting  the variable ECHO_HIDDEN from
              within psql.

       -f filename

       --file filename
              Use the file filename as  the  source  of  commands  instead  of
              reading  commands  interactively.   After the file is processed,
              psql terminates. This is in many ways equivalent to the internal
              command \i.

              If filename is - (hyphen), then standard input is read.

              Using  this  option  is  subtly  different  from  writing psql <
              filename. In general, both will do what you expect, but using -f
              enables  some  nice  features  such  as error messages with line
              numbers. There is also a slight chance that  using  this  option
              will  reduce  the  start-up  overhead.  On  the  other hand, the
              variant using the  shell’s  input  redirection  is  (in  theory)
              guaranteed  to yield exactly the same output that you would have
              gotten had you entered everything by hand.

       -F separator

       --field-separator separator
              Use separator as the field separator for unaligned output.  This
              is equivalent to \pset fieldsep or \f.

       -h hostname

       --host hostname
              Specifies  the  host  name of the machine on which the server is
              running. If the value begins with a slash, it  is  used  as  the
              directory for the Unix-domain socket.

       -H

       --html Turn  on HTML tabular output. This is equivalent to \pset format
              html or the \H command.

       -l

       --list List all available databases, then  exit.  Other  non-connection
              options  are  ignored.  This  is similar to the internal command
              \list.

       -L filename

       --log-file filename
              Write all query output into file filename, in  addition  to  the
              normal output destination.

       -n

       --no-readline
              Do not use readline for line editing and do not use the history.
              This can be useful to turn off tab expansion  when  cutting  and
              pasting.

       -o filename

       --output filename
              Put  all  query output into file filename. This is equivalent to
              the command \o.

       -p port

       --port port
              Specifies the TCP port or  the  local  Unix-domain  socket  file
              extension  on  which  the  server  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.

       -P assignment

       --pset assignment
              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.

       -q

       --quiet
              Specifies that psql should do its work quietly. By  default,  it
              prints  welcome  messages  and  various informational output. If
              this option is used, none of this happens. This is  useful  with
              the  -c option.  Within psql you can also set the QUIET variable
              to achieve the same effect.

       -R separator

       --record-separator separator
              Use separator as the record separator for unaligned output. This
              is equivalent to the \pset recordsep command.

       -s

       --single-step
              Run  in single-step mode. That means the user is prompted before
              each command is sent to the server, with the  option  to  cancel
              execution as well. Use this to debug scripts.

       -S

       --single-line
              Runs  in  single-line  mode  where  a  newline terminates an SQL
              command, as a semicolon does.

              Note: 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 inexperienced user.

       -t

       --tuples-only
              Turn  off printing of column names and result row count footers,
              etc. This is equivalent to the \t command.

       -T table_options

       --table-attr table_options
              Allows you to specify options to be placed within the HTML table
              tag. See \pset for details.

       -U username

       --username username
              Connect  to  the  database  as  the user username instead of the
              default.  (You must have permission to do so, of course.)

       -v assignment

       --set assignment

       --variable assignment
              Perform 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. To unset a  variable,  leave  off  the
              equal  sign.  To  just  set  a variable without a value, use the
              equal sign but leave off the value. These assignments  are  done
              during a very early stage of start-up, so variables reserved for
              internal purposes might get overwritten later.

       -V

       --version
              Print the psql version and exit.

       -w

       --no-password
              Never issue a password prompt. If the server  requires  password
              authentication  and  a  password is not available by other means
              such as a .pgpass file, the connection attempt will  fail.  This
              option  can be useful in batch jobs and scripts where no user is
              present to enter a password.

              Note that this option will remain set for  the  entire  session,
              and  so  it affects uses of the meta-command \connect as well as
              the initial connection attempt.

       -W

       --password
              Force psql to prompt for  a  password  before  connecting  to  a
              database.

              This  option  is  never essential, since psql will automatically
              prompt  for  a  password  if   the   server   demands   password
              authentication.  However,  psql  will waste a connection attempt
              finding out that the server wants a password. In some  cases  it
              is worth typing -W to avoid the extra connection attempt.

              Note  that  this  option will remain set for the entire session,
              and so it affects uses of the meta-command \connect as  well  as
              the initial connection attempt.

       -x

       --expanded
              Turn  on  the expanded table formatting mode. This is equivalent
              to the \x command.

       -X,

       --no-psqlrc
              Do not read the start-up file (neither  the  system-wide  psqlrc
              file nor the user’s ~/.psqlrc file).

       -1

       --single-transaction
              When  psql  executes  a  script  with the -f option, adding this
              option wraps BEGIN/COMMIT around the script to execute it  as  a
              single  transaction.  This  ensures that either all the commands
              complete successfully, or no changes are applied.

              If the script itself  uses  BEGIN,  COMMIT,  or  ROLLBACK,  this
              option  will  not have the desired effects.  Also, if the script
              contains  any  command  that  cannot  be   executed   inside   a
              transaction  block,  specifying  this  option  will  cause  that
              command (and hence the whole transaction) to fail.

       -?

       --help Show help about psql command line arguments, and exit.

EXIT STATUS

       psql returns 0 to the shell if it finished normally, 1 if a fatal error
       of  its own (out of memory, file not found) occurs, 2 if the connection
       to the server went bad and the session was not interactive, and 3 if an
       error occurred in a script and the variable ON_ERROR_STOP was set.

USAGE

   CONNECTING TO A DATABASE
       psql is a regular PostgreSQL client application. In order to connect to
       a database you need to know the name of your target database, the  host
       name  and  port  number  of  the  server and what user name you want to
       connect as. psql can be told about those parameters  via  command  line
       options,  namely  -d,  -h,  -p,  and -U respectively. If an argument is
       found that does not belong to any option it will be interpreted as  the
       database  name  (or  the  user  name,  if  the database name is already
       given). Not all these options are required; there are useful  defaults.
       If  you  omit the host name, psql will connect via a Unix-domain socket
       to a server on the local host, or via TCP/IP to localhost  on  machines
       that  don’t  have  Unix-domain  sockets.  The  default  port  number is
       determined at compile time.  Since the database server  uses  the  same
       default,  you  will  not  have  to  specify the port in most cases. The
       default user name is your Unix user name, as is  the  default  database
       name.  Note that you cannot just connect to any database under any user
       name. Your database administrator should have informed you  about  your
       access rights.

       When the defaults aren’t quite right, you can save yourself some typing
       by setting the environment variables PGDATABASE, PGHOST, PGPORT  and/or
       PGUSER  to  appropriate  values. (For additional environment variables,
       see in the documentation.) It is also convenient to  have  a  ~/.pgpass
       file  to  avoid  regularly  having  to  type  in  passwords. See in the
       documentation for more information.

       An alternative way to specify connection parameters is  in  a  conninfo
       string,  which  is used instead of a database name. This mechanism give
       you very wide control over the connection. For example:

       $ psql "service=myservice sslmode=require"

       This way you can also use  LDAP  for  connection  parameter  lookup  as
       described  in  in the documentation.  See in the documentation for more
       information on all the available connection options.

       If the connection could not be made for any reason (e.g.,  insufficient
       privileges,  server  is  not  running on the targeted host, etc.), psql
       will return an error and terminate.

   ENTERING SQL COMMANDS
       In normal operation, psql provides  a  prompt  with  the  name  of  the
       database  to  which psql is currently connected, followed by the string
       =>. For example:

       $ psql testdb
       psql (8.4.4)
       Type "help" for help.

       testdb=>

       At the prompt, the user can type in SQL  commands.   Ordinarily,  input
       lines  are  sent  to the server when a command-terminating semicolon is
       reached. An end of line does not terminate a command. Thus commands can
       be  spread  over several lines for clarity. If the command was sent and
       executed without error, the results of the command are displayed on the
       screen.

       Whenever  a  command  is  executed,  psql  also  polls for asynchronous
       notification  events  generated  by  LISTEN  [listen(7)]   and   NOTIFY
       [notify(7)].

   META-COMMANDS
       Anything  you enter in psql that begins with an unquoted backslash is a
       psql 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.

       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 whitespace characters.

       To  include  whitespace into an argument you can quote it with a single
       quote. To include a single quote into such an argument, use two  single
       quotes.  Anything  contained in single quotes is furthermore subject to
       C-like substitutions for \n (new line), \t (tab), \digits (octal),  and
       \xdigits (hexadecimal).

       If  an unquoted argument begins with a colon (:), it is taken as a psql
       variable and the value of the variable is used as the argument instead.

       Arguments  that  are  enclosed in backquotes (‘) are taken as a command
       line that is passed to 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 backquotes.

       Some commands take  an  SQL  identifier  (such  as  a  table  name)  as
       argument.  These  arguments  follow  the  syntax rules of SQL: 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.

       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  commands,  if  any. That way SQL and psql commands can be
       freely mixed on a line. But 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, it is switched
              to aligned.  If it is not unaligned, it  is  set  to  unaligned.
              This  command is kept for backwards compatibility. See \pset for
              a more general solution.

       \cd [ directory ]
              Changes the current  working  directory  to  directory.  Without
              argument, changes to the current user’s home directory.

              Tip: To print your current working directory, use \! pwd.

       \C [ title ]
              Sets  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 ] [ host ] [ port ] ]
              Establishes  a new connection to a PostgreSQL server. If the new
              connection is successfully  made,  the  previous  connection  is
              closed.  If any of dbname, username, host or port are omitted or
              specified as -, the value of that parameter  from  the  previous
              connection  is  used.  If  there  is no previous connection, the
              libpq default for the parameter’s value is used.

              If the  connection  attempt  failed  (wrong  user  name,  access
              denied, etc.), the previous connection will only be kept 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 { table [ ( column_list ) ] | ( query ) }
              Performs a frontend (client) copy. This  is  an  operation  that
              runs  an  SQL  COPY [copy(7)] command, but instead of the server
              reading or writing the specified file, psql reads or writes  the
              file  and  routes the data between the server and the local file
              system.  This means that file accessibility and  privileges  are
              those  of  the  local user, not the server, and no SQL superuser
              privileges are required.

              The syntax of the command is similar to that  of  the  SQL  COPY
              [copy(7)]  command.  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.

              \copy  ...  from  stdin  |  to  stdout reads/writes based on the
              command input and output respectively.  All rows are  read  from
              the  same source that issued the command, continuing until \. is
              read or the stream reaches EOF. Output is sent to the same place
              as  command  output. To read/write from psql’s standard input or
              output, use  pstdin  or  pstdout.  This  option  is  useful  for
              populating tables in-line within a SQL script file.

              Tip:  This operation is not as efficient as the SQL COPY command
              because all data must pass through the client/server connection.
              For large amounts of data the SQL command might be preferable.

       \copyright
              Shows the copyright and distribution terms of PostgreSQL.

       \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.)

              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.

              By  default,  only  user-created  objects  are  shown;  supply a
              pattern or the S modifier to include system objects.

              Note: 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.

       \da[S] [ pattern ]
              Lists all available 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.   By default, only user-created objects are shown; supply
              a pattern or the S modifier to include system objects.

       \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  is  listed  with  its
              associated permissions.

       \dc[S] [ pattern ]
              Lists all available conversions between character-set encodings.
              If pattern is specified, only conversions 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.

       \dC [ pattern ]
              Lists  all  available type casts.  If pattern is specified, only
              casts whose source or target types match the pattern are listed.

       \dd[S] [ pattern ]
              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.  By default,
              only user-created objects are shown; supply a pattern or  the  S
              modifier   to   include   system   objects.   ‘‘Object’’  covers
              aggregates,  functions,  operators,  types,  relations  (tables,
              views,  indexes, sequences), large objects, rules, and triggers.
              For example:

              => \dd version
                                   Object descriptions
                 Schema   |  Name   |  Object  |        Description
              ------------+---------+----------+---------------------------
               pg_catalog | version | function | PostgreSQL version string
              (1 row)

              Descriptions  for  objects  can  be  created  with  the  COMMENT
              [comment(7)] SQL command.

       \dD[S] [ pattern ]
              Lists  all  available  domains.  If  pattern  is specified, only
              matching domains  are  shown.   By  default,  only  user-created
              objects are shown; supply a pattern or the S modifier to include
              system objects.

       \des[+] [ pattern ]
              Lists all foreign servers (mnemonic: ‘‘external servers’’).   If
              pattern  is specified, only those servers whose name matches the
              pattern are listed. If the form \des+ is used, a full desription
              of  each  server  is  shown,  including  the server’s ACL, type,
              version, and options.

       \deu[+] [ pattern ]
              Lists all user  mappings  (mnemonic:  ‘‘external  users’’).   If
              pattern is specified, only those mappings whose user names match
              the pattern are listed. If the form \deu+  is  used,  additional
              information about each mapping is shown.

              Caution:  \deu+ might also display the user name and password of
              the remote user, so care should be taken not to disclose them.

       \dew[+] [ pattern ]
              Lists   all   foreign-data   wrappers   (mnemonic:    ‘‘external
              wrappers’’).   If  pattern is specified, only those foreign-data
              wrappers whose name matches the pattern are listed. If the  form
              \dew+  is  used, the ACL and options of the foreign-data wrapper
              are also shown.

       \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 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  modifier  to  include  system
              objects.

              Note:  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.

       \dF[+] [ pattern ]
              Lists  available  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 each
              configuration is shown, including  the  underlying  text  search
              parser and the dictionary list for each parser token type.

       \dFd[+] [ pattern ]
              Lists   available  text  search  dictionaries.   If  pattern  is
              specified, only dictionaries whose names match the  pattern  are
              shown.   If  the  form  \dFd+ is used, additional information is
              shown about each selected dictionary, including  the  underlying
              text search template and the option values.

       \dFp[+] [ pattern ]
              Lists  available  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 each parser is shown,
              including the underlying functions and the  list  of  recognized
              token types.

       \dFt[+] [ pattern ]
              Lists available text search templates.  If pattern is specified,
              only templates whose names match the pattern are shown.  If  the
              form  \dFt+  is used, additional information is shown about each
              template, including the underlying function names.

       \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).  If the form \dg+ is  used,
              additional  information  is shown about each role, including the
              comment for each role.

       \di[S+] [ pattern ]

       \ds[S+] [ pattern ]

       \dt[S+] [ pattern ]

       \dv[S+] [ pattern ]
              In this group of commands, the letters i, s, 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 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.

       \dl    This  is  an  alias  for  \lo_list,  which shows a list of large
              objects.

       \dn[+] [ pattern ]
              Lists available schemas  (namespaces).  If  pattern  (a  regular
              expression)  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 permissions and description, if any.

       \do[S] [ pattern ]
              Lists available 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  pattern  or  the S modifier to include system
              objects.

       \dp [ pattern ]
              Lists  available  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.

              The GRANT [grant(7)] and REVOKE [revoke(7)] commands are used to
              set access privileges.

       \dT[S+] [ pattern ]
              Lists available 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 listed with its internal name and
              size,  as  well as its allowed values if it is an enum type.  By
              default, only user-created objects are shown; supply  a  pattern
              or the S modifier to include system objects.

       \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 is shown about each role,
              including the comment for each role.

       \edit (or \e) [ filename ]
              If filename is specified, the file is edited; after  the  editor
              exits,  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.)
              This means also that if the query ends with (or rather contains)
              a  semicolon, it is immediately executed. In other cases it will
              merely wait in the query buffer.

              Tip:  psql  searches  the  environment  variables   PSQL_EDITOR,
              EDITOR,  and VISUAL (in that order) for an editor to use. If all
              of them are unset, vi is used on Unix  systems,  notepad.exe  on
              Windows systems.

       \ef [ function_description ]
              This  command  fetches  and  edits  the  definition of the named
              function, in the form of a CREATE OR REPLACE  FUNCTION  command.
              Editing  is  done  in  the same way as for \e.  After the editor
              exits, the updated command  waits  in  the  query  buffer;  type
              semicolon or \g to send it, or \r to cancel.

              The  target  function can be specified by name alone, or by name
              and arguments, for example  foo(integer,  text).   The  argument
              types  must  be  given if there is more than one function of the
              same name.

              If no function is specified, a blank CREATE FUNCTION template is
              presented for editing.

       \echo text [ ... ]
              Prints  the  arguments  to the standard output, separated by one
              space  and  followed  by  a  newline.  This  can  be  useful  to
              intersperse information in the output of scripts. For example:

              => \echodate‘
              Tue Oct 26 21:40:57 CEST 1999

              If  the first argument is an unquoted -n the trailing newline is
              not written.

              Tip: If you use the \o command to redirect your query output you
              might wish to use \qecho instead of this command.

       \encoding [ encoding ]
              Sets  the  client  character  set encoding. Without an argument,
              this command shows the current encoding.

       \f [ string ]
              Sets the field separator for unaligned query output. The default
              is  the  vertical  bar  (|). See also \pset for a generic way of
              setting output options.

       \g [ { filename | |command } ]
              Sends  the  current  query  input  buffer  to  the  server   and
              optionally  stores  the  query’s output in filename or pipes the
              output into a separate Unix shell executing command. A  bare  \g
              is  virtually equivalent to a semicolon. A \g with argument is a
              ‘‘one-shot’’ alternative to the \o command.

       \help (or \h) [ command ]
              Gives syntax help on the specified SQL command.  If  command  is
              not  specified,  then  psql will list all the commands for which
              syntax help is available. If command is an  asterisk  (*),  then
              syntax help on all SQL commands is shown.

              Note:  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
              had been typed on the keyboard.

              Note:  If  you  want  to see the lines on the screen as they are
              read you must set the variable ECHO to all.

       \l (or \list)

       \l+ (or \list+)
              List the names, owners,  character  set  encodings,  and  access
              privileges of all the databases in the server.  If + is appended
              to the command name, database sizes,  default  tablespaces,  and
              descriptions  are  also  displayed.   (Size  information is only
              available for databases that the current user can connect to.)

       \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.

              Tip: Use \lo_list to find out the large object’s OID.

       \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/peter/pictures/photo.xcf’ ’a picture of me’
              lo_import 152801

              The  response indicates that the large object received object ID
              152801, which can be used  to  access  the  newly-created  large
              object  in  the  future.  For  the  sake  of  readability, it is
              recommended to always associate a  human-readable  comment  with
              every  object.  Both  OIDs  and  comments can be viewed 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.

       \lo_list
              Shows a list of all PostgreSQL large objects currently stored in
              the database, along with any comments provided for them.

       \lo_unlink loid
              Deletes the large object with OID loid from the database.

              Tip: Use \lo_list to find out the large object’s OID.

       \o [ {filename | |command} ]
              Saves  future query results to the file filename or pipes future
              results into a separate Unix shell to  execute  command.  If  no
              arguments  are  specified, the query output will be reset to the
              standard output.

              ‘‘Query results’’ includes all tables,  command  responses,  and
              notices  obtained from the database server, as well as output of
              various backslash commands that query the database (such as \d),
              but not error messages.

              Tip:  To  intersperse  text output in between query results, use
              \qecho.

       \p     Print the current query buffer to the standard output.

       \password [ username ]
              Changes the password of the  specified  user  (by  default,  the
              current  user).  This  command  prompts  for  the  new password,
              encrypts it, and sends  it  to  the  server  as  an  ALTER  ROLE
              command.  This  makes sure that the new password does not appear
              in  cleartext  in  the  command  history,  the  server  log,  or
              elsewhere.

       \prompt [ text ] name
              Prompts the user to set variable name. An optional prompt, text,
              can be specified. (For multi-word prompts, use single-quotes.)

              By default, \prompt uses the  terminal  for  input  and  output.
              However,  if  the  -f  command line switch is used, \prompt uses
              standard input and 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,
                     wrapped,  html, latex, or troff-ms.  Unique abbreviations
                     are allowed. (That would mean one letter is enough.)

                     ‘‘Unaligned’’ writes all columns of  a  row  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.

                     ‘‘Wrapped’’  is  like  aligned  but  wraps  output to the
                     specified width. If \pset columns is zero (the  default),
                     wrapped mode only affects screen output and wrapped width
                     is controlled by the environment variable COLUMNS or  the
                     detected  screen width. If \pset columns is set to a non-
                     zero value, all output is  wrapped,  including  file  and
                     pipe output.

                     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.)

              columns
                     Controls  the  target  width  for the wrapped format, and
                     width for determining if wide output requires the  pager.
                     Zero  (the  default)  causes the wrapped format to affect
                     only screen output.

              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)
                     You can specify an optional second  argument,  if  it  is
                     provided  it may be either on or off which will enable or
                     disable expanded mode. If  the  second  argument  is  not
                     provided then we will toggle between regular and expanded
                     format. When expanded format is  enabled,  query  results
                     are displayed in two columns, with the column 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 supported by all four output formats.

              null   The second argument is a string that  should  be  printed
                     whenever  a  column  is null. The default is not to print
                     anything, which can easily be mistaken for, say, an empty
                     string.  Thus,  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
                     vertical bar).

              footer You  can  specify  an  optional second argument, if it is
                     provided it may be either on or off which will enable  or
                     disable  display  of  the default footer (x rows). If the
                     second argument is  not  provided  then  we  will  toggle
                     between on and off.

              numericlocale
                     You  can  specify  an  optional second argument, if it is
                     provided it may be either on or off which will enable  or
                     disable  display  of a locale-aware character to separate
                     groups of digits to the left of the  decimal  marker.  If
                     the  second  argument is not provided then we will toggle
                     between on and off.

              recordsep
                     Specifies the record (line) separator to use in unaligned
                     output mode. The default is a newline character.

              tuples_only (or t)
                     You  can  specify  an  optional second argument, if it is
                     provided it may be either on or off which will enable  or
                     disable  the  tuples only mode. If the second argument is
                     not provided then we will toggle between tuples only  and
                     full  display.  Full display shows 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.

              tableattr (or T) [ text ]
                     Allows  you to specify any attributes to be placed 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  Controls  use  of a pager for query and psql help output.
                     If the environment variable PAGER is set, the  output  is
                     piped  to  the  specified program.  Otherwise a platform-
                     dependent default (such as more) is used.

                     When the pager is off, the pager is not  used.  When  the
                     pager  is  on,  the  pager is used only when appropriate,
                     i.e. the output is to a terminal and will not fit on  the
                     screen.   \pset  pager  turns the pager on and off. Pager
                     can also be set to always, which causes the pager  to  be
                     always used.

       Illustrations  on  how  these different formats look can be seen in the
       Examples [psql(1)] section.

              Tip: There are various shortcut commands for \pset. See \a,  \C,
              \H, \t, \T, and \x.

              Note:  It  is  an  error to call \pset without arguments. In the
              future this call might show the current status of  all  printing
              options.

       \q     Quits the psql program.

       \qecho text [ ... ]
              This  command  is identical to \echo except that the 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
              Readline library.

       \set [ name [ value [ ... ] ] ]
              Sets  the  internal  variable name to value or, if more than one
              value is given, to the concatenation  of  all  of  them.  If  no
              second  argument  is  given,  the  variable  is just set with no
              value. To unset a variable, use the \unset command.

              Valid  variable  names  can  contain  characters,  digits,   and
              underscores.  See  the  section  Variables  [psql(1)]  below for
              details.  Variable names are case-sensitive.

              Although you are welcome to set any  variable  to  anything  you
              want,  psql  treats  several  variables  as  special.  They  are
              documented in the section about variables.

              Note: This command is totally separate from the SQL command  SET
              [set(7)].

       \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 attributes to be placed within the table
              tag in HTML tabular output mode. This command is  equivalent  to
              \pset tableattr table_options.

       \timing [ on | off ]
              Without  parameter,  toggles  a  display  of  how  long each SQL
              statement takes, in milliseconds. With parameter, sets same.

       \w {filename | |command}
              Outputs the current query buffer to the file filename  or  pipes
              it to the Unix command command.

       \x     Toggles expanded table formatting mode. As such it is equivalent
              to \pset expanded.

       \z [ pattern ]
              Produces a list of all available  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.

              The GRANT [grant(7)] and REVOKE [revoke(7)] commands are used to
              set access privileges.

              This is an alias for \dp (‘‘display privileges’’).

       \! [ command ]
              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.

       \?     Shows help information about the backslash commands.

   PATTERNS
       The various \d commands accept  a  pattern  parameter  to  specify  the
       object name(s) to be displayed. In the simplest case, a pattern is just
       the exact name of the object.  The  characters  within  a  pattern  are
       normally  folded  to lower case, just as in SQL names; for example, \dt
       FOO will display the table named foo. As in SQL names,  placing  double
       quotes around a pattern stops folding to lower case. Should you need to
       include an actual double quote character in a pattern, write  it  as  a
       pair  of double quotes within a double-quote sequence; again this is in
       accord with the rules for SQL  quoted  identifiers.  For  example,  \dt
       "FOO""BAR"  will  display the table named FOO"BAR (not foo"bar). Unlike
       the normal rules for SQL names, you can put double quotes  around  just
       part  of a pattern, for instance \dt FOO"FOO"BAR will display the table
       named fooFOObar.

       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  begin  with int. But within double
       quotes, * and ? lose  these  special  meanings  and  are  just  matched
       literally.

       A  pattern  that  contains  a  dot  (.) is interpreted as a schema name
       pattern followed by an object name pattern. For example, \dt foo*.*bar*
       displays  all  tables whose table name includes bar that are in schemas
       whose schema name starts with  foo.  When  no  dot  appears,  then  the
       pattern  matches  only  objects  that are visible in the current schema
       search path.  Again, a dot  within  double  quotes  loses  its  special
       meaning and is matched literally.

       Advanced  users  can use regular-expression notations such as character
       classes, for example [0-9] to match any digit. All  regular  expression
       special  characters  work  as specified in in the documentation, except
       for . which is taken as a separator as  mentioned  above,  *  which  is
       translated to the regular-expression notation .*, ? which is translated
       to ., and $ which is matched literally. You can emulate  these  pattern
       characters at need by writing ? for ., (R+|) for R*, or (R|) for R?.  $
       is not needed as a regular-expression character since the pattern  must
       match  the  whole  name,  unlike  the  usual  interpretation of regular
       expressions (in other  words,  $  is  automatically  appended  to  your
       pattern).  Write  *  at  the beginning and/or end if you don’t wish the
       pattern to be anchored.  Note that within double  quotes,  all  regular
       expression  special  characters  lose  their  special  meanings and are
       matched literally. Also, the regular 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 *.*.

   ADVANCED FEATURES
   VARIABLES
       psql  provides  variable  substitution  features similar to common Unix
       command shells.  Variables are simply name/value 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 colon and use it as the argument of
       any slash command:

       testdb=> \echo :foo
       bar

              Note: 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 ’something’ and get ‘‘soft  links’’
              or  ‘‘variable  variables’’  of  Perl or PHP fame, respectively.
              Unfortunately (or fortunately?), there is no way to do  anything
              useful  with  these constructs. On the other hand, \set bar :foo
              is a perfectly valid way to copy a variable.

       If you call \set without a second argument, the variable is  set,  with
       an  empty  string  as  value.  To unset (or delete) a variable, use the
       command \unset.

       psql’s internal variable names can consist  of  letters,  numbers,  and
       underscores  in  any  order  and  any number of them. A number of these
       variables are treated specially by psql. They indicate  certain  option
       settings  that  can be changed at run time by altering the value of the
       variable or represent some state of the application. Although  you  can
       use  these variables for any other purpose, this is not recommended, as
       the program behavior might  grow  really  strange  really  quickly.  By
       convention,  all  specially treated variables consist of all upper-case
       letters (and possibly  numbers  and  underscores).  To  ensure  maximum
       compatibility  in  the future, avoid using such variable names for your
       own purposes. A list of all specially treated variables follows.

       AUTOCOMMIT
              When  on  (the  default),  each  SQL  command  is  automatically
              committed upon successful completion. To postpone commit in this
              mode, you must enter a BEGIN or START TRANSACTION  SQL  command.
              When  off  or  unset,  SQL  commands are not committed until you
              explicitly issue COMMIT or END. The autocommit-off mode works by
              issuing  an implicit BEGIN for you, just before any command that
              is not already in a transaction block and is not itself a  BEGIN
              or  other transaction-control command, nor a command that cannot
              be executed inside a transaction block (such as VACUUM).

              Note: In autocommit-off mode, you must  explicitly  abandon  any
              failed  transaction by entering ABORT or ROLLBACK.  Also keep in
              mind that if you exit the session without committing, your  work
              will be lost.

              Note:   The   autocommit-on  mode  is  PostgreSQL’s  traditional
              behavior, but autocommit-off is closer to the SQL spec.  If  you
              prefer  autocommit-off,  you might wish to set it in the system-
              wide psqlrc file or your ~/.psqlrc file.

       DBNAME The name of the database you are currently connected to. This is
              set  every  time  you  connect  to a database (including program
              start-up), but can be unset.

       ECHO   If set to all, all lines entered from the  keyboard  or  from  a
              script are written to the standard output before they are parsed
              or executed. To select this behavior on  program  start-up,  use
              the switch -a. If set to queries, psql merely prints all queries
              as they are sent to the server. The switch for this is -e.

       ECHO_HIDDEN
              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. (To select this behavior on program start-up, use
              the switch -E.) If you set the variable to the value noexec, the
              queries  are  just shown but are not actually sent to the server
              and executed.

       ENCODING
              The current client character set encoding.

       FETCH_COUNT
              If this variable is set to an integer value > 0, the results  of
              SELECT  queries are fetched and displayed in groups of that many
              rows, rather than the default behavior of collecting the  entire
              result  set  before  display. Therefore only a limited amount of
              memory is used, regardless  of  the  size  of  the  result  set.
              Settings  of  100  to  1000 are commonly used when enabling this
              feature.  Keep in mind that when using  this  feature,  a  query
              might fail after having already displayed some rows.

              Tip:  Although  you can use any output format with this feature,
              the default aligned format tends to look bad because each  group
              of  FETCH_COUNT  rows  will  be formatted separately, leading to
              varying column widths across the row groups.  The  other  output
              formats work better.

       HISTCONTROL
              If this variable is set to ignorespace, lines which begin with a
              space are not entered into the history list. If set to  a  value
              of  ignoredups, lines matching the previous history line are not
              entered. A value of ignoreboth  combines  the  two  options.  If
              unset,  or if set to any other value than those above, all lines
              read in interactive mode are saved on the history list.

              Note: This feature was shamelessly plagiarized from Bash.

       HISTFILE
              The file name that will be used to store the history  list.  The
              default value is ~/.psql_history. For example, putting:

              \set HISTFILE ~/.psql_history- :DBNAME

              in  ~/.psqlrc will cause psql to maintain a separate history for
              each database.

              Note: This feature was shamelessly plagiarized from Bash.

       HISTSIZE
              The number of commands to store  in  the  command  history.  The
              default value is 500.

              Note: This feature was shamelessly plagiarized from Bash.

       HOST   The database server host you are currently connected to. This is
              set every time you connect  to  a  database  (including  program
              start-up), but can be unset.

       IGNOREEOF
              If  unset,  sending  an  EOF character (usually Control+D) to an
              interactive session of psql will terminate the  application.  If
              set  to  a  numeric  value, that many EOF characters are ignored
              before the application terminates. If the variable  is  set  but
              has no numeric value, the default is 10.

              Note: This feature was shamelessly plagiarized from Bash.

       LASTOID
              The  value  of the last affected OID, as returned from an INSERT
              or lo_insert command. This variable is  only  guaranteed  to  be
              valid  until  after  the result of the next SQL command has been
              displayed.

       ON_ERROR_ROLLBACK
              When on, if a statement in  a  transaction  block  generates  an
              error,  the error is ignored and the transaction continues. When
              interactive,  such  errors  are  only  ignored  in   interactive
              sessions,  and  not  when  reading  script  files. When off (the
              default), a statement in a transaction block that  generates  an
              error  aborts  the  entire transaction. The on_error_rollback-on
              mode works by issuing an implicit SAVEPOINT for you, just before
              each  command  that is in a transaction block, and rolls back to
              the savepoint on error.

       ON_ERROR_STOP
              By default, if non-interactive scripts encounter an error,  such
              as  a malformed SQL command or internal meta-command, processing
              continues. This has been the traditional behavior of psql but it
              is  sometimes  not  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 -f option, psql will return error
              code 3, to distinguish this case  from  fatal  error  conditions
              (error code 1).

       PORT   The  database  server port to which you are currently connected.
              This is set every time you  connect  to  a  database  (including
              program start-up), but can be unset.

       PROMPT1

       PROMPT2

       PROMPT3
              These specify what the prompts psql issues should look like. See
              Prompting [psql(1)] below.

       QUIET  This variable is equivalent to the command line option -q. It is
              probably not too useful in interactive mode.

       SINGLELINE
              This variable is equivalent to the command line option -S.

       SINGLESTEP
              This variable is equivalent to the command line option -s.

       USER   The  database  user  you are currently connected as. This is set
              every time you connect to a database (including  program  start-
              up), but can be unset.

       VERBOSITY
              This  variable  can  be  set  to the values default, verbose, or
              terse to control the verbosity of error reports.

   SQL INTERPOLATION
       An additional  useful  feature  of  psql  variables  is  that  you  can
       substitute  (‘‘interpolate’’)  them  into  regular  SQL statements. The
       syntax for this is again to prepend the variable name with a colon (:):

       testdb=> \set foomy_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.
       Variable interpolation will not be performed into quoted SQL  entities.

       One  possible  use  of this mechanism is to copy the contents of a file
       into a table column. 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 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‘ ’’’’

       If you are using non-standard-conforming strings then you’ll also  need
       to double backslashes. This is a bit tricky:

       testdb=> \set content ’’’’ ‘sed -e "s//’’/g" -es/\\/\\\\/g< my_file.txt‘ ’’’’

       Note the use of different shell quoting conventions so that neither the
       single quote marks nor  the  backslashes  are  special  to  the  shell.
       Backslashes  are  still  special  to sed, however, so we need to double
       them. (Perhaps at one point you thought it  was  great  that  all  Unix
       commands use the same escape character.)

       Since  colons  can  legally  appear in SQL commands, the following rule
       applies:  the  character  sequence  ‘‘:name’’  is  not  changed  unless
       ‘‘name’’  is  the name of a variable that is currently set. In any case
       you  can  escape  a  colon  with  a  backslash  to  protect   it   from
       substitution.  (The  colon  syntax  for  variables  is standard SQL for
       embedded query languages, such as ECPG.  The  colon  syntax  for  array
       slices and type casts are PostgreSQL extensions, hence the conflict.)

   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  command.
       Prompt  2  is  issued  when more input is expected during command input
       because the command 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 row values on the terminal.

       The value of the selected 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 full host name (with domain name) of the database server, or
              [local] if the connection is  over  a  Unix  domain  socket,  or
              [local:/dir/name],  if  the  Unix  domain  socket  is not at the
              compiled in default location.

       %m     The host name of the database server,  truncated  at  the  first
              dot,  or [local] if the connection is over a Unix domain socket.

       %>     The port number at which the database server is listening.

       %n     The database session user name. (The  expansion  of  this  value
              might  change  during  a  database  session as the result of the
              command SET SESSION AUTHORIZATION.)

       %/     The name of the current database.

       %~     Like %/, but the output is ~ (tilde) if  the  database  is  your
              default database.

       %#     If the session user is a database superuser, then a #, otherwise
              a >.  (The  expansion  of  this  value  might  change  during  a
              database  session  as  the  result  of  the  command SET SESSION
              AUTHORIZATION.)

       %R     In prompt 1 normally =, but ^ if in single-line mode, and  !  if
              the  session is disconnected from the database (which can happen
              if \connect fails). In prompt 2 the sequence is replaced  by  -,
              *,  a  single quote, a double quote, or a dollar sign, depending
              on whether psql expects more input because  the  command  wasn’t
              terminated  yet,  because you are inside a /* ... */ comment, or
              because you are inside a quoted  or  dollar-escaped  string.  In
              prompt 3 the sequence doesn’t produce anything.

       %x     Transaction  status:  an  empty string when not in a transaction
              block, or * when in a transaction block, or ! when in  a  failed
              transaction   block,   or  ?   when  the  transaction  state  is
              indeterminate (for example, because there is no connection).

       %digits
              The character with the indicated octal code is substituted.

       %:name:
              The value of the psql variable name. See the  section  Variables
              [psql(1)] for details.

       %command‘
              The   output  of  command,  similar  to  ordinary  ‘‘back-tick’’
              substitution.

       %[ ... %]
              Prompts can  contain  terminal  control  characters  which,  for
              example,  change  the  color, background, or style of the prompt
              text, or change the title of the terminal window. In  order  for
              the  line  editing  features of Readline to work properly, these
              non-printing control characters must be designated as  invisible
              by  surrounding them with %[ and %]. Multiple pairs of these can
              occur within the prompt. For example:

              testdb=> \set PROMPT1 ’%[%033[1;33;40m%]%n@%/%R%[%033[0m%]%# ’

              results in a boldfaced (1;) yellow-on-black  (33;40)  prompt  on
              VT100-compatible, color-capable terminals.

       To  insert  a  percent  sign  into  your  prompt, write %%. The default
       prompts are ’%/%R%# ’ for prompts 1 and 2, and ’>> ’ for prompt 3.

              Note: This feature was shamelessly plagiarized from tcsh.

   COMMAND-LINE EDITING
       psql supports the Readline library  for  convenient  line  editing  and
       retrieval.  The  command history is automatically saved when psql exits
       and is reloaded when psql starts up. Tab-completion is also  supported,
       although  the  completion  logic makes no claim to be an SQL parser. If
       for some reason you do not like the tab completion, you can turn it off
       by putting this in a file named .inputrc in your home directory:

       $if psql
       set disable-completion on
       $endif

       (This  is not a psql but a Readline feature. Read its documentation for
       further details.)

ENVIRONMENT

       COLUMNS
              If \pset columns is zero, controls the  width  for  the  wrapped
              format  and  width  for  determining if wide output requires the
              pager.

       PAGER  If the query results do not fit on the screen,  they  are  piped
              through  this  command.  Typical  values  are  more or less. The
              default is platform-dependent. The  use  of  the  pager  can  be
              disabled by using the \pset command.

       PGDATABASE

       PGHOST

       PGPORT

       PGUSER Default connection parameters (see in the documentation).

       PSQL_EDITOR

       EDITOR

       VISUAL Editor used by the \e command. The variables are examined in the
              order listed; the first that is set is used.

       SHELL  Command executed by the \! command.

       TMPDIR Directory for storing temporary files. The default is /tmp.

       This utility, like most  other  PostgreSQL  utilities,  also  uses  the
       environment variables supported by libpq (see in the documentation).

FILES

       · Before  starting  up, psql attempts to read and execute commands from
         the system-wide psqlrc file  and  the  user’s  ~/.psqlrc  file.   (On
         Windows,      the      user’s      startup      file     is     named
         %APPDATA%\postgresql\psqlrc.conf.)   See   PREFIX/share/psqlrc.sample
         for  information on setting up the system-wide file. It could be used
         to set up the client or the server to taste (using the \set  and  SET
         commands).

       · Both the system-wide psqlrc file and the user’s ~/.psqlrc file can be
         made version-specific by appending a dash and the PostgreSQL  release
         number,  for  example  ~/.psqlrc-8.4.4.   A matching version-specific
         file will be read in preference to a non-version-specific file.

       · The command-line history is stored in the  file  ~/.psql_history,  or
         %APPDATA%\postgresql\psql_history on Windows.

NOTES

       · In an earlier life psql allowed the first argument of a single-letter
         backslash command  to  start  directly  after  the  command,  without
         intervening  whitespace.   As  of  PostgreSQL  8.4  this is no longer
         allowed.

       · psql is only guaranteed to work 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.  Backslash
         commands  are particularly likely to fail if the server is of a newer
         version than psql itself.  However,  backslash  commands  of  the  \d
         family  should  work with servers of versions back to 7.4, though not
         necessarily with servers newer than psql itself.

NOTES FOR WINDOWS USERS

       psql is built as a ‘‘console application’’. Since the  Windows  console
       windows  use a different encoding than the rest of the system, you must
       take special care when using 8-bit characters  within  psql.   If  psql
       detects  a  problematic console code page, it will warn you at startup.
       To change the console code page, two things are necessary:

       · Set the code page by entering cmd.exe /c chcp 1252. (1252 is  a  code
         page  that is appropriate for German; replace it with your value.) If
         you are using Cygwin, you can put this command in /etc/profile.

       · Set the console font to Lucida Console, because the raster font  does
         not work with the ANSI code page.

EXAMPLES

       The  first  example shows how to spread a command over several lines of
       input. Notice the changing prompt:

       testdb=> CREATE TABLE my_table (
       testdb(>  first integer not null default 0,
       testdb(>  second text)
       testdb-> ;
       CREATE TABLE

       Now look at the table definition again:

       testdb=> \d my_table
                    Table "my_table"
        Attribute |  Type   |      Modifier
       -----------+---------+--------------------
        first     | integer | not null default 0
        second    | text    |

       Now we 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)

       You can display tables in different ways 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