libpq.sgml

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

<!--
$PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.199.2.2 2006/05/21 20:19:44 tgl Exp $
-->

 <chapter id="libpq">
  <title><application>libpq</application> - C Library</title>

  <indexterm zone="libpq">
   <primary>libpq</primary>
  </indexterm>

  <indexterm zone="libpq">
   <primary>C</primary>
  </indexterm>

  <para>
   <application>libpq</application> is the <acronym>C</acronym>
   application programmer's interface to <productname>PostgreSQL</>.
   <application>libpq</> is a set of library functions that allow
   client programs to pass queries to the <productname>PostgreSQL</>
   backend server and to receive the results of these queries.
  </para>

  <para>
   <application>libpq</> is also the underlying engine for several
   other <productname>PostgreSQL</> application interfaces, including
   those written for C++, Perl, Python, Tcl and <application>ECPG</>.
   So some aspects of <application>libpq</>'s behavior will be
   important to you if you use one of those packages.  In particular,
   <xref linkend="libpq-envars">,
   <xref linkend="libpq-pgpass"> and
   <xref linkend="libpq-ssl">
   describe behavior that is visible to the user of any application
   that uses <application>libpq</>.
  </para>

  <para>
   Some short programs are included at the end of this chapter (<xref linkend="libpq-example">) to show how
   to write programs that use <application>libpq</application>.  There are also several
   complete examples of <application>libpq</application> applications in the
   directory <filename>src/test/examples</filename> in the source code distribution.
  </para>

  <para>
   Client programs that use <application>libpq</application> must
   include the header file
   <filename>libpq-fe.h</filename><indexterm><primary>libpq-fe.h</></>
   and must link with the <application>libpq</application> library.
  </para>

 <sect1 id="libpq-connect">
  <title>Database Connection Control Functions</title>

  <para>
   The following functions deal with making a connection to a
   <productname>PostgreSQL</productname> backend server.  An
   application program can have several backend connections open at
   one time.  (One reason to do that is to access more than one
   database.)  Each connection is represented by a
   <structname>PGconn</><indexterm><primary>PGconn</></> object, which
   is obtained from the function <function>PQconnectdb</> or
   <function>PQsetdbLogin</>.  Note that these functions will always
   return a non-null object pointer, unless perhaps there is too
   little memory even to allocate the <structname>PGconn</> object.
   The <function>PQstatus</> function should be called to check
   whether a connection was successfully made before queries are sent
   via the connection object.

   <variablelist>
    <varlistentry>
     <term><function>PQconnectdb</function><indexterm><primary>PQconnectdb</></></term>
     <listitem>
      <para>
       Makes a new connection to the database server.
<synopsis>
PGconn *PQconnectdb(const char *conninfo);
</synopsis>
</para>

