psql-ref.sgml

postgresql8.3.4源码,开源数据库

      </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
      <command>\pset</command> for details.
      </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><option>-U <replaceable class="parameter">username</replaceable></></term>
      <term><option>--username <replaceable class="parameter">username</replaceable></></term>
      <listitem>
      <para>
      Connect to the database as the user <replaceable
      class="parameter">username</replaceable> instead of the default.
      (You must have permission to do so, of course.)
      </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><option>-v <replaceable class="parameter">assignment</replaceable></></term>
      <term><option>--set <replaceable class="parameter">assignment</replaceable></></term>
      <term><option>--variable <replaceable class="parameter">assignment</replaceable></></term>
      <listitem>
      <para>
      Perform a variable assignment, like the <command>\set</command>
      internal command. Note that you must separate name and value, if
      any, by an equal sign on the command line. To unset a variable,
      leave off the equal sign. To just set a variable without a value,
      use the equal sign but leave off the value. These assignments are
      done during a very early stage of start-up, so variables reserved
      for internal purposes might get overwritten later.
      </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><option>-V</></term>
      <term><option>--version</></term>
      <listitem>
      <para>
      Print the <application>psql</application> version and exit.
      </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><option>-W</></term>
      <term><option>--password</></term>
      <listitem>
      <para>
       Force <application>psql</application> to prompt for a
       password before connecting to a database.  
      </para>

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

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

    <varlistentry>
      <term><option>-x</></term>
      <term><option>--expanded</></term>
      <listitem>
      <para>
      Turn on the expanded table formatting mode. This is equivalent to the
      <command>\x</command> command.
      </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><option>-X,</></term>
      <term><option>--no-psqlrc</></term>
      <listitem>
      <para>
      Do not read the start-up file (neither the system-wide
      <filename>psqlrc</filename> file nor the user's
      <filename>~/.psqlrc</filename> file).
      </para>
      </listitem>
    </varlistentry>

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

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

    <varlistentry>
      <term><option>-?</></term>
      <term><option>--help</></term>
      <listitem>
      <para>
      Show help about <application>psql</application> command line
      arguments, and exit.
      </para>
      </listitem>
    </varlistentry>
  </variablelist>
 </refsect1>


 <refsect1>
  <title>Exit Status</title>

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


 <refsect1>
  <title>Usage</title>

  <refsect2 id="R2-APP-PSQL-connecting">
    <title>Connecting To A Database</title>

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

    <para>
    When the defaults aren't quite right, you can save yourself
    some typing by setting the environment variables
    <envar>PGDATABASE</envar>, <envar>PGHOST</envar>,
    <envar>PGPORT</envar> and/or <envar>PGUSER</envar> to appropriate
    values. (For additional environment variables, see <xref
    linkend="libpq-envars">.) It is also convenient to have a
    <filename>~/.pgpass</> file to avoid regularly having to type in
    passwords. See <xref linkend="libpq-pgpass"> for more information.
    </para>

    <para>
     An alternative way to specify connection parameters is in a
     <parameter>conninfo</parameter> string, which is used instead of a 
     database name. This mechanism give you very wide control over the 
     connection. For example:
<programlisting>
$ <userinput>psql "service=myservice sslmode=require"</userinput>
</programlisting>
     This way you can also use LDAP for connection parameter lookup as
     described in <xref linkend="libpq-ldap">.
     See <xref linkend="libpq-connect"> for more information on all the
     available connection options.
    </para>

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

  <refsect2 id="R2-APP-PSQL-4">
    <title>Entering SQL Commands</title>

    <para>
    In normal operation, <application>psql</application> provides a
    prompt with the name of the database to which
    <application>psql</application> is currently connected, followed by
    the string <literal>=&gt;</literal>. For example:
<programlisting>
$ <userinput>psql testdb</userinput>
Welcome to psql &version;, the PostgreSQL interactive terminal.

Type:  \copyright for distribution terms
       \h for help with SQL commands
       \? for help with psql commands
       \g or terminate with semicolon to execute query
       \q to quit

testdb=&gt;
</programlisting>
    </para>

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

    <para>
    Whenever a command is executed, <application>psql</application> also polls
    for asynchronous notification events generated by
    <xref linkend="SQL-LISTEN" endterm="SQL-LISTEN-title"> and
    <xref linkend="SQL-NOTIFY" endterm="SQL-NOTIFY-title">.
    </para>
  </refsect2>

  <refsect2>
    <title>Meta-Commands</title>

    <para>
    Anything you enter in <application>psql</application> that begins
    with an unquoted backslash is a <application>psql</application>
    meta-command that is processed by <application>psql</application>
    itself. These commands help make
    <application>psql</application> more useful for administration or
    scripting. Meta-commands are more commonly called slash or backslash
    commands.
    </para>

    <para>
    The format of a <application>psql</application> command is the backslash,
    followed immediately by a command verb, then any arguments. The arguments
    are separated from the command verb and each other by any number of
    whitespace characters.
    </para>

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

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

    <para>
    Arguments that are enclosed in backquotes (<literal>`</literal>)
    are taken as a command line that is passed to the shell. The
    output of the command (with any trailing newline removed) is taken
    as the argument value. The above escape sequences also apply in
    backquotes.
    </para>

    <para>
    Some commands take an <acronym>SQL</acronym> identifier (such as a
    table name) as argument. These arguments follow the syntax rules
    of <acronym>SQL</acronym>: Unquoted letters are forced to
    lowercase, while double quotes (<literal>"</>) protect letters
    from case conversion and allow incorporation of whitespace into
    the identifier.  Within double quotes, paired double quotes reduce
    to a single double quote in the resulting name.  For example,
    <literal>FOO"BAR"BAZ</> is interpreted as <literal>fooBARbaz</>,
    and <literal>"A weird"" name"</> becomes <literal>A weird"
    name</>.
    </para>

    <para>
    Parsing for arguments stops when another unquoted backslash occurs.
    This is taken as the beginning of a new meta-command. The special
    sequence <literal>\\</literal> (two backslashes) marks the end of
    arguments and continues parsing <acronym>SQL</acronym> commands, if
    any. That way <acronym>SQL</acronym> and
    <application>psql</application> commands can be freely mixed on a
    line. But in any case, the arguments of a meta-command cannot
    continue beyond the end of the line.
    </para>

    <para>
    The following meta-commands are defined:

    <variablelist>
      <varlistentry>
        <term><literal>\a</literal></term>