psql-ref.sgml

PostgreSQL 8.1.4的源码 适用于Linux下的开源数据库系统

<!--
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.154.2.1 2005/12/09 19:19:28 momjian Exp $
PostgreSQL documentation
-->

<refentry id="APP-PSQL">
  <refmeta>
    <refentrytitle id="app-psql-title"><application>psql</application></refentrytitle>
    <manvolnum>1</manvolnum>
    <refmiscinfo>Application</refmiscinfo>
  </refmeta>

  <refnamediv>
    <refname><application>psql</application></refname>
    <refpurpose>
      <productname>PostgreSQL</productname> interactive terminal
    </refpurpose>
  </refnamediv>

 <indexterm zone="app-psql">
  <primary>psql</primary>
 </indexterm>

 <refsynopsisdiv>
  <cmdsynopsis>
   <command>psql</command>
   <arg rep="repeat"><replaceable class="parameter">option</replaceable></arg>
   <arg><replaceable class="parameter">dbname</replaceable>
   <arg><replaceable class="parameter">username</replaceable></arg></arg>
  </cmdsynopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

    <para>
     <application>psql</application> is a terminal-based front-end to
     <productname>PostgreSQL</productname>. It enables you to type in
     queries interactively, issue them to
     <productname>PostgreSQL</productname>, and see the query results.
     Alternatively, input can be from a file. In addition, it provides a
     number of meta-commands and various shell-like features to
     facilitate writing scripts and automating a wide variety of tasks.
    </para>
 </refsect1>

 <refsect1 id="R1-APP-PSQL-3">
  <title>Options</title>

  <variablelist>
    <varlistentry>
      <term><option>-a</></term>
      <term><option>--echo-all</></term>
      <listitem>
      <para>
      Print all input lines to standard output as they are read. This is more
      useful for script processing rather than interactive mode. This is
      equivalent to setting the variable <varname>ECHO</varname> to
      <literal>all</literal>.
      </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><option>-A</></term>
      <term><option>--no-align</></term>
      <listitem>
      <para>
      Switches to unaligned output mode. (The default output mode is
      otherwise aligned.)
      </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><option>-c <replaceable class="parameter">command</replaceable></></term>
      <term><option>--command <replaceable class="parameter">command</replaceable></></term>
      <listitem>
      <para>
      Specifies that <application>psql</application> is to execute one
      command string, <replaceable class="parameter">command</replaceable>,
      and then exit. This is useful in shell scripts.
      </para>
      <para>
      <replaceable class="parameter">command</replaceable> must be either
      a command string that is completely parsable by the server (i.e.,
      it contains no <application>psql</application> specific features),
      or a single backslash command. Thus you cannot mix
      <acronym>SQL</acronym> and <application>psql</application>
      meta-commands. To achieve that, you could pipe the string into
      <application>psql</application>, like this: <literal>echo "\x \\
      select * from foo;" | psql</literal>.
      </para>
      <para>
       If the command string contains multiple SQL commands, they are
       processed in a single transaction, unless there are explicit
       BEGIN/COMMIT commands included in the string to divide it into
       multiple transactions.  This is different from the behavior when
       the same string is fed to <application>psql</application>'s standard input.
      </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><option>-d <replaceable class="parameter">dbname</replaceable></></term>
      <term><option>--dbname <replaceable class="parameter">dbname</replaceable></></term>
      <listitem>
      <para>
      Specifies the name of the database to connect to. This is
      equivalent to specifying <replaceable
      class="parameter">dbname</replaceable> as the first non-option
      argument on the command line.
      </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><option>-e</></term>
      <term><option>--echo-queries</></term>
      <listitem>
      <para>
      Copy all SQL commands sent to the server to standard output as well.
      This is equivalent
      to setting the variable <varname>ECHO</varname> to
      <literal>queries</literal>.
      </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><option>-E</></term>
      <term><option>--echo-hidden</></term>
      <listitem>
      <para>
      Echo the actual queries generated by <command>\d</command> and other backslash
      commands. You can use this to study <application>psql</application>'s
      internal operations. This is equivalent to
      setting the variable <varname>ECHO_HIDDEN</varname> from within
      <application>psql</application>.
      </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><option>-f <replaceable class="parameter">filename</replaceable></></term>
      <term><option>--file <replaceable class="parameter">filename</replaceable></></term>
      <listitem>
      <para>
      Use the file <replaceable class="parameter">filename</replaceable>
      as the source of commands instead of reading commands interactively.
      After the file is processed, <application>psql</application>
      terminates. This is in many ways equivalent to the internal
      command <command>\i</command>.
      </para>

      <para>
       If <replaceable>filename</replaceable> is <literal>-</literal>
       (hyphen), then standard input is read.
      </para>

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

    <varlistentry>
      <term><option>-F <replaceable class="parameter">separator</replaceable></></term>
      <term><option>--field-separator <replaceable class="parameter">separator</replaceable></></term>
      <listitem>
      <para>
      Use <replaceable class="parameter">separator</replaceable> as the
      field separator for unaligned output. This is equivalent to
      <command>\pset fieldsep</command> or <command>\f</command>.
      </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><option>-h <replaceable class="parameter">hostname</replaceable></></term>
      <term><option>--host <replaceable class="parameter">hostname</replaceable></></term>
      <listitem>
      <para>
      Specifies the host name of the machine on which the
      server is running. If the value begins
      with a slash, it is used as the directory for the Unix-domain
      socket.
      </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><option>-H</></term>
      <term><option>--html</></term>
      <listitem>
      <para>
      Turn on <acronym>HTML</acronym> tabular output. This is
      equivalent to <literal>\pset format html</literal> or the
      <command>\H</command> command.
      </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><option>-l</></term>
      <term><option>--list</></term>
      <listitem>
      <para>
      List all available databases, then exit. Other non-connection
      options are ignored. This is similar to the internal command
      <command>\list</command>.
      </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><option>-L <replaceable class="parameter">filename</replaceable></></term>
      <term><option>--log-file <replaceable class="parameter">filename</replaceable></></term>
      <listitem>
      <para>
       Write all query output into file <replaceable
       class="parameter">filename</replaceable>, in addition to the
       normal output destination.
      </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><option>-o <replaceable class="parameter">filename</replaceable></></term>
      <term><option>--output <replaceable class="parameter">filename</replaceable></></term>
      <listitem>
      <para>
      Put all query output into file <replaceable
      class="parameter">filename</replaceable>. This is equivalent to
      the command <command>\o</command>.
      </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><option>-p <replaceable class="parameter">port</replaceable></></term>
      <term><option>--port <replaceable class="parameter">port</replaceable></></term>
      <listitem>
      <para>
      Specifies the TCP port or the local Unix-domain
      socket file extension on which the server is listening for
      connections. Defaults to the value of the <envar>PGPORT</envar>
      environment variable or, if not set, to the port specified at
      compile time, usually 5432.
      </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><option>-P <replaceable class="parameter">assignment</replaceable></></term>
      <term><option>--pset <replaceable class="parameter">assignment</replaceable></></term>
      <listitem>
      <para>
      Allows you to specify printing options in the style of
      <command>\pset</command> on the command line. Note that here you
      have to separate name and value with an equal sign instead of a
      space. Thus to set the output format to LaTeX, you could write
      <literal>-P format=latex</literal>.
      </para>
      </listitem>
    </varlistentry>

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

    <varlistentry>
      <term><option>-R <replaceable class="parameter">separator</replaceable></></term>
      <term><option>--record-separator <replaceable class="parameter">separator</replaceable></></term>
      <listitem>
      <para>
      Use <replaceable class="parameter">separator</replaceable> as the
      record separator for unaligned output. This is equivalent to the
      <command>\pset recordsep</command> command.
      </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><option>-s</></term>
      <term><option>--single-step</></term>
      <listitem>
      <para>
      Run in single-step mode. That means the user is prompted before
      each command is sent to the server, with the option to cancel
      execution as well. Use this to debug scripts.
      </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><option>-S</></term>
      <term><option>--single-line</></term>
      <listitem>
      <para>
      Runs in single-line mode where a newline terminates an SQL command, as a
      semicolon does.
      </para>

      <note>
      <para>
      This mode is provided for those who insist on it, but you are not
      necessarily encouraged to use it. In particular, if you mix
      <acronym>SQL</acronym> and meta-commands on a line the order of
      execution might not always be clear to the inexperienced user.
      </para>
      </note>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><option>-t</></term>
      <term><option>--tuples-only</></term>
      <listitem>
      <para>
      Turn off printing of column names and result row count footers,
      etc. This is equivalent to the <command>\t</command> command.
      </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><option>-T <replaceable class="parameter">table_options</replaceable></></term>
      <term><option>--table-attr <replaceable class="parameter">table_options</replaceable></></term>
      <listitem>
      <para>
      Allows you to specify options to be placed within the
      <acronym>HTML</acronym> <sgmltag>table</sgmltag> tag. See