granicus.if.org Git - postgresql/blob - doc/src/sgml/ref/psql-ref.sgml

   1 <!--
   2 $Header: /cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.51 2001/05/09 17:29:10 momjian Exp $
   3 Postgres documentation
   4 -->
   5
   6 <refentry id="APP-PSQL">
   7  <docinfo>
   8   <date>2000-12-25</date>
   9  </docinfo>
  10
  11   <refmeta>
  12     <refentrytitle id="app-psql-title"><application>psql</application></refentrytitle>
  13     <manvolnum>1</manvolnum>
  14     <refmiscinfo>Application</refmiscinfo>
  15   </refmeta>
  16
  17   <refnamediv>
  18     <refname><application>psql</application></refname>
  19     <refpurpose>
  20       <productname>Postgres</productname> interactive terminal
  21     </refpurpose>
  22   </refnamediv>
  23
  24   <refsynopsisdiv>
  25     <refsynopsisdivinfo>
  26       <date>1999-10-26</date>
  27     </refsynopsisdivinfo>
  28
  29     <synopsis>psql [ <replaceable class="parameter">options</replaceable> ] [ <replaceable class="parameter">dbname</replaceable> [ <replaceable class="parameter">user</replaceable> ] ]</synopsis>
  30
  31   <refsect2 id="R2-APP-PSQL-1">
  32     <refsect2info>
  33       <date>1998-09-26</date>
  34     </refsect2info>
  35
  36     <title>Summary</title>
  37
  38     <para>
  39      <application>psql</application> is a terminal-based front-end to
  40      <productname>Postgres</productname>. It enables you to type in queries
  41      interactively, issue them to <productname>Postgres</productname>, and see
  42      the query results. Alternatively, input can be from a file.
  43      In addition, it provides a number of meta-commands and
  44      various shell-like features to facilitate writing scripts and automating a wide
  45      variety of tasks.
  46     </para>
  47
  48   </refsect2>
  49
  50 </refsynopsisdiv>
  51
  52 <refsect1 id="R1-APP-PSQL-1">
  53   <refsect1info>
  54     <date>1998-10-26</date>
  55   </refsect1info>
  56
  57   <title>Description</title>
  58
  59   <refsect2 id="R2-APP-PSQL-connecting">
  60     <refsect2info>
  61       <date>2000-01-14</date>
  62     </refsect2info>
  63
  64     <title>Connecting To A Database</title>
  65
  66     <para>
  67     <application>psql</application> is a regular <productname>Postgres</productname>
  68     client application. In order to connect to a database you need to know the
  69     name of your target database, the hostname and port number of the server
  70     and what user name you want to connect as. <application>psql</application> can be
  71     told about those parameters via command line options, namely <option>-d</option>,
  72     <option>-h</option>, <option>-p</option>, and <option>-U</option> respectively.
  73     If an argument is found that does not belong to any option it will be interpreted
  74     as the database name (or the user name, if the database name is also
  75          given). Not all these options are required, defaults do apply.
  76     If you omit the host name psql will connect via a Unix domain socket
  77     to a server on the
  78     local host. The default port number is compile-time determined. Since the database
  79     server uses the same default, you will not have to specify the port in most
  80     cases. The default user name is your Unix username, as is the default
  81     database name.
  82     Note that you can't just connect to any database under any username. Your database
  83     administrator should have informed you about your access rights. To save you some typing
  84     you can also set the environment variables <envar>PGDATABASE</envar>,
  85     <envar>PGHOST</envar>, <envar>PGPORT</envar> and <envar>PGUSER</envar>
  86     to appropriate values.
  87     </para>
  88
  89     <para>
  90     If the connection could not be made for any reason (e.g., insufficient
  91     privileges, postmaster is not running on the server, etc.),
  92     <application>psql</application> will return an error and terminate.
  93     </para>
  94   </refsect2>
  95
  96   <refsect2 id="R2-APP-PSQL-4">
  97     <refsect2info>
  98       <date>1998-09-26</date>
  99     </refsect2info>
 100
 101     <title>Entering Queries</title>
 102
 103     <para>
 104     In normal operation, <application>psql</application> provides a prompt with
 105     the name of the database to which <application>psql</application> is currently
 106     connected, followed by the string "=>". For example,
 107 <programlisting>
 108 $ <userinput>psql testdb</userinput>
 109 Welcome to psql, the PostgreSQL interactive terminal.
 110
 111 Type:  \copyright for distribution terms
 112        \h for help with SQL commands
 113        \? for help on internal slash commands
 114        \g or terminate with semicolon to execute query
 115        \q to quit
 116
 117 testdb=>
 118 </programlisting>
 119     </para>
 120
 121     <para>
 122     At the prompt, the user may type in <acronym>SQL</acronym> queries.
 123     Ordinarily, input lines are sent to the backend when a query-terminating
 124     semicolon is reached. An end of line does not terminate a query! Thus queries
 125     can be spread over several lines for clarity. If the query was sent and without
 126     error, the query results are displayed on the screen.
 127     </para>
 128
 129     <para>
 130     Whenever a query is executed, <application>psql</application> also polls
 131     for asynchronous notification events generated by
 132     <xref linkend="SQL-LISTEN" endterm="SQL-LISTEN-title"> and
 133     <xref linkend="SQL-NOTIFY" endterm="SQL-NOTIFY-title">.
 134     </para>
 135   </refsect2>
 136 </refsect1>
 137
 138 <refsect1 id="R1-APP-PSQL-2">
 139     <refsect1info>
 140       <date>1998-09-26</date>
 141     </refsect1info>
 142
 143     <title><application>psql</application> Meta-Commands</title>
 144
 145     <para>
 146     Anything you enter in <application>psql</application> that begins with an
 147     unquoted backslash is a <application>psql</application> meta-command that is
 148     processed by <application>psql</application> itself.
 149     These commands are what makes
 150     <application>psql</application> interesting for administration or scripting.
 151     Meta-commands are more commonly called slash or backslash commands.
 152     </para>
 153
 154     <para>
 155     The format of a <application>psql</application> command is the backslash,
 156     followed immediately by a command verb, then any arguments. The arguments
 157     are separated from the command verb and each other by any number of
 158     whitespace characters.
 159     </para>
 160
 161     <para>
 162     To include whitespace into an argument you must quote it with a single
 163     quote. To include a single quote into such an argument, precede it by
 164     a backslash. Anything contained in single quotes is furthermore subject to
 165     C-like substitutions for <literal>\n</literal> (new line), <literal>\t</literal>
 166      (tab), <literal>\</literal><replaceable>digits</replaceable>,
 167     <literal>\0</literal><replaceable>digits</replaceable>, and
 168     <literal>\0x</literal><replaceable>digits</replaceable>
 169     (the character with the given decimal, octal, or hexadecimal code).
 170     </para>
 171
 172     <para>
 173     If an unquoted argument begins with a colon (<literal>:</literal>),
 174     it is taken as a variable and the value of the variable is taken as the
 175     argument instead.
 176     </para>
 177
 178     <para>
 179     Arguments that are quoted in <quote>backticks</quote> (<literal>`</literal>)
 180     are taken as a command line that is passed to the shell. The output of the
 181     command (with a trailing newline removed) is taken as the argument value.
 182     The above escape sequences also apply in backticks.
 183     </para>
 184
 185     <para>
 186     Some commands take the name of an <acronym>SQL</acronym> identifier (such as
 187     a table name) as argument. These arguments follow the syntax rules of
 188     <acronym>SQL</acronym> regarding double quotes: an identifier without
 189     double quotes is coerced to lower-case. For all other commands
 190     double quotes are not special and will become part of the argument.
 191     </para>
 192
 193     <para>
 194     Parsing for arguments stops when another unquoted backslash occurs. This
 195     is taken as the beginning of a new meta-command. The special sequence
 196     <literal>\\</literal>
 197     (two backslashes) marks the end of arguments and continues parsing
 198     <acronym>SQL</acronym> queries, if any. That way <acronym>SQL</acronym> and
 199     <application>psql</application> commands can be freely mixed on a line.
 200     But in any case, the arguments of a meta-command cannot continue beyond the end
 201     of the line.
 202     </para>
 203
 204     <para>
 205     The following meta-commands are defined:
 206
 207     <variablelist>
 208       <varlistentry>
 209         <term><literal>\a</literal></term>
 210         <listitem>
 211         <para>
 212         If the current table output format is unaligned, switch to aligned.
 213         If it is not unaligned, set it to unaligned. This command is
 214         kept for backwards compatibility. See <command>\pset</command> for a
 215         general solution.
 216         </para>
 217         </listitem>
 218       </varlistentry>
 219
 220       <varlistentry>
 221        <term><literal>\cd</literal> <optional><replaceable>directory</replaceable></optional></term>
 222        <listitem>
 223         <para>
 224          Change the current working directory to
 225          <replaceable>directory</replaceable>.  Without argument,
 226          change to the current user's home directory.
 227         </para>
 228
 229         <tip>
 230          <para>
 231           To print your current working directory, use <literal>\!pwd</literal>.
 232          </para>
 233         </tip>
 234        </listitem>
 235       </varlistentry>
 236
 237       <varlistentry>
 238         <term><literal>\C</literal> [ <replaceable class="parameter">title</replaceable> ]</term>
 239         <listitem>
 240         <para>
 241         Set the title of any tables being printed as the result of a query or
 242         unset any such title. This command is equivalent to
 243         <literal>\pset title <replaceable class="parameter">title</replaceable></literal>.
 244         (The name of this
 245         command derives from <quote>caption</quote>, as it was previously only
 246         used to set the caption in an <acronym>HTML</acronym> table.)
 247         </para>
 248         </listitem>
 249       </varlistentry>
 250
 251       <varlistentry>
 252         <term><literal>\connect</literal> (or <literal>\c</literal>) [ <replaceable class="parameter">dbname</replaceable> [ <replaceable class="parameter">username</replaceable> ] ]</term>
 253         <listitem>
 254         <para>
 255         Establishes a connection to a new database and/or under a user name. The
 256         previous connection is closed.
 257         If <replaceable class="parameter">dbname</replaceable> is <literal>-</literal>
 258         the current database name is assumed.
 259         </para>
 260
 261         <para>
 262         If <replaceable class="parameter">username</replaceable> is omitted
 263         the current user name is assumed.
 264         </para>
 265
 266         <para>
 267         As a special rule, <command>\connect</command> without any arguments will connect
 268         to the default database as the default user (as you would have gotten
 269         by starting <application>psql</application> without any arguments).
 270         </para>
 271
 272         <para>
 273         If the connection attempt failed (wrong username, access denied, etc.), the
 274         previous connection will be kept if and only if <application>psql</application> is
 275         in interactive mode. When executing a non-interactive script, processing
 276         will immediately stop with an error. This distinction was chosen as a user
 277         convenience against typos on the one hand, and a safety mechanism that
 278         scripts are not accidentally acting on the wrong database on the other hand.
 279         </para>
 280         </listitem>
 281       </varlistentry>
 282
 283       <varlistentry>
 284         <term><literal>\copy</literal> <replaceable class="parameter">table</replaceable>
 285         [ <literal>with oids</literal> ] { <literal>from</literal> | <literal>to</literal> }
 286         <replaceable class="parameter">filename</replaceable> | stdin | stdout
 287         [ <literal>using delimiters</literal> '<replaceable class="parameter">characters</replaceable>' ]
 288         [ <literal>with null as</literal> '<replaceable class="parameter">string</replaceable>' ]
 289         </term>
 290
 291         <listitem>
 292         <para>
 293         Performs a frontend (client) copy. This is an operation that runs an
 294         <acronym>SQL</acronym> <xref linkend="SQL-COPY" endterm="SQL-COPY-title"> command,
 295         but instead of the backend's reading or writing the specified file, and
 296         consequently requiring backend access and special user privilege,
 297         as well as being bound to the file system accessible by the backend,
 298         <application>psql</application> reads or writes the
 299         file and routes the data between the backend and the local file system.
 300         </para>
 301
 302         <para>
 303         The syntax of the command is similar to that of the <acronym>SQL</acronym>
 304         <command>COPY</command> command (see its description for the details).
 305         Note that, because of this, special parsing rules apply to the
 306         <command>\copy</command> command. In particular, the variable
 307         substitution rules and backslash escapes do not apply.
 308         </para>
 309
 310         <tip>
 311         <para>
 312         This operation is not as efficient as the <acronym>SQL</acronym>
 313         <command>COPY</command> command because all data must pass through the
 314         client/server IP or socket connection. For large amounts of data the other
 315         technique may be preferable.
 316         </para>
 317         </tip>
 318
 319         <note>
 320         <para>
 321         Note the difference in interpretation of <literal>stdin</literal> and <literal>stdout</literal>
 322         between frontend and backend copies: in a frontend copy these always refer
 323         to <application>psql</application>'s input and output stream. On a backend
 324         copy <literal>stdin</literal> comes from wherever the <command>COPY</command>
 325         itself came from (for example, a script run with the <option>-f</option> option),
 326         and <literal>stdout</literal> refers to the query output stream (see
 327         <command>\o</command> meta-command below).
 328         </para>
 329         </note>
 330         </listitem>
 331       </varlistentry>
 332
 333       <varlistentry>
 334         <term><literal>\copyright</literal></term>
 335         <listitem>
 336         <para>
 337         Shows the copyright and distribution terms of <application>Postgres</application>.
 338         </para>
 339         </listitem>
 340       </varlistentry>
 341
 342       <varlistentry>
 343         <term><literal>\d</literal> <replaceable class="parameter">relation</replaceable> </term>
 344
 345         <listitem>
 346         <para>
 347         Shows all columns of <replaceable class="parameter">relation</replaceable>
 348         (which could be a table, view, index, or sequence),
 349         their types, and any special attributes such as <literal>NOT NULL</literal>
 350         or defaults, if any.
 351         If the relation is, in fact, a table, any defined indices are also listed.
 352         If the relation is a view, the view definition is also shown.
 353         </para>
 354
 355         <para>
 356         The command form <literal>\d+</literal> is identical, but any comments
 357         associated with the table columns are shown as well.
 358         </para>
 359
 360         <note>
 361         <para>
 362         If <command>\d</command> is called without any arguments, it is
 363         equivalent to <command>\dtvs</command> which will show a list
 364         of all tables, views, and sequences. This is purely a convenience
 365         measure.
 366         </para>
 367         </note>
 368         </listitem>
 369       </varlistentry>
 370
 371       <varlistentry>
 372         <term><literal>\da</literal> [ <replaceable class="parameter">pattern</replaceable> ]</term>
 373
 374         <listitem>
 375         <para>
 376         Lists all available aggregate functions, together with the data type they operate on.
 377         If <replaceable class="parameter">pattern</replaceable>
 378         (a regular expression) is specified, only matching aggregates are shown.
 379         </para>
 380         </listitem>
 381       </varlistentry>
 382
 383       <varlistentry>
 384         <term><literal>\dd</literal> [ <replaceable class="parameter">object</replaceable> ]</term>
 385         <listitem>
 386         <para>
 387         Shows the descriptions of <replaceable class="parameter">object</replaceable>
 388         (which can be a regular expression), or of all objects if no argument is given.
 389         (<quote>Object</quote> covers aggregates, functions, operators, types, relations
 390         (tables, views, indices, sequences, large objects), rules, and triggers.) For example:
 391 <programlisting>
 392 => <userinput>\dd version</userinput>
 393               Object descriptions
 394   Name   |   What   |        Description
 395 ---------+----------+---------------------------
 396  version | function | PostgreSQL version string
 397 (1 row)
 398 </programlisting>
 399         </para>
 400
 401         <para>
 402         Descriptions for objects can be generated with the <command>COMMENT ON</command>
 403         <acronym>SQL</acronym> command.
 404         </para>
 405
 406         <note>
 407         <para>
 408         <productname>Postgres</productname> stores the object descriptions in the
 409         pg_description system table.
 410         </para>
 411         </note>
 412
 413         </listitem>
 414       </varlistentry>
 415
 416
 417       <varlistentry>
 418         <term><literal>\df [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
 419
 420         <listitem>
 421         <para>
 422         Lists available functions, together with their argument and return types.
 423         If <replaceable class="parameter">pattern</replaceable>
 424         (a regular expression) is specified, only matching functions are shown.
 425         If the form <literal>\df+</literal> is used, additional information about
 426         each function, including language and description, is shown.
 427         </para>
 428         </listitem>
 429       </varlistentry>
 430
 431
 432       <varlistentry>
 433         <term><literal>\distvS [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
 434
 435         <listitem>
 436         <para>
 437         This is not the actual command name: The letters i, s, t, v, S stand for
 438         index, sequence, table, view, and system table, respectively. You can specify
 439         any or all of them in any order to obtain a listing of them, together with
 440         who the owner is.
 441         </para>
 442
 443         <para>
 444         If <replaceable class="parameter">pattern</replaceable> is specified,
 445         it is a regular expression that restricts the listing to those objects
 446         whose name matches. If one appends a <quote>+</quote> to the command name,
 447         each object is listed with its associated description, if any.
 448         </para>
 449         </listitem>
 450       </varlistentry>
 451
 452
 453       <varlistentry>
 454         <term><literal>\dl</literal></term>
 455         <listitem>
 456         <para>
 457         This is an alias for <command>\lo_list</command>, which shows a list of large objects.
 458         </para>
 459         </listitem>
 460       </varlistentry>
 461
 462
 463       <varlistentry>
 464         <term><literal>\do [ <replaceable class="parameter">name</replaceable> ]</literal></term>
 465         <listitem>
 466         <para>
 467         Lists available operators with their operand and return types.
 468         If <replaceable class="parameter">name</replaceable>
 469         is specified, only operators with that name will be shown.
 470         </para>
 471         </listitem>
 472       </varlistentry>
 473
 474
 475       <varlistentry>
 476         <term><literal>\dp</literal> [ <replaceable class="parameter">pattern</replaceable> ]</term>
 477         <listitem>
 478         <para>
 479         This is an alias for <command>\z</command> which was included for its
 480         greater mnemonic value (<quote>display permissions</quote>).
 481         </para>
 482         </listitem>
 483       </varlistentry>
 484
 485
 486       <varlistentry>
 487         <term><literal>\dT [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
 488         <listitem>
 489         <para>
 490         Lists all data types or only those that match <replaceable class="parameter">pattern</replaceable>.
 491         The command form <literal>\dT+</literal> shows extra information.
 492         </para>
 493         </listitem>
 494       </varlistentry>
 495
 496
 497       <varlistentry>
 498         <term><literal>\du [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
 499         <listitem>
 500         <para>
 501         Lists all configured users or only those that match <replaceable class="parameter">pattern</replaceable>.
 502         </para>
 503         </listitem>
 504       </varlistentry>
 505
 506
 507       <varlistentry>
 508         <term><literal>\edit</literal> (or <literal>\e</literal>) [ <replaceable class="parameter">filename</replaceable> ]</term>
 509
 510         <listitem>
 511         <para>
 512         If <replaceable class="parameter">filename</replaceable> is specified,
 513         the file is edited; after the editor exits, its content is copied
 514         back to the query buffer. If no argument is given, the current query
 515         buffer is copied to a temporary file which is then edited in the same
 516         fashion.
 517         </para>
 518
 519         <para>
 520         The new query buffer is then re-parsed according to the normal rules of
 521         <application>psql</application>, where the whole buffer is treated as
 522         a single line. (Thus you cannot make scripts this way.
 523         Use <command>\i</command> for that.) This means also that
 524         if the query ends with (or rather contains) a semicolon, it is immediately
 525         executed. In other cases it will merely wait in the query buffer.
 526         </para>
 527
 528         <tip>
 529         <para>
 530         <application>psql</application> searches the environment variables
 531         <envar>PSQL_EDITOR</envar>, <envar>EDITOR</envar>, and <envar>VISUAL</envar>
 532         (in that order) for an editor to use. If all of them are unset,
 533         <filename>/bin/vi</filename> is run.
 534         </para>
 535         </tip>
 536         </listitem>
 537       </varlistentry>
 538
 539
 540       <varlistentry>
 541         <term><literal>\echo</literal> <replaceable class="parameter">text</replaceable> [ ... ]</term>
 542         <listitem>
 543         <para>
 544         Prints the arguments to the standard output, separated by one space and
 545         followed by a newline. This can be useful to
 546         intersperse information in the output of scripts. For example:
 547 <programlisting>
 548 => <userinput>\echo `date`</userinput>
 549 Tue Oct 26 21:40:57 CEST 1999
 550 </programlisting>
 551         If the first argument is an unquoted <literal>-n</literal> the the trailing
 552         newline is not written.
 553         </para>
 554
 555         <tip>
 556         <para>
 557         If you use the <command>\o</command> command to redirect your query output
 558         you may wish to use <command>\qecho</command> instead of this command.
 559         </para>
 560         </tip>
 561         </listitem>
 562       </varlistentry>
 563
 564
 565       <varlistentry>
 566         <term><literal>\encoding</literal> [ <replaceable class="parameter">encoding</replaceable> ]</term>
 567
 568         <listitem>
 569         <para>
 570         Sets the client encoding, if you are using multibyte encodings.
 571         Without an argument, this command shows the current encoding.
 572         </para>
 573         </listitem>
 574       </varlistentry>
 575
 576
 577       <varlistentry>
 578         <term><literal>\f</literal> [ <replaceable class="parameter">string</replaceable> ]</term>
 579
 580         <listitem>
 581         <para>
 582         Sets the field separator for unaligned query output. The default is
 583 pipe (<literal>|</literal>). See also <command>\pset</command> for a generic way
 584         of setting output options.
 585         </para>
 586         </listitem>
 587       </varlistentry>
 588
 589
 590       <varlistentry>
 591         <term><literal>\g</literal> [ { <replaceable class="parameter">filename</replaceable> | <literal>|</literal><replaceable class="parameter">command</replaceable> } ]</term>
 592
 593         <listitem>
 594         <para>
 595         Sends the current query input buffer to the backend and optionally
 596         saves the output in <replaceable class="parameter">filename</replaceable>
 597         or pipes the output into a separate Unix shell to execute
 598         <replaceable class="parameter">command</replaceable>. A bare <literal>\g</literal>
 599         is virtually equivalent to a semicolon. A <literal>\g</literal> with argument
 600         is a <quote>one-shot</quote> alternative to the <command>\o</command> command.
 601         </para>
 602         </listitem>
 603       </varlistentry>
 604
 605       <varlistentry>
 606         <term><literal>\help</literal> (or <literal>\h</literal>) [ <replaceable class="parameter">command</replaceable> ]</term>
 607         <listitem>
 608         <para>
 609         Give syntax help on the specified <acronym>SQL</acronym> command.
 610         If <replaceable class="parameter">command</replaceable> is not specified,
 611         then <application>psql</application> will
 612         list all the commands for which syntax help is
 613         available.  If <replaceable class="parameter">command</replaceable>
 614         is an asterisk (<quote>*</quote>), then
 615         syntax help on all <acronym>SQL</acronym> commands is shown.
 616         </para>
 617
 618         <note>
 619         <para>
 620         To simplify typing, commands that consists of several words do not have to be quoted.
 621         Thus it is fine to type <userinput>\help alter table</userinput>.
 622         </para>
 623         </note>
 624         </listitem>
 625       </varlistentry>
 626
 627
 628       <varlistentry>
 629         <term><literal>\H</literal></term>
 630         <listitem>
 631         <para>
 632         Turns on <acronym>HTML</acronym> query output format. If the <acronym>HTML</acronym>
 633         format is already on, it is switched back to the default aligned text format. This
 634         command is for compatibility and convenience, but see <command>\pset</command> about
 635         setting other output options.
 636         </para>
 637         </listitem>
 638       </varlistentry>
 639
 640
 641       <varlistentry>
 642         <term><literal>\i</literal> <replaceable class="parameter">filename</replaceable></term>
 643         <listitem>
 644         <para>
 645         Reads input from the file <replaceable class="parameter">filename</replaceable>
 646         and executes it as though it had been typed on the keyboard.
 647         </para>
 648         <note>
 649         <para>
 650         If you want to see the lines on the screen as they are read you must set
 651         the variable <envar>ECHO</envar> to <literal>all</literal>.
 652         </para>
 653         </note>
 654         </listitem>
 655       </varlistentry>
 656
 657
 658       <varlistentry>
 659         <term><literal>\l</literal> (or <literal>\list</literal>)</term>
 660         <listitem>
 661         <para>
 662         List all the databases in the server as well as their owners. Append a
 663         <quote>+</quote> to the command name to see any descriptions
 664         for the databases as well. If your <productname>Postgres</productname>
 665         installation was
 666         compiled with multibyte encoding support, the encoding scheme of each
 667         database is shown as well.
 668         </para>
 669         </listitem>
 670       </varlistentry>
 671
 672
 673       <varlistentry>
 674         <term><literal>\lo_export</literal> <replaceable class="parameter">loid</replaceable> <replaceable class="parameter">filename</replaceable></term>
 675
 676         <listitem>
 677         <para>
 678         Reads the large object with <acronym>OID</acronym> <replaceable class="parameter">loid</replaceable>
 679         from the database and writes it to <replaceable class="parameter">filename</replaceable>.
 680         Note that this is subtly different from the server function <function>lo_export</function>,
 681         which acts with the permissions of the user that the database server runs as and
 682         on the server's file system.
 683         </para>
 684         <tip>
 685         <para>
 686         Use <command>\lo_list</command> to find out the large object's <acronym>OID</acronym>.
 687         </para>
 688         </tip>
 689         <note>
 690         <para>
 691         See the description of the <envar>LO_TRANSACTION</envar> variable for
 692         important information concerning all large object operations.
 693         </para>
 694         </note>
 695         </listitem>
 696       </varlistentry>
 697
 698
 699       <varlistentry>
 700         <term><literal>\lo_import</literal> <replaceable class="parameter">filename</replaceable> [ <replaceable class="parameter">comment</replaceable> ]</term>
 701
 702         <listitem>
 703         <para>
 704         Stores the file into a <productname>Postgres</productname> <quote>large object</quote>.
 705         Optionally, it associates the given comment with the object. Example:
 706 <programlisting>
 707 foo=> <userinput>\lo_import '/home/peter/pictures/photo.xcf' 'a picture of me'</userinput>
 708 lo_import 152801
 709 </programlisting>
 710         The response indicates that the large object received object id 152801
 711         which one ought to remember if one wants to access the object ever again.
 712         For that reason it is recommended to always associate a human-readable
 713         comment with every object. Those can then be seen with the
 714         <command>\lo_list</command> command.
 715         </para>
 716
 717         <para>
 718         Note that this command is subtly different from the server-side <function>lo_import</function>
 719         because it acts as the local user on the local file system, rather than the server's
 720         user and file system.
 721         </para>
 722
 723         <note>
 724         <para>
 725         See the description of the <envar>LO_TRANSACTION</envar> variable for
 726         important information concerning all large object operations.
 727         </para>
 728         </note>
 729         </listitem>
 730       </varlistentry>
 731
 732       <varlistentry>
 733         <term><literal>\lo_list</literal></term>
 734         <listitem>
 735         <para>
 736         Shows a list of all <productname>Postgres</productname> <quote>large
 737         objects</quote> currently stored in the database, along with any
 738         comments provided for them.
 739         </para>
 740         </listitem>
 741       </varlistentry>
 742
 743       <varlistentry>
 744         <term><literal>\lo_unlink</literal> <replaceable class="parameter">loid</replaceable></term>
 745
 746         <listitem>
 747         <para>
 748         Deletes the large object with <acronym>OID</acronym> <replaceable class="parameter">loid</replaceable>
 749         from the database.
 750         </para>
 751
 752         <tip>
 753         <para>
 754         Use <command>\lo_list</command> to find out the large object's <acronym>OID</acronym>.
 755         </para>
 756         </tip>
 757         <note>
 758         <para>
 759         See the description of the <envar>LO_TRANSACTION</envar> variable for
 760         important information concerning all large object operations.
 761         </para>
 762         </note>
 763         </listitem>
 764       </varlistentry>
 765
 766
 767       <varlistentry>
 768         <term><literal>\o</literal> [ {<replaceable class="parameter">filename</replaceable> | <literal>|</literal><replaceable class="parameter">command</replaceable>} ]</term>
 769
 770         <listitem>
 771         <para>
 772         Saves future query results to the file
 773         <replaceable class="parameter">filename</replaceable> or pipes future
 774         results into a separate Unix shell to execute
 775         <replaceable class="parameter">command</replaceable>.
 776         If no arguments are specified, the query output will be reset to
 777         <filename>stdout</filename>.
 778         </para>
 779
 780         <para>
 781         <quote>Query results</quote> includes all tables, command responses,
 782         and notices obtained
 783         from the database server, as well as output of various backslash
 784         commands that query the database (such as <command>\d</command>),
 785         but not error messages.
 786         </para>
 787
 788         <tip>
 789         <para>
 790         To intersperse text output in between query results, use <command>\qecho</command>.
 791         </para>
 792         </tip>
 793         </listitem>
 794       </varlistentry>
 795
 796
 797       <varlistentry>
 798         <term><literal>\p</literal></term>
 799         <listitem>
 800         <para>
 801         Print the current query buffer to the standard output.
 802         </para>
 803         </listitem>
 804       </varlistentry>
 805
 806
 807       <varlistentry>
 808         <term><literal>\pset</literal> <replaceable class="parameter">parameter</replaceable> [ <replaceable class="parameter">value</replaceable> ]</term>
 809
 810         <listitem>
 811         <para>
 812         This command sets options affecting the output of query result tables.
 813         <replaceable class="parameter">parameter</replaceable> describes which option
 814         is to be set. The semantics of <replaceable class="parameter">value</replaceable>
 815         depend thereon.
 816         </para>
 817
 818         <para>
 819         Adjustable printing options are:
 820         <variablelist>
 821           <varlistentry>
 822           <term><literal>format</literal></term>
 823           <listitem>
 824           <para>
 825           Sets the output format to one of <literal>unaligned</literal>,
 826           <literal>aligned</literal>, <literal>html</literal>, or <literal>latex</literal>.
 827           Unique abbreviations are allowed. (That would mean one letter is enough.)
 828           </para>
 829
 830           <para>
 831           <quote>Unaligned</quote> writes all fields of a tuple on a line, separated
 832           by the currently active field separator. This is intended to create output
 833           that might be intended to be read in by other programs (tab-separated,
 834           comma-separated).
 835           <quote>Aligned</quote> mode is the
 836           standard, human-readable, nicely formatted text output that is default.
 837           The <quote><acronym>HTML</acronym></quote> and <quote>LaTeX</quote> modes
 838           put out tables that are intended to be included in documents using the
 839           respective mark-up language. They are not complete documents! (This might
 840           not be so dramatic in <acronym>HTML</acronym>, but in LaTeX you must
 841           have a complete document wrapper.)
 842           </para>
 843           </listitem>
 844           </varlistentry>
 845
 846           <varlistentry>
 847           <term><literal>border</literal></term>
 848           <listitem>
 849           <para>
 850           The second argument must be a number. In general, the higher the number
 851           the more borders and lines the tables will have, but this depends on
 852           the particular format. In <acronym>HTML</acronym> mode, this will
 853           translate directly into the <literal>border=...</literal> attribute, in
 854           the others only values 0 (no border), 1 (internal dividing lines), and 2
 855           (table frame) make sense.
 856           </para>
 857           </listitem>
 858           </varlistentry>
 859
 860           <varlistentry>
 861           <term><literal>expanded</literal> (or <literal>x</literal>)</term>
 862           <listitem>
 863           <para>
 864           Toggles between regular and expanded format. When expanded format is
 865           enabled, all output has two columns with the field name on the left
 866           and the data on the right. This mode is useful if the data wouldn't
 867           fit on the screen in the normal <quote>horizontal</quote> mode.
 868           </para>
 869
 870           <para>
 871           Expanded mode is supported by all four output modes.
 872           </para>
 873           </listitem>
 874           </varlistentry>
 875
 876           <varlistentry>
 877           <term><literal>null</literal></term>
 878           <listitem>
 879           <para>
 880           The second argument is a string that should be printed whenever a field
 881           is null. The default is not to print anything, which can easily be mistaken
 882           for, say, an empty string. Thus, one might choose to write
 883           <literal>\pset null '(null)'</literal>.
 884           </para>
 885           </listitem>
 886           </varlistentry>
 887
 888           <varlistentry>
 889           <term><literal>fieldsep</literal></term>
 890           <listitem>
 891           <para>
 892           Specifies the field separator to be used in unaligned output mode. That way
 893           one can create, for example, tab- or comma-separated output, which other
 894           programs might prefer. To set a tab as field separator, type
 895           <literal>\pset fieldsep '\t'</literal>. The default field separator is
 896           <literal>'|'</literal> (a <quote>pipe</quote> symbol).
 897           </para>
 898           </listitem>
 899           </varlistentry>
 900
 901           <varlistentry>
 902           <term><literal>recordsep</literal></term>
 903           <listitem>
 904           <para>
 905           Specifies the record (line) separator to use in unaligned output mode. The default
 906           is a newline character.
 907           </para>
 908           </listitem>
 909           </varlistentry>
 910
 911           <varlistentry>
 912           <term><literal>tuples_only</literal> (or <literal>t</literal>)</term>
 913           <listitem>
 914           <para>
 915           Toggles between tuples only and full display. Full display may show
 916           extra information such as column headers, titles, and various footers.
 917           In tuples only mode, only actual table data is shown.
 918           </para>
 919           </listitem>
 920           </varlistentry>
 921
 922           <varlistentry>
 923           <term><literal>title</literal> [ <replaceable class="parameter">text</replaceable> ]</term>
 924           <listitem>
 925           <para>
 926           Sets the table title for any subsequently printed tables. This can be
 927           used to give your output descriptive tags. If no argument is given,
 928           the title is unset.
 929           </para>
 930
 931           <note>
 932           <para>
 933           This formerly only affected <acronym>HTML</acronym> mode. You can now
 934           set titles in any output format.
 935           </para>
 936           </note>
 937           </listitem>
 938           </varlistentry>
 939
 940           <varlistentry>
 941           <term><literal>tableattr</literal> (or <literal>T</literal>) [ <replaceable class="parameter">text</replaceable> ]</term>
 942           <listitem>
 943           <para>
 944           Allows you to specify any attributes to be placed inside the <acronym>HTML</acronym>
 945           <sgmltag>table</sgmltag> tag. This could for example be
 946           <literal>cellpadding</literal> or <literal>bgcolor</literal>. Note that you
 947           probably don't want to specify <literal>border</literal> here, as
 948           that is already taken care of by <literal>\pset border</literal>.
 949           </para>
 950           </listitem>
 951           </varlistentry>
 952
 953
 954           <varlistentry>
 955           <term><literal>pager</literal></term>
 956           <listitem>
 957           <para>
 958           Toggles the list of a pager to do table output. If the environment variable
 959           <envar>PAGER</envar> is set, the output is piped to the specified program.
 960           Otherwise <filename>more</filename> is used.
 961           </para>
 962
 963           <para>
 964           In any case, <application>psql</application> only uses the pager if it
 965           seems appropriate. That means among other things that the output is to
 966           a terminal and that the table would normally not fit on the screen.
 967           Because of the modular nature of the printing routines it is not always
 968           possible to predict the number of lines that will actually be printed.
 969           For that reason <application>psql</application> might not appear very
 970           discriminating about when to use the pager and when not to.
 971           </para>
 972           </listitem>
 973           </varlistentry>
 974         </variablelist>
 975         Illustrations on how these different formats look can be seen in
 976         the <xref linkend="APP-PSQL-examples" endterm="APP-PSQL-examples-title"> section.
 977         </para>
 978
 979         <tip>
 980         <para>
 981         There are various shortcut commands for <command>\pset</command>. See
 982         <command>\a</command>, <command>\C</command>, <command>\H</command>,
 983         <command>\t</command>, <command>\T</command>, and <command>\x</command>.
 984         </para>
 985         </tip>
 986
 987         <note>
 988         <para>
 989         It is an error to call <command>\pset</command> without arguments. In the future
 990         this call might show the current status of all printing options.
 991         </para>
 992         </note>
 993
 994         </listitem>
 995       </varlistentry>
 996
 997
 998       <varlistentry>
 999         <term><literal>\q</literal></term>
1000         <listitem>
1001         <para>
1002         Quit the <application>psql</application> program.
1003         </para>
1004         </listitem>
1005       </varlistentry>
1006
1007
1008       <varlistentry>
1009         <term><literal>\qecho</literal> <replaceable class="parameter">text</replaceable> [ ... ] </term>
1010         <listitem>
1011         <para>
1012         This command is identical to <command>\echo</command> except that
1013         all output will be written to the query output channel, as set by
1014         <command>\o</command>.
1015         </para>
1016         </listitem>
1017       </varlistentry>
1018
1019
1020       <varlistentry>
1021         <term><literal>\r</literal></term>
1022         <listitem>
1023         <para>
1024         Resets (clears) the query buffer.
1025         </para>
1026         </listitem>
1027       </varlistentry>
1028
1029
1030       <varlistentry>
1031         <term><literal>\s</literal> [ <replaceable class="parameter">filename</replaceable> ]</term>
1032         <listitem>
1033         <para>
1034         Print or save the command line history to
1035         <replaceable class="parameter">filename</replaceable>.
1036         If <replaceable class="parameter">filename</replaceable> is omitted,
1037         the history is written to the standard output.
1038         This option is only available if <application>psql</application> is
1039         configured to use the <acronym>GNU</acronym> history library.
1040         </para>
1041
1042         <note>
1043         <para>
1044         As of <application>psql</application> version 7.0 it is no longer
1045         necessary to save the command history, since that will be done
1046         automatically on program termination. The history is
1047         also loaded automatically every time <application>psql</application>
1048         starts up.
1049         </para>
1050         </note>
1051         </listitem>
1052       </varlistentry>
1053
1054
1055       <varlistentry>
1056         <term><literal>\set</literal> [ <replaceable class="parameter">name</replaceable> [ <replaceable class="parameter">value</replaceable> [ ... ]]]</term>
1057
1058         <listitem>
1059         <para>
1060         Sets the internal variable <replaceable class="parameter">name</replaceable>
1061         to <replaceable class="parameter">value</replaceable> or, if more than one
1062         value is given, to the concatenation of all of them. If no second argument
1063         is given, the variable is just set with no value. To unset a variable, use
1064         the <command>\unset</command> command.
1065         </para>
1066
1067         <para>
1068         Valid variable names can contain characters, digits, and underscores.
1069         See the section about <application>psql</application> variables for details.
1070         </para>
1071
1072         <para>
1073         Although you are welcome to set any variable to anything you want,
1074         <application>psql</application> treats several variables as special.
1075         They are documented in the section about variables.
1076         </para>
1077
1078         <note>
1079         <para>
1080         This command is totally separate from the <acronym>SQL</acronym> command
1081         <xref linkend="SQL-SET" endterm="SQL-SET-title">.
1082         </para>
1083         </note>
1084         </listitem>
1085       </varlistentry>
1086
1087
1088       <varlistentry>
1089         <term><literal>\t</literal></term>
1090         <listitem>
1091         <para>
1092         Toggles the display of output column name headings and row count footer.
1093         This command is equivalent to <literal>\pset tuples_only</literal> and
1094         is provided for convenience.
1095         </para>
1096         </listitem>
1097       </varlistentry>
1098
1099
1100       <varlistentry>
1101         <term><literal>\T</literal> <replaceable class="parameter">table_options</replaceable></term>
1102         <listitem>
1103         <para>
1104         Allows you to specify options to be placed within the <sgmltag>table</sgmltag>
1105         tag in <acronym>HTML</acronym> tabular output mode. This command is
1106         equivalent to <literal>\pset tableattr <replaceable class="parameter">table_options</replaceable></literal>.
1107         </para>
1108         </listitem>
1109       </varlistentry>
1110
1111
1112       <varlistentry>
1113         <term><literal>\w</literal> {<replaceable class="parameter">filename</replaceable> | <replaceable class="parameter">|command</replaceable>}</term>
1114         <listitem>
1115         <para>
1116         Outputs the current query buffer to the file <replaceable class="parameter">filename</replaceable>
1117         or pipes it to the Unix command <replaceable class="parameter">command</replaceable>.
1118         </para>
1119         </listitem>
1120       </varlistentry>
1121
1122
1123       <varlistentry>
1124         <term><literal>\x</literal></term>
1125         <listitem>
1126         <para>
1127         Toggles extended row format mode. As such it is equivalent to
1128         <literal>\pset expanded</literal>.
1129        </para>
1130        </listitem>
1131       </varlistentry>
1132
1133
1134       <varlistentry>
1135         <term><literal>\z</literal> [ <replaceable class="parameter">pattern</replaceable> ]</term>
1136         <listitem>
1137         <para>
1138         Produces a list of all tables in the database with their appropriate
1139         access permissions listed. If an argument is given it is taken as a regular
1140         expression which limits the listing to those tables which match it.
1141         </para>
1142
1143         <para>
1144 <programlisting>
1145 test=> <userinput>\z</userinput>
1146 Access permissions for database "test"
1147  Relation |           Access permissions
1148 ----------+-------------------------------------
1149  my_table | {"=r","joe=arwR", "group staff=ar"}
1150 (1 row )
1151 </programlisting>
1152         Read this as follows:
1153
1154         <itemizedlist>
1155           <listitem>
1156           <para>
1157           <literal>"=r"</literal>: <literal>PUBLIC</literal> has read
1158           (<command>SELECT</command>) permission on the table.
1159           </para>
1160           </listitem>
1161
1162           <listitem>
1163           <para>
1164           <literal>"joe=arwR"</literal>: User <literal>joe</literal> has read,
1165           write (<command>UPDATE</command>, <command>DELETE</command>),
1166           <quote>append</quote> (<command>INSERT</command>) permissions,
1167           and permission to create rules on the table.
1168           </para>
1169           </listitem>
1170
1171           <listitem>
1172           <para>
1173           <literal>"group staff=ar"</literal>: Group <literal>staff</literal>
1174           has <command>SELECT</command> and <command>INSERT</command> permission.
1175           </para>
1176           </listitem>
1177         </itemizedlist>
1178         </para>
1179
1180         <para>
1181         The commands <xref linkend="SQL-GRANT" endterm="SQL-GRANT-title"> and
1182         <xref linkend="SQL-REVOKE" endterm="SQL-REVOKE-title">
1183         are used to set access permissions.
1184         </para>
1185
1186         </listitem>
1187       </varlistentry>
1188
1189
1190       <varlistentry>
1191         <term><literal>\!</literal> [ <replaceable class="parameter">command</replaceable> ]</term>
1192         <listitem>
1193         <para>
1194         Escapes to a separate Unix shell or executes the Unix command
1195         <replaceable class="parameter">command</replaceable>. The arguments
1196         are not further interpreted, the shell will see them as is.
1197         </para>
1198         </listitem>
1199       </varlistentry>
1200
1201
1202       <varlistentry>
1203         <term><literal>\?</literal></term>
1204         <listitem>
1205         <para>
1206         Get help information about the backslash (<quote>\</quote>) commands.
1207         </para>
1208         </listitem>
1209       </varlistentry>
1210
1211     </variablelist>
1212   </para>
1213 </refsect1>
1214
1215
1216
1217 <refsect1 id="R1-APP-PSQL-3">
1218   <refsect1info>
1219     <date>1998-09-26</date>
1220   </refsect1info>
1221
1222   <title>Command-line Options</title>
1223
1224   <para>
1225   If so configured, <application>psql</application> understands both standard
1226   Unix short options, and <acronym>GNU</acronym>-style long options. The latter
1227   are not available on all systems.
1228   </para>
1229
1230   <para>
1231   <variablelist>
1232     <varlistentry>
1233       <term>-a, --echo-all</term>
1234       <listitem>
1235       <para>
1236       Print all the lines to the screen as they are read. This is more useful for
1237       script processing rather than interactive mode.
1238       This is equivalent to setting the variable <envar>ECHO</envar> to <literal>all</literal>.
1239       </para>
1240       </listitem>
1241     </varlistentry>
1242
1243
1244     <varlistentry>
1245       <term>-A, --no-align</term>
1246       <listitem>
1247       <para>
1248       Switches to unaligned output mode. (The default output mode is otherwise
1249       aligned.)
1250       </para>
1251       </listitem>
1252     </varlistentry>
1253
1254
1255     <varlistentry>
1256       <term>-c, --command <replaceable class="parameter">query</replaceable></term>
1257       <listitem>
1258       <para>
1259       Specifies that <application>psql</application>
1260       is to execute one query string, <replaceable class="parameter">query</replaceable>,
1261       and then exit.  This is useful in shell scripts.
1262       </para>
1263       <para>
1264       <replaceable class="parameter">query</replaceable> must be either a query string
1265       that is completely parseable by the backend (i.e., it contains no <application>psql</application>
1266       specific features), or it is a single backslash command. Thus
1267       you cannot mix <acronym>SQL</acronym> and <application>psql</application>
1268       meta-commands. To achieve that, you could pipe the string into
1269       <application>psql</application>, like this:
1270       <literal>echo "\x \\ select * from foo;" | psql</literal>.
1271       </para>
1272       </listitem>
1273     </varlistentry>
1274
1275
1276     <varlistentry>
1277       <term>-d, --dbname <replaceable class="parameter">dbname</replaceable></term>
1278       <listitem>
1279       <para>
1280       Specifies the name of the database to connect to. This is equivalent to specifying
1281       <replaceable class="parameter">dbname</replaceable> as the first non-option
1282       argument on the command line.
1283       </para>
1284       </listitem>
1285     </varlistentry>
1286
1287
1288     <varlistentry>
1289       <term>-e, --echo-queries</term>
1290       <listitem>
1291       <para>
1292       Show all queries that are sent to the backend.
1293       This is equivalent to setting the variable <envar>ECHO</envar>
1294       to <literal>queries</literal>.
1295       </para>
1296       </listitem>
1297     </varlistentry>
1298
1299
1300     <varlistentry>
1301       <term>-E, --echo-hidden</term>
1302       <listitem>
1303       <para>
1304       Echoes the actual queries generated by \d and other backslash commands.
1305       You can use this if you wish to include similar functionality into
1306       your own programs. This is equivalent to setting the variable
1307       <envar>ECHO_HIDDEN</envar> from within <application>psql</application>.
1308       </para>
1309       </listitem>
1310     </varlistentry>
1311
1312
1313     <varlistentry>
1314       <term>-f, --file <replaceable class="parameter">filename</replaceable></term>
1315       <listitem>
1316       <para>
1317       Use the file <replaceable class="parameter">filename</replaceable>
1318       as the source of queries instead of reading queries interactively.
1319       After the file is processed, <application>psql</application> terminates.
1320       This is in many ways equivalent to the internal command <command>\i</command>.
1321       </para>
1322
1323       <para>
1324        If <replaceable>filename</replaceable> is <literal>-</literal>
1325        (hyphen), then standard input is read.
1326       </para>
1327
1328       <para>
1329       Using this option is subtly different from writing
1330       <literal>psql &lt; <replaceable class="parameter">filename</replaceable></literal>.
1331       In general, both will do what you expect, but using <literal>-f</literal>
1332       enables some nice features such as error messages with line numbers.
1333       There is also a slight chance that using this option will reduce
1334       the start-up overhead. On the other hand, the variant using the shell's
1335       input redirection is (in theory) guaranteed to yield exactly the same
1336       output that you would have gotten had you entered everything by hand.
1337       </para>
1338       </listitem>
1339     </varlistentry>
1340
1341
1342     <varlistentry>
1343       <term>-F, --field-separator <replaceable class="parameter">separator</replaceable></term>
1344       <listitem>
1345       <para>
1346       Use <replaceable class="parameter">separator</replaceable> as the field separator.
1347       This is equivalent to <command>\pset fieldsep</command> or <command>\f</command>.
1348       </para>
1349       </listitem>
1350     </varlistentry>
1351
1352
1353     <varlistentry>
1354       <term>-h, --host <replaceable class="parameter">hostname</replaceable></term>
1355       <listitem>
1356       <para>
1357       Specifies the host name of the machine on which the
1358       <application>postmaster</application> is running.
1359       If host begins with a slash, it is used
1360       as the directory for the unix domain socket.
1361       </para>
1362       </listitem>
1363     </varlistentry>
1364
1365
1366     <varlistentry>
1367       <term>-H, --html</term>
1368       <listitem>
1369       <para>
1370       Turns on <acronym>HTML</acronym> tabular output. This is equivalent
1371       to <literal>\pset format html</literal> or the <command>\H</command>
1372       command.
1373       </para>
1374       </listitem>
1375     </varlistentry>
1376
1377
1378     <varlistentry>
1379       <term>-l, --list</term>
1380       <listitem>
1381       <para>
1382       Lists all available databases, then exits. Other non-connection options
1383       are ignored. This is similar to the internal command <command>\list</command>.
1384       </para>
1385       </listitem>
1386     </varlistentry>
1387
1388
1389     <varlistentry>
1390       <term>-o, --output <replaceable class="parameter">filename</replaceable></term>
1391       <listitem>
1392       <para>
1393       Put all query output into file <replaceable class="parameter">filename</replaceable>.
1394       This is equivalent to the command <command>\o</command>.
1395       </para>
1396       </listitem>
1397     </varlistentry>
1398
1399
1400     <varlistentry>
1401       <term>-p, --port <replaceable class="parameter">port</replaceable></term>
1402       <listitem>
1403       <para>
1404       Specifies the TCP/IP port or, by omission, the local Unix domain socket file
1405       extension on which the <application>postmaster</application>
1406       is listening for connections.  Defaults to the value of the
1407       <envar>PGPORT</envar> environment variable or, if not set, to the port
1408       specified at compile time, usually 5432.
1409       </para>
1410       </listitem>
1411     </varlistentry>
1412
1413
1414     <varlistentry>
1415       <term>-P, --pset <replaceable class="parameter">assignment</replaceable></term>
1416       <listitem>
1417       <para>
1418       Allows you to specify printing options in the style of <command>\pset</command>
1419       on the command line. Note that here you have to separate name and value with
1420       an equal sign instead of a space. Thus to set the output format to LaTeX, you
1421       could write <literal>-P format=latex</literal>.
1422       </para>
1423       </listitem>
1424     </varlistentry>
1425
1426
1427     <varlistentry>
1428       <term>-q</term>
1429       <listitem>
1430       <para>
1431       Specifies that <application>psql</application> should do its work quietly.
1432       By default, it prints welcome messages and various informational output.
1433       If this option is used, none of this happens. This is useful with the
1434       <option>-c</option> option. Within <application>psql</application> you can
1435       also set the <envar>QUIET</envar> variable to achieve the same effect.
1436       </para>
1437       </listitem>
1438     </varlistentry>
1439
1440
1441     <varlistentry>
1442       <term>-R, --record-separator <replaceable class="parameter">separator</replaceable></term>
1443       <listitem>
1444       <para>
1445       Use <replaceable class="parameter">separator</replaceable> as the record separator.
1446       This is equivalent to the <command>\pset recordsep</command> command.
1447       </para>
1448       </listitem>
1449     </varlistentry>
1450
1451
1452     <varlistentry>
1453       <term>-s, --single-step</term>
1454       <listitem>
1455       <para>
1456       Run in single-step mode. That means the user is prompted before each query
1457       is sent to the backend, with the option to cancel execution as well.
1458       Use this to debug scripts.
1459       </para>
1460       </listitem>
1461     </varlistentry>
1462
1463
1464     <varlistentry>
1465       <term>-S, --single-line</term>
1466       <listitem>
1467       <para>
1468       Runs in single-line mode where a newline terminates a query, as a semicolon does.
1469       </para>
1470
1471       <note>
1472       <para>
1473       This mode is provided for those who insist on it, but you are not necessarily
1474       encouraged to use it. In particular, if you mix <acronym>SQL</acronym> and
1475       meta-commands on a line the order of execution might not always be clear to
1476       the inexperienced user.
1477       </para>
1478       </note>
1479       </listitem>
1480     </varlistentry>
1481
1482
1483     <varlistentry>
1484       <term>-t, --tuples-only</term>
1485       <listitem>
1486       <para>
1487       Turn off printing of column names and result row count footers, etc.
1488       It is completely equivalent to the <command>\t</command> meta-command.
1489       </para>
1490       </listitem>
1491     </varlistentry>
1492
1493
1494     <varlistentry>
1495       <term>-T, --table-attr <replaceable class="parameter">table_options</replaceable></term>
1496       <listitem>
1497       <para>
1498       Allows you to specify options to be placed within the <acronym>HTML</acronym>
1499       <sgmltag>table</sgmltag> tag. See <command>\pset</command> for details.
1500       </para>
1501       </listitem>
1502     </varlistentry>
1503
1504
1505     <varlistentry>
1506       <term>-u</term>
1507       <listitem>
1508       <para>
1509       Makes <application>psql</application> prompt for the user name and password
1510       before connecting to the database.
1511       </para>
1512
1513       <para>
1514       This option is deprecated, as it is conceptually flawed. (Prompting for
1515       a non-default user name and prompting for a password because the
1516       backend requires it are really two different things.) You are encouraged
1517       to look at the <option>-U</option> and <option>-W</option> options instead.
1518       </para>
1519       </listitem>
1520     </varlistentry>
1521
1522
1523     <varlistentry>
1524       <term>-U, --username <replaceable class="parameter">username</replaceable></term>
1525       <listitem>
1526       <para>
1527       Connects to the database as the user <replaceable class="parameter">username</replaceable>
1528       instead of the default. (You must have permission to do so, of course.)
1529       </para>
1530       </listitem>
1531     </varlistentry>
1532
1533
1534     <varlistentry>
1535       <term>-v, --variable, --set <replaceable class="parameter">assignment</replaceable></term>
1536       <listitem>
1537       <para>
1538       Performs a variable assignment, like the <command>\set</command>
1539       internal command.  Note that you must separate name and value,
1540       if any, by an equal sign on the command line. To unset a
1541       variable, leave off the equal sign.  To just set a variable
1542       without a value, use the equal sign but leave off the value.
1543       These assignments are done during a very early stage of
1544       start-up, so variables reserved for internal purposes might get
1545       overwritten later.
1546       </para>
1547       </listitem>
1548     </varlistentry>
1549
1550
1551     <varlistentry>
1552       <term>-V, --version</term>
1553       <listitem>
1554       <para>
1555       Shows the <application>psql</application> version.
1556       </para>
1557       </listitem>
1558     </varlistentry>
1559
1560
1561     <varlistentry>
1562       <term>-W, --password</term>
1563       <listitem>
1564       <para>
1565       Requests that <application>psql</application> should prompt for a password
1566       before connecting to a database. This will remain set for the entire
1567       session, even if you change the database connection with the meta-command
1568       <command>\connect</command>.
1569       </para>
1570
1571       <para>
1572       As of version 7.0, <application>psql</application> automatically issues a
1573       password prompt whenever the backend requests password authentication.
1574       Because this is currently based on a hack, the automatic
1575       recognition might mysteriously fail, hence this option to force a prompt.
1576       If no password prompt is issued and the backend requires password authentication
1577       the connection attempt will fail.
1578       </para>
1579       </listitem>
1580     </varlistentry>
1581
1582
1583     <varlistentry>
1584       <term>-x, --expanded</term>
1585       <listitem>
1586       <para>
1587       Turns on extended row format mode. This is equivalent to the command
1588       <command>\x</command>.
1589       </para>
1590       </listitem>
1591     </varlistentry>
1592
1593
1594     <varlistentry>
1595       <term>-X, --no-psqlrc</term>
1596       <listitem>
1597       <para>
1598       Do not read the start-up file <filename>~/.psqlrc</filename>.
1599       </para>
1600       </listitem>
1601     </varlistentry>
1602
1603
1604     <varlistentry>
1605       <term>-?, --help</term>
1606       <listitem>
1607       <para>
1608       Shows help about <application>psql</application> command line arguments.
1609       </para>
1610       </listitem>
1611     </varlistentry>
1612
1613   </variablelist>
1614   </para>
1615
1616 </refsect1>
1617
1618
1619 <refsect1 id="R1-APP-PSQL-4">
1620     <refsect1info>
1621       <date>1998-09-27</date>
1622     </refsect1info>
1623
1624     <title>Advanced features</title>
1625
1626   <refsect2 id="APP-PSQL-variables">
1627     <title id="APP-PSQL-variables-title">Variables</title>
1628
1629     <para>
1630     <application>psql</application> provides variable substitution features
1631     similar to common Unix command shells. This feature is new and not very
1632     sophisticated, yet, but there are plans to expand it in the future.
1633     Variables are simply name/value
1634     pairs, where the value can be any string of any length. To set variables,
1635     use the <application>psql</application> meta-command <command>\set</command>:
1636 <programlisting>
1637 testdb=> <userinput>\set foo bar</userinput>
1638 </programlisting>
1639     sets the variable <quote>foo</quote> to the value <quote>bar</quote>. To retrieve
1640     the content of the variable, precede the name with a colon and use it
1641     as the argument of any slash command:
1642 <programlisting>
1643 testdb=> <userinput>\echo :foo</userinput>
1644 bar
1645 </programlisting>
1646     </para>
1647
1648     <note>
1649     <para>
1650     The arguments of <command>\set</command> are subject to the same substitution
1651     rules as with other commands. Thus you can construct interesting references
1652     such as <literal>\set :foo 'something'</literal> and get <quote>soft
1653     links</quote> or <quote>variable variables</quote> of <productname>Perl</productname>
1654     or <productname><acronym>PHP</acronym></productname> fame, respectively.
1655     Unfortunately (or fortunately?), there is no way to do anything useful
1656     with these constructs. On the
1657     other hand, <literal>\set bar :foo</literal> is a perfectly valid way to copy
1658     a variable.
1659     </para>
1660     </note>
1661
1662     <para>
1663     If you call <command>\set</command> without a second argument, the variable is simply
1664     set, but has no value. To unset (or delete) a variable, use the command
1665     <command>\unset</command>.
1666     </para>
1667
1668     <para>
1669     <application>psql</application>'s internal variable names can consist of
1670     letters, numbers, and underscores in any order and any number of them.
1671     A number of regular variables are treated specially by <application>psql</application>.
1672     They indicate certain option settings that can be changed at runtime
1673     by altering the value of the variable or represent some state of the application.
1674     Although you can use these
1675     variables for any other purpose, this is not recommended, as the
1676     program behavior might grow really strange really quickly.
1677     By convention, all specially treated variables consist of all upper-case letters
1678     (and possibly numbers and underscores). To ensure maximum compatibility in the
1679     future, avoid such variables.
1680     A list of all specially treated variables follows.
1681     <variablelist>
1682       <varlistentry>
1683         <term><envar>DBNAME</envar></term>
1684         <listitem>
1685         <para>
1686         The name of the database you are currently connected to. This is set every time
1687         you connect to a database (including program start-up), but can be unset.
1688         </para>
1689         </listitem>
1690       </varlistentry>
1691
1692       <varlistentry>
1693         <term><envar>ECHO</envar></term>
1694         <listitem>
1695         <para>
1696         If set to <quote><literal>all</literal></quote>, all lines entered or from a script
1697         are written to the standard output before they
1698         are parsed or executed. To specify this on program start-up, use the switch
1699         <option>-a</option>. If set to <quote><literal>queries</literal></quote>,
1700         <application>psql</application> merely prints all queries as they are sent to the
1701         backend. The option for this is <option>-e</option>.
1702         </para>
1703         </listitem>
1704       </varlistentry>
1705
1706       <varlistentry>
1707         <term><envar>ECHO_HIDDEN</envar></term>
1708         <listitem>
1709         <para>
1710         When this variable is set and a backslash command queries the database, the query
1711         is first shown. This way you can study the <productname>Postgres</productname>
1712         internals and provide similar functionality in your own programs. If you set the
1713         variable to the value <quote>noexec</quote>, the queries are just shown but are
1714         not actually sent to the backend and executed.
1715         </para>
1716         </listitem>
1717       </varlistentry>
1718
1719       <varlistentry>
1720         <term><envar>ENCODING</envar></term>
1721         <listitem>
1722         <para>
1723         The current client multibyte encoding. If you are not set up to use
1724         multibyte characters, this variable will always contain
1725         <quote>SQL_ASCII</quote>.
1726         </para>
1727         </listitem>
1728       </varlistentry>
1729
1730       <varlistentry>
1731         <term><envar>HISTCONTROL</envar></term>
1732         <listitem>
1733         <para>
1734          If  this variable is set  to  <literal>ignorespace</literal>, lines which begin with a
1735          space are not entered into the history list. If set to a value of
1736          <literal>ignoredups</literal>, lines matching the previous history line are not
1737          entered. A value of <literal>ignoreboth</literal> combines the two
1738          options.  If unset, or if set to any other value than those above, all lines read
1739          in interactive mode are saved on the history list.
1740         </para>
1741         <note>
1742         <para>
1743         This feature was shamelessly plagiarized from <application>bash</application>.
1744         </para>
1745         </note>
1746         </listitem>
1747       </varlistentry>
1748
1749       <varlistentry>
1750         <term><envar>HISTSIZE</envar></term>
1751         <listitem>
1752         <para>
1753         The number of commands to store in the command history.
1754         The default value is 500.
1755         </para>
1756         <note>
1757         <para>
1758         This feature was shamelessly plagiarized from <application>bash</application>.
1759         </para>
1760         </note>
1761         </listitem>
1762       </varlistentry>
1763
1764       <varlistentry>
1765         <term><envar>HOST</envar></term>
1766         <listitem>
1767         <para>
1768         The database server host you are currently connected to. This is set every time
1769         you connect to a database (including program start-up), but can be unset.
1770         </para>
1771         </listitem>
1772       </varlistentry>
1773
1774       <varlistentry>
1775         <term><envar>IGNOREEOF</envar></term>
1776         <listitem>
1777         <para>
1778          If unset, sending an EOF character (usually Control-D) to an interactive session of
1779          <application>psql</application> will terminate the application.
1780          If set to a numeric value, that many EOF characters are ignored before the application
1781          terminates. If the variable is set but has no numeric value, the default is 10.
1782         </para>
1783         <note>
1784         <para>
1785         This feature was shamelessly plagiarized from <application>bash</application>.
1786         </para>
1787         </note>
1788         </listitem>
1789       </varlistentry>
1790
1791       <varlistentry>
1792         <term><envar>LASTOID</envar></term>
1793         <listitem>
1794         <para>
1795         The value of the last affected oid, as returned from an <command>INSERT</command>
1796         or <command>lo_insert</command> command. This variable is only guaranteed to be
1797         valid until after the result of the next <acronym>SQL</acronym> command has been
1798         displayed.
1799         </para>
1800         </listitem>
1801       </varlistentry>
1802
1803       <varlistentry>
1804         <term><envar>LO_TRANSACTION</envar></term>
1805         <listitem>
1806         <para>
1807         If you use the <productname>Postgres</productname> large object
1808         interface to specially store data that does not fit into one tuple,
1809         all the operations must be contained in a transaction block. (See the
1810         documentation of the large object interface for more information.) Since
1811         <application>psql</application> has no way to tell if you already
1812         have a transaction in progress when you call one of its internal
1813         commands (<command>\lo_export</command>, <command>\lo_import</command>,
1814         <command>\lo_unlink</command>) it must take some arbitrary action. This
1815         action could either be to roll back any transaction that might already
1816         be in progress, or to commit any such transaction, or to do nothing at
1817         all. In the last case you must provide your own
1818         <command>BEGIN TRANSACTION</command>/<command>COMMIT</command> block or
1819         the results will be unpredictable (usually resulting in the desired
1820         action's not being performed in any case).
1821         </para>
1822
1823         <para>
1824         To choose what you want to do you set this variable to one of
1825         <quote>rollback</quote>, <quote>commit</quote>, or <quote>nothing</quote>.
1826         The default is to roll back the transaction. If you just want to load one
1827         or a few objects this is fine. However, if you intend to transfer many
1828         large objects, it might be advisable to provide one explicit transaction
1829         block around all commands.
1830         </para>
1831         </listitem>
1832       </varlistentry>
1833
1834       <varlistentry>
1835         <term><envar>ON_ERROR_STOP</envar></term>
1836         <listitem>
1837         <para>
1838         By default, if non-interactive scripts encounter an error, such as a
1839         malformed <acronym>SQL</acronym> query or internal meta-command,
1840         processing continues. This has been the traditional behavior of
1841         <application>psql</application> but it is sometimes not desirable. If this variable
1842         is set, script processing will immediately terminate. If the script was
1843         called from another script it will terminate in the same fashion.
1844         If the outermost script was not called from an interactive <application>psql</application>
1845         session but rather using the <option>-f</option> option, <application>psql</application>
1846         will return error code 3, to distinguish this case from fatal
1847         error conditions (error code 1).
1848         </para>
1849         </listitem>
1850       </varlistentry>
1851
1852       <varlistentry>
1853         <term><envar>PORT</envar></term>
1854         <listitem>
1855         <para>
1856         The database server port to which you are currently connected. This is set every time
1857         you connect to a database (including program start-up), but can be unset.
1858         </para>
1859         </listitem>
1860       </varlistentry>
1861
1862       <varlistentry>
1863         <term><envar>PROMPT1</envar>, <envar>PROMPT2</envar>, <envar>PROMPT3</envar></term>
1864         <listitem>
1865         <para>
1866         These specify what the prompt <application>psql</application> issues is
1867         supposed to look like. See
1868         <quote><xref linkend="APP-PSQL-prompting" endterm="APP-PSQL-prompting-title"></quote>
1869         below.
1870         </para>
1871         </listitem>
1872       </varlistentry>
1873
1874       <varlistentry>
1875         <term><envar>QUIET</envar></term>
1876         <listitem>
1877         <para>
1878         This variable is equivalent to the command line option <option>-q</option>.
1879         It is probably not too useful in interactive mode.
1880         </para>
1881         </listitem>
1882       </varlistentry>
1883
1884       <varlistentry>
1885         <term><envar>SINGLELINE</envar></term>
1886         <listitem>
1887         <para>
1888         This variable is set by the command line option <option>-S</option>. You
1889         can unset or reset it at run time.
1890         </para>
1891         </listitem>
1892       </varlistentry>
1893
1894       <varlistentry>
1895         <term><envar>SINGLESTEP</envar></term>
1896         <listitem>
1897         <para>
1898         This variable is equivalent to the command line option <option>-s</option>.
1899         </para>
1900         </listitem>
1901       </varlistentry>
1902
1903       <varlistentry>
1904         <term><envar>USER</envar></term>
1905         <listitem>
1906         <para>
1907         The database user you are currently connected as. This is set every time
1908         you connect to a database (including program start-up), but can be unset.
1909         </para>
1910         </listitem>
1911       </varlistentry>
1912
1913     </variablelist>
1914
1915     </para>
1916
1917   </refsect2>
1918
1919
1920   <refsect2 id="APP-PSQL-sql-interpol">
1921     <title id="APP-PSQL-sql-interpol-title"><acronym>SQL</acronym> Interpolation</title>
1922
1923     <para>
1924     An additional useful feature of <application>psql</application> variables
1925     is that you can substitute (<quote>interpolate</quote>) them into
1926     regular <acronym>SQL</acronym> statements. The syntax for this is again to prepend
1927     the variable name with a colon (<literal>:</literal>).
1928 <programlisting>
1929 testdb=> <userinput>\set foo 'my_table'</userinput>
1930 testdb=> <userinput>SELECT * FROM :foo;</userinput>
1931 </programlisting>
1932     would then query the table <literal>my_table</literal>. The value of the
1933     variable is copied literally, so it can even contain unbalanced quotes or
1934     backslash commands. You must make sure that it makes sense where you put it.
1935     Variable interpolation will not be performed into quoted <acronym>SQL</acronym>
1936     entities.
1937     </para>
1938
1939     <para>
1940     A popular application of this facility is to refer to the last inserted
1941     <acronym>OID</acronym> in subsequent statements to build a foreign key
1942     scenario.
1943     Another possible use of this mechanism is to copy the contents of a file
1944     into a field. First load the file into a variable and then proceed as above.
1945 <programlisting>
1946 testdb=> <userinput>\set content '\'' `cat my_file.txt` '\''</userinput>
1947 testdb=> <userinput>INSERT INTO my_table VALUES (:content);</userinput>
1948 </programlisting>
1949     One possible problem with this approach is that <filename>my_file.txt</filename>
1950     might contain single quotes. These need to be escaped so that
1951     they don't cause a syntax error when the third line is processed. This
1952     could be done with the program <application>sed</application>:
1953 <programlisting>
1954 testdb=> <userinput>\set content `sed -e "s/'/\\\\\\'/g" < my_file.txt`</userinput>
1955 </programlisting>
1956     Observe the correct number of backslashes (6)! You can resolve it this way: After
1957     <application>psql</application> has parsed this line, it passes
1958     <literal>sed -e "s/'/\\\'/g" < my_file.txt</literal> to the shell. The shell
1959     will do its own thing inside the double quotes and execute <filename>sed</filename>
1960     with the arguments <literal>-e</literal> and <literal>s/'/\\'/g</literal>.
1961     When <application>sed</application> parses this it will replace the two
1962     backslashes with a single one and then do the substitution. Perhaps at
1963     one point you thought it was great that all Unix commands use the same
1964     escape character. And this is ignoring the fact that you might have to
1965     escape all backslashes as well because <acronym>SQL</acronym> text constants
1966     are also subject to certain interpretations. In that case you might
1967     be better off preparing the file externally.
1968     </para>
1969
1970     <para>
1971     Since colons may legally appear in queries, the following rule applies: If the variable
1972     is not set, the character sequence <quote>colon+name</quote> is not changed. In any
1973     case you can escape a colon with a backslash to protect it from interpretation.
1974     (The colon syntax for variables is standard <acronym>SQL</acronym> for embedded
1975     query languages, such as <application>ecpg</application>. The colon syntax for
1976     array slices and type casts are <productname>Postgres</productname> extensions,
1977     hence the conflict.)
1978     </para>
1979
1980   </refsect2>
1981
1982
1983   <refsect2 id="APP-PSQL-prompting">
1984     <title id="APP-PSQL-prompting-title">Prompting</title>
1985
1986     <para>
1987     The prompts <application>psql</application> issues can be customized to
1988     your preference. The three variables <envar>PROMPT1</envar>, <envar>PROMPT2</envar>,
1989     and <envar>PROMPT3</envar> contain strings and special escape sequences
1990     that describe the appearance of the prompt. Prompt 1 is the normal prompt
1991     that is issued when <application>psql</application> requests a new query.
1992     Prompt 2 is issued when more input is expected during query input because
1993     the query was not terminated with a semicolon or a quote was not closed.
1994     Prompt 3 is issued when you run an <acronym>SQL</acronym> <command>COPY</command>
1995     command and you are expected to type in the tuples on the terminal.
1996     </para>
1997
1998     <para>
1999     The value of the respective prompt variable is printed literally, except where
2000     a percent sign (<quote>%</quote>) is encountered. Depending on the next
2001     character, certain other text is substituted instead. Defined substitutions are:
2002
2003     <variablelist>
2004       <varlistentry>
2005         <term><literal>%M</literal></term>
2006         <listitem>
2007          <para>
2008           The full hostname (with domain name) of the database server,
2009           or <literal>[local]</literal> if the connection is over a
2010           Unix domain socket, or
2011           <literal>[local:<replaceable>/dir/name</replaceable>]</literal>,
2012           if the Unix domain socket is not at the compiled in default
2013           location.
2014         </para>
2015        </listitem>
2016       </varlistentry>
2017
2018       <varlistentry>
2019         <term><literal>%m</literal></term>
2020         <listitem>
2021          <para>
2022           The hostname of the database server, truncated after the
2023           first dot, or <literal>[local]</literal> if the connection
2024           is over a Unix domain socket.
2025          </para>
2026         </listitem>
2027       </varlistentry>
2028
2029       <varlistentry>
2030         <term><literal>%&gt;</literal></term>
2031         <listitem><para>The port number at which the database server is listening.</para></listitem>
2032       </varlistentry>
2033
2034       <varlistentry>
2035         <term><literal>%n</literal></term>
2036         <listitem><para>The username you are connected as (not your local system
2037          user name).</para></listitem>
2038       </varlistentry>
2039
2040       <varlistentry>
2041         <term><literal>%/</literal></term>
2042         <listitem><para>The name of the current database.</para></listitem>
2043       </varlistentry>
2044
2045       <varlistentry>
2046         <term><literal>%~</literal></term>
2047         <listitem><para>Like <literal>%/</literal>, but the output is <quote>~</quote>
2048          (tilde) if the database is your default database.</para></listitem>
2049       </varlistentry>
2050
2051       <varlistentry>
2052         <term><literal>%#</literal></term>
2053         <listitem><para>If the current user is a database superuser, then a
2054          <quote>#</quote>, otherwise a <quote>&gt;</quote>.</para></listitem>
2055       </varlistentry>
2056
2057       <varlistentry>
2058         <term><literal>%R</literal></term>
2059         <listitem><para>
2060         In prompt 1 normally <quote>=</quote>, but <quote>^</quote> if in single-line
2061         mode, and <quote>!</quote> if the session is disconnected from the database
2062         (which can happen if <command>\connect</command> fails). In prompt 2 the
2063         sequence is replaced by <quote>-</quote>, <quote>*</quote>, a single quote,
2064         or a double quote, depending on whether <application>psql</application>
2065         expects more input because the query wasn't terminated yet, because you are
2066         inside a <literal>/* ... */</literal> comment, or because you are inside
2067         a quote. In prompt 3 the sequence doesn't resolve to anything.</para>
2068         </listitem>
2069       </varlistentry>
2070
2071       <varlistentry>
2072         <term><literal>%</literal><replaceable class="parameter">digits</replaceable></term>
2073         <listitem><para>
2074         If <replaceable class="parameter">digits</replaceable> starts with
2075         <literal>0x</literal> the rest of the characters are interpreted as a
2076         hexadecimal digit and the character with the corresponding code is
2077         substituted. If the first digit is <literal>0</literal> the characters are
2078         interpreted as on octal number and the corresponding character is
2079         substituted. Otherwise a decimal number is assumed.</para>
2080         </listitem>
2081       </varlistentry>
2082
2083       <varlistentry>
2084         <term><literal>%:</literal><replaceable class="parameter">name</replaceable><literal>:</literal></term>
2085         <listitem><para>
2086         The value of the <application>psql</application>, variable <replaceable
2087         class="parameter">name</replaceable>. See the section
2088         <quote><xref linkend="APP-PSQL-variables" endterm="APP-PSQL-variables-title"></quote>
2089         for details.</para>
2090         </listitem>
2091       </varlistentry>
2092
2093       <varlistentry>
2094         <term><literal>%`</literal><replaceable class="parameter">command</replaceable><literal>`</literal></term>
2095         <listitem><para>
2096         The output of <replaceable class="parameter">command</replaceable>, similar to
2097         ordinary <quote>back-tick</quote> substitution.</para>
2098         </listitem>
2099       </varlistentry>
2100
2101     </variablelist>
2102
2103     To insert a percent sign into your prompt, write <literal>%%</literal>. The
2104     default prompts are equivalent to <literal>'%/%R%# '</literal> for prompts 1
2105     and 2, and <literal>'&gt;&gt; '</literal> for prompt 3.
2106     </para>
2107
2108     <note>
2109     <para>
2110     This feature was shamelessly plagiarized from <application>tcsh</application>.
2111     </para>
2112     </note>
2113
2114    </refsect2>
2115
2116   <refsect2 id="APP-PSQL-MISC">
2117     <title id="APP-PSQL-MISC-title">Miscellaneous</title>
2118
2119     <para>
2120     <application>psql</application> returns 0 to the shell if it finished normally,
2121     1 if a fatal error of its own (out of memory, file not found) occurs, 2 if the
2122     connection to the backend went bad and the session is not interactive, and 3 if
2123     an error occurred in a script and the variable <envar>ON_ERROR_STOP</envar> was
2124     set.
2125     </para>
2126
2127     <para>
2128     Before starting up, <application>psql</application> attempts
2129     to read and execute commands from the file <filename>$HOME/.psqlrc</filename>. It
2130     could be used to set up the client or the server to taste (using the <command>\set
2131     </command> and <command>SET</command> commands).
2132     </para>
2133
2134   </refsect2>
2135
2136   <refsect2>
2137     <title><acronym>GNU</acronym> readline</title>
2138
2139     <para>
2140     <application>psql</application> supports the readline and history libraries for
2141     convenient line editing and retrieval. The command history is stored in a file
2142     named <filename>.psql_history</filename> in your home directory and is reloaded when
2143     <application>psql</application> starts up.
2144     Tab-completion is also supported, although
2145     the completion logic makes no claim to be an <acronym>SQL</acronym> parser.
2146     When available, <application>psql</application> is automatically built to use these
2147     features. If for some reason you do not like the tab completion, you can turn if off
2148     by putting this in a file named <filename>.inputrc</filename> in your
2149     home directory:
2150 <programlisting>
2151 $if psql
2152 set disable-completion on
2153 $endif
2154 </programlisting>
2155     (This is not a <application>psql</application> but a <application>readline</application>
2156     feature. Read its documentation for further details.)
2157     </para>
2158
2159     <para>
2160     If you have the readline library installed but <application>psql</application>
2161     does not seem to use it, you must make sure that <productname>Postgres</productname>'s
2162     top-level <filename>configure</filename> script finds it. <filename>configure</filename>
2163     needs to find both the library <filename>libreadline.a</filename>
2164     (or a shared library equivalent)
2165     <emphasis>and</emphasis> the header files <filename>readline.h</filename> and
2166     <filename>history.h</filename> (or <filename>readline/readline.h</filename> and
2167     <filename>readline/history.h</filename>) in appropriate directories. If
2168     you have the library and header files installed in an obscure place you
2169     must tell <filename>configure</filename> about them, for example:
2170 <programlisting>
2171 $ ./configure --with-includes=/opt/gnu/include --with-libs=/opt/gnu/lib  ...
2172 </programlisting>
2173     Then you have to recompile <application>psql</application> (not necessarily
2174     the entire code tree).
2175     </para>
2176
2177     <para>
2178     The <acronym>GNU</acronym> readline library can be obtained from the <acronym>GNU</acronym>
2179     project's <acronym>FTP</acronym> server at <ulink URL="ftp://ftp.gnu.org">ftp://ftp.gnu.org</ulink>.
2180     </para>
2181   </refsect2>
2182
2183
2184
2185 </refsect1>
2186
2187
2188 <refsect1 id="APP-PSQL-examples">
2189   <title id="APP-PSQL-examples-title">Examples</title>
2190
2191   <note>
2192   <para>
2193   This section only shows a few examples specific to <application>psql</application>.
2194   If you want to learn <acronym>SQL</acronym> or get familiar with
2195   <productname>Postgres</productname>, you might wish to read the Tutorial that
2196   is included in the distribution.
2197   </para>
2198   </note>
2199
2200   <para>
2201   The first example shows how to spread a query over several lines of input.
2202   Notice the changing prompt:
2203 <programlisting>
2204 testdb=> <userinput>CREATE TABLE my_table (</userinput>
2205 testdb(> <userinput> first integer not null default 0,</userinput>
2206 testdb(> <userinput> second text</userinput>
2207 testdb-> <userinput>);</userinput>
2208 CREATE
2209 </programlisting>
2210   Now look at the table definition again:
2211 <programlisting>
2212 testdb=> <userinput>\d my_table</userinput>
2213              Table "my_table"
2214  Attribute |  Type   |      Modifier
2215 -----------+---------+--------------------
2216  first     | integer | not null default 0
2217  second    | text    |
2218
2219 </programlisting>
2220   At this point you decide to change the prompt to something more
2221   interesting:
2222 <programlisting>
2223 testdb=> <userinput>\set PROMPT1 '%n@%m %~%R%# '</userinput>
2224 peter@localhost testdb=>
2225 </programlisting>
2226   Let's assume you have filled the table with data and want to take a look at it:
2227 <programlisting>
2228 peter@localhost testdb=> SELECT * FROM my_table;
2229  first | second
2230 -------+--------
2231      1 | one
2232      2 | two
2233      3 | three
2234      4 | four
2235 (4 rows)
2236
2237 </programlisting>
2238   You can make this table look differently by using the <command>\pset</command>
2239   command:
2240 <programlisting>
2241 peter@localhost testdb=> <userinput>\pset border 2</userinput>
2242 Border style is 2.
2243 peter@localhost testdb=> <userinput>SELECT * FROM my_table;</userinput>
2244 +-------+--------+
2245 | first | second |
2246 +-------+--------+
2247 |     1 | one    |
2248 |     2 | two    |
2249 |     3 | three  |
2250 |     4 | four   |
2251 +-------+--------+
2252 (4 rows)
2253
2254 peter@localhost testdb=> <userinput>\pset border 0</userinput>
2255 Border style is 0.
2256 peter@localhost testdb=> <userinput>SELECT * FROM my_table;</userinput>
2257 first second
2258 ----- ------
2259     1 one
2260     2 two
2261     3 three
2262     4 four
2263 (4 rows)
2264
2265 peter@localhost testdb=> <userinput>\pset border 1</userinput>
2266 Border style is 1.
2267 peter@localhost testdb=> <userinput>\pset format unaligned</userinput>
2268 Output format is unaligned.
2269 peter@localhost testdb=> <userinput>\pset fieldsep ","</userinput>
2270 Field separator is ",".
2271 peter@localhost testdb=> <userinput>\pset tuples_only</userinput>
2272 Showing only tuples.
2273 peter@localhost testdb=> <userinput>SELECT second, first FROM my_table;</userinput>
2274 one,1
2275 two,2
2276 three,3
2277 four,4
2278 </programlisting>
2279   Alternatively, use the short commands:
2280 <programlisting>
2281 peter@localhost testdb=> <userinput>\a \t \x</userinput>
2282 Output format is aligned.
2283 Tuples only is off.
2284 Expanded display is on.
2285 peter@localhost testdb=> <userinput>SELECT * FROM my_table;</userinput>
2286 -[ RECORD 1 ]-
2287 first  | 1
2288 second | one
2289 -[ RECORD 2 ]-
2290 first  | 2
2291 second | two
2292 -[ RECORD 3 ]-
2293 first  | 3
2294 second | three
2295 -[ RECORD 4 ]-
2296 first  | 4
2297 second | four
2298 </programlisting>
2299   </para>
2300
2301 </refsect1>
2302
2303
2304 <refsect1>
2305   <refsect1info>
2306     <date>1999-10-27</date>
2307   </refsect1info>
2308
2309   <title>Appendix</title>
2310
2311   <refsect2>
2312     <title>Bugs and Issues</title>
2313
2314     <itemizedlist>
2315       <listitem>
2316       <para>
2317       In some earlier life <application>psql</application> allowed the first
2318       argument to start directly after the (single-letter) command. For
2319       compatibility this is still supported to some extent but I am not
2320       going to explain the details here as this use is discouraged. But
2321       if you get strange messages, keep this in mind. For example
2322 <programlisting>
2323 testdb=> <userinput>\foo</userinput>
2324 Field separator is "oo",
2325 </programlisting>
2326       which is perhaps not what one would expect.
2327       </para>
2328       </listitem>
2329
2330       <listitem>
2331       <para>
2332       <application>psql</application> only works smoothly with servers of the
2333       same version. That does not mean other combinations will fail outright,
2334       but subtle and not-so-subtle problems might come up.
2335       </para>
2336       </listitem>
2337
2338       <listitem>
2339       <para>
2340       Pressing Control-C during a <quote>copy in</quote> (data sent to the
2341       server) doesn't show the most ideal of behaviors. If you get a message
2342       such as <quote>PQexec: you gotta get out of a COPY state yourself</quote>,
2343       simply reset the connection by entering <literal>\c - -</literal>.
2344       </para>
2345       </listitem>
2346
2347     </itemizedlist>
2348
2349   </refsect2>
2350
2351 </refsect1>
2352
2353 </refentry>
2354
2355 <!-- Keep this comment at the end of the file
2356 Local variables:
2357 mode: sgml
2358 sgml-omittag:nil
2359 sgml-shorttag:t
2360 sgml-minimize-attributes:nil
2361 sgml-always-quote-attributes:t
2362 sgml-indent-step:1
2363 sgml-indent-data:t
2364 sgml-parent-document:nil
2365 sgml-default-dtd-file:"../reference.ced"
2366 sgml-exposed-tags:nil
2367 sgml-local-catalogs:"/usr/lib/sgml/catalog"
2368 sgml-local-ecat-files:nil
2369 End:
2370 -->