<!-- doc/src/sgml/libpq.sgml -->

<chapter id="libpq">
 <title><application>libpq</application> &mdash; 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.
 </para>

 <para>
  <application>libpq</application> is also the underlying engine for several
  other <productname>PostgreSQL</productname> application interfaces, including
  those written for C++, Perl, Python, Tcl and <application>ECPG</application>.
  So some aspects of <application>libpq</application>'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</application>.
 </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</primary></indexterm>
  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</structname><indexterm><primary>PGconn</primary></indexterm> object, which
   is obtained from the function <xref linkend="libpq-PQconnectdb"/>,
   <xref linkend="libpq-PQconnectdbParams"/>, or
   <xref linkend="libpq-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</structname> object.
   The <xref linkend="libpq-PQstatus"/> function should be called to check
   the return value for a successful connection before queries are sent
   via the connection object.

   <warning>
    <para>
     If untrusted users have access to a database that has not adopted a
     <link linkend="ddl-schemas-patterns">secure schema usage pattern</link>,
     begin each session by removing publicly-writable schemas from
     <varname>search_path</varname>.  One can set parameter key
     word <literal>options</literal> to
     value <literal>-csearch_path=</literal>.  Alternately, one can
     issue <literal>PQexec(<replaceable>conn</replaceable>, "SELECT
     pg_catalog.set_config('search_path', '', false)")</literal> after
     connecting.  This consideration is not specific
     to <application>libpq</application>; it applies to every interface for
     executing arbitrary SQL commands.
    </para>
   </warning>

   <warning>
    <para>
     On Unix, forking a process with open libpq connections can lead to
     unpredictable results because the parent and child processes share
     the same sockets and operating system resources.  For this reason,
     such usage is not recommended, though doing an <function>exec</function> from
     the child process to load a new