<para>
   This function opens a new database connection using the parameters taken
   from the string <literal>conninfo</literal>.  Unlike <function>PQsetdbLogin</> below,
   the parameter set can be extended without changing the function signature,
   so use of this function (or its nonblocking analogues <function>PQconnectStart</>
   and <function>PQconnectPoll</function>) is preferred for new application programming.
   </para>

   <para>
   The passed string
   can be empty to use all default parameters, or it can contain one or more
   parameter settings separated by whitespace.
   Each parameter setting is in the form <literal>keyword = value</literal>.
   Spaces around the equal sign are optional.
   To write an empty value or a value containing
   spaces, surround it with single quotes, e.g.,
   <literal>keyword = 'a value'</literal>.
   Single quotes and backslashes within the value must be escaped with a
   backslash, i.e., <literal>\'</literal> and <literal>\\</literal>.
   </para>

   <para>
   The currently recognized parameter key words are:

   <variablelist>
    <varlistentry>
     <term><literal>host</literal></term>
     <listitem>
     <para>
      Name of host to connect to.<indexterm><primary>host name</></>
      If this begins with a slash, it specifies Unix-domain
      communication rather than TCP/IP communication; the value is the
      name of the directory in which the socket file is stored.  The
      default behavior when <literal>host</literal> is not specified
      is to connect to a Unix-domain
      socket<indexterm><primary>Unix domain socket</></> in
      <filename>/tmp</filename> (or whatever socket directory was specified
      when <productname>PostgreSQL</> was built). On machines without
      Unix-domain sockets, the default is to connect to <literal>localhost</>.
     </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>hostaddr</literal></term>
     <listitem>
     <para>
      Numeric IP address of host to connect to.  This should be in the
      standard IPv4 address format, e.g., <literal>172.28.40.9</>.  If
      your machine supports IPv6, you can also use those addresses.
      TCP/IP communication is
      always used when a nonempty string is specified for this parameter.
     </para>
     <para>
      Using <literal>hostaddr</> instead of <literal>host</> allows the
      application to avoid a host name look-up, which may be important in
      applications with time constraints. However, Kerberos authentication
      requires the host name. The following therefore applies: If
      <literal>host</> is specified without <literal>hostaddr</>, a host name
      lookup occurs. If <literal>hostaddr</> is specified without
      <literal>host</>, the value for <literal>hostaddr</> gives the remote
      address. When Kerberos is used, a reverse name query occurs to obtain
      the host name for Kerberos. If both
      <literal>host</> and <literal>hostaddr</> are specified, the value for
      <literal>hostaddr</> gives the remote address; the value for
      <literal>host</> is ignored, unless Kerberos is used, in which case that
      value is used for Kerberos authentication. (Note that authentication is
      likely to fail if <application>libpq</application> is passed a host name
      that is not the name of the machine at <literal>hostaddr</>.)  Also,
      <literal>host</> rather than <literal>hostaddr</> is used to identify
      the connection in <filename>~/.pgpass</> (see
      <xref linkend="libpq-pgpass">).
     </para>
     <para>
      Without either a host name or host address,
      <application>libpq</application> will connect using a
      local Unix-domain socket; or on machines without Unix-domain
      sockets, it will attempt to connect to <literal>localhost</>.
     </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>port</literal></term>
     <listitem>
     <para>
      Port number to connect to at the server host, or socket file
      name extension for Unix-domain
      connections.<indexterm><primary>port</></>
     </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>dbname</literal></term>
     <listitem>
     <para>
      The database name.  Defaults to be the same as the user name.
     </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>user</literal></term> 
     <listitem>
     <para>
      <productname>PostgreSQL</productname> user name to connect as.
      Defaults to be the same as the operating system name of the user
      running the application.
     </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>password</literal></term>
     <listitem>
     <para>
      Password to be used if the server demands password authentication.
     </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>connect_timeout</literal></term>
     <listitem>
     <para>
      Maximum wait for connection, in seconds (write as a decimal integer
      string). Zero or not specified means wait indefinitely.  It is not
      recommended to use a timeout of less than 2 seconds.
     </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>options</literal></term>
     <listitem>
      <para>
       Command-line options to be sent to the server.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>tty</literal></term>
     <listitem>
     <para>
      Ignored (formerly, this specified where to send server debug output).
     </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>sslmode</literal></term>
     <listitem>
      <para>
       This option determines whether or with what priority an
       <acronym>SSL</> connection will be negotiated with the
       server. There are four modes: <literal>disable</> will attempt
       only an unencrypted <acronym>SSL</> connection;
       <literal>allow</> will negotiate, trying first a
       non-<acronym>SSL</> connection, then if that fails, trying an
       <acronym>SSL</> connection; <literal>prefer</> (the default)
       will negotiate, trying first an <acronym>SSL</> connection,
       then if that fails, trying a regular non-<acronym>SSL</>
       connection; <literal>require</> will try only an
       <acronym>SSL</> connection.
      </para>

      <para>
       If <productname>PostgreSQL</> is compiled without SSL support,
       using option <literal>require</> will cause an error, while
       options <literal>allow</> and <literal>prefer</> will be
       accepted but <application>libpq</> will not in fact attempt
       an <acronym>SSL</>
       connection.<indexterm><primary>SSL</><secondary
       sortas="libpq">with libpq</></indexterm>
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>requiressl</literal></term>
     <listitem>
      <para>
       This option is deprecated in favor of the <literal>sslmode</>
       setting.
      </para>

      <para>
       If set to 1, an <acronym>SSL</acronym> connection to the server
       is required (this is equivalent to <literal>sslmode</>
       <literal>require</>).  <application>libpq</> will then refuse
       to connect if the server does not accept an
       <acronym>SSL</acronym> connection.  If set to 0 (default),
       <application>libpq</> will negotiate the connection type with
       the server (equivalent to <literal>sslmode</>
       <literal>prefer</>).  This option is only available if
       <productname>PostgreSQL</> is compiled with SSL support.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>krbsrvname</literal></term>
     <listitem>
      <para>
       Kerberos service name to use when authenticating with Kerberos 5.
       This must match the service name specified in the server
       configuration for Kerberos authentication to succeed. (See also
       <xref linkend="kerberos-auth">.)
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>service</literal></term>
     <listitem>
     <para>
      Service name to use for additional parameters.  It specifies a service
      name in <filename>pg_service.conf</filename> that holds additional connection parameters.
      This allows applications to specify only a service name so connection parameters 
      can be centrally maintained. See <xref linkend="libpq-pgservice">.
     </para>
     </listitem>
    </varlistentry>
   </variablelist>

   If  any  parameter is unspecified, then the corresponding
   environment variable (see <xref linkend="libpq-envars">)
   is checked. If the  environment  variable is not set either,
   then the indicated built-in defaults are used.
   </para>
  </listitem>
 </varlistentry>

 <varlistentry>
  <term><function>PQsetdbLogin</function><indexterm><primary>PQsetdbLogin</></></term>
  <listitem>
   <para>
       Makes a new connection to the database server.
<synopsis>
PGconn *PQsetdbLogin(const char *pghost,
                     const char *pgport,
                     const char *pgoptions,
                     const char *pgtty,
                     const char *dbName,
                     const char *login,
                     const char *pwd);
</synopsis>
</para>

<para>
   This is the predecessor of <function>PQconnectdb</function> with a fixed
   set of parameters.  It has the same functionality except that the
   missing parameters will always take on default values.  Write <symbol>NULL</symbol> or an
   empty string for any one of the fixed parameters that is to be defaulted.
   </para>
  </listitem>
 </varlistentry>

 <varlistentry>
  <term><function>PQsetdb</function><indexterm><primary>PQsetdb</></></term>
  <listitem>
   <para>
   Makes a new connection to the database server.
<synopsis>
PGconn *PQsetdb(char *pghost,
                char *pgport,
                char *pgoptions,
                char *pgtty,
                char *dbName);
</synopsis>
</para>

<para>
   This is a macro that calls <function>PQsetdbLogin</function> with null pointers
   for the <parameter>login</> and <parameter>pwd</> parameters.  It is provided
   for backward compatibility with very old programs.
   </para>
  </listitem>
 </varlistentry>

 <varlistentry>
  <term><function>PQconnectStart</function><indexterm><primary>PQconnectStart</></></term>
  <term><function>PQconnectPoll</function><indexterm><primary>PQconnectPoll</></></term>
  <listitem>
  <para>
   <indexterm><primary>nonblocking connection</primary></indexterm>
   Make a connection to the database server in a nonblocking manner.
<synopsis>
PGconn *PQconnectStart(const char *conninfo);
</synopsis>