libpq.sgml

PostgreSQL7.4.6 for Linux

<!--
$Header: /cvsroot/pgsql/doc/src/sgml/libpq.sgml,v 1.141.2.1 2003/11/12 20:05:14 petere 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</productname>.  <application>libpq</application> is a set
   of library functions that allow client programs to pass queries to the
   <productname>PostgreSQL</productname> backend server and to receive the
   results of these queries.  <application>libpq</application> is also the
   underlying engine for several other <productname>PostgreSQL</productname>
   application interfaces, including <application>libpq++</application> (C++),
   <application>libpgtcl</application> (Tcl), <productname>Perl</productname>, and
   <application>ECPG</application>.  So some aspects of <application>libpq</>'s behavior will be
   important to you if you use one of those packages.
  </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>.
   (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>.)
   Spaces around the equal sign are optional.
   </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 is to connect to a Unix-domain socket in
      <filename>/tmp</filename>.<indexterm><primary>Unix domain
      socket</></>
     </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>$HOME/.pgpass</>.
     </para>
     <para>
      Without either a host name or host address,
      <application>libpq</application> will connect using a
      local Unix domain socket.
     </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.
     </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, and
       options <literal>allow</> and <literal>prefer</> will be
       tolerated but <application>libpq</> will be unable to negotiate
       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>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 
      <filename><replaceable>PREFIX</>/share/pg_service.conf.sample</> for
      information on how to set up the file.
     </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 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>
<synopsis>
PostgresPollingStatusType PQconnectPoll(PGconn *conn);
</synopsis>
</para>
<para>
   These two functions are used to open a connection to a database server such
   that your application's thread of execution is not blocked on remote I/O
   whilst doing so.
   The point of this approach is that the waits for I/O to complete can occur
   in the application's main loop, rather than down inside
   <function>PQconnectdb</>, and so the application can manage this
   operation in parallel with other activities.
  </para>
  <para>
   The database connection is made using the parameters taken from the string
   <literal>conninfo</literal>, passed to <function>PQconnectStart</function>. This string is in
   the same format as described above for <function>PQconnectdb</function>.
  </para>
  <para>
   Neither <function>PQconnectStart</function> nor <function>PQconnectPoll</function> will block, so long as a number of
   restrictions are met:
   <itemizedlist>
    <listitem>
     <para>
      The <literal>hostaddr</> and <literal>host</> parameters are used appropriately to ensure that
      name and reverse name queries are not made. See the documentation of
      these parameters under <function>PQconnectdb</function> above for details.
     </para>
    </listitem>

    <listitem>
     <para>
      If you call <function>PQtrace</function>, ensure that the stream object
      into which you trace will not block.
     </para>
    </listitem>