Provided by: postgresql-client-8.4_8.4.11-1_amd64 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.11)
       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 description 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:

              => \echo `date`
              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 or \quit
              Quits  the  psql  program.   In  a  script  file,  only execution of that script is
              terminated.

       \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 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. 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" -e 's/\\/\\\\/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.11.  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