<?xml version="1.0" encoding="UTF-8"?>

<section id="postgresql"><title>PostgreSQL Database Access</title>

<para>This package offers an &ffi-pac;-based interface to
 &postgresql-link;.</para>
<para>The package <quote role="package">SQL</quote>
 (nicknamed <quote role="package">POSTGRES</quote>
 and <quote role="package">POSTGRESQL</quote>) is &case-sensitive-k;,
 so you would write <code>(sql:PQconnectdb ...)</code>
 when you need to call <function role="pq">PQconnectdb</function>.</para>

<simpara>When this module is present, &features-my;
 contains the symbol <constant>:POSTGRESQL</constant>.</simpara>

<para>See <filename role="clisp-cvs">modules/postgresql/test.tst</filename>
 for sample usage.</para>

<para>Additionally, some higher level functionality is available (defined
 in <filename role="clisp-cvs">modules/postgresql/sql.lisp</filename>):</para>

<variablelist>
<varlistentry id="sql:pq-finish"><term><code>(sql:pq-finish
   &conn-r;)</code></term>
 <listitem><simpara><function role="pq">PQfinish</function> the &conn-r;
   and mark it as invalid</simpara></listitem></varlistentry>
<varlistentry id="sql:pq-clear"><term><code>(sql:pq-clear
   &res-r;)</code></term>
 <listitem><simpara><function role="pq">PQclear</function> the &res-r;
   and mark it as invalid</simpara></listitem></varlistentry>
<varlistentry><term><code>(sql:sql-error &conn-r; &res-r; &fmt-r;
   &rest-amp; &args-r;)</code></term>
 <listitem><simpara>finalize &conn-r; and &res-r; and &signal; an
   appropriate &error-t;</simpara></listitem></varlistentry>
<varlistentry id="sql:sql-connect"><term><code>(sql:sql-connect
   &key-amp; host port options tty name login password)</code></term>
 <listitem><simpara>call <function role="pq">PQsetdbLogin</function> and
   return the &conn-r;</simpara></listitem></varlistentry>
<varlistentry id="sql:with-sql-connection"><term><code>(sql:with-sql-connection
   (&var-r; &rest-amp; &option-r;s &key-amp; &log-r; &allow-other-keys-amp;)
   &body-amp; &body-r;)</code></term>
 <listitem><procedure><step><simpara>bind <varname>*sql-log*</varname>
     to the &log-r; argument</simpara></step>
   <step><simpara>call <function>sql:sql-connect</function> on
     &option-r;s and bind &var-r; to the result</simpara></step>
   <step><simpara>execute &body-r;</simpara></step>
   <step><simpara>call <function>sql:pq-finish</function> on
     &var-r;</simpara></step></procedure></listitem></varlistentry>
<varlistentry><term><code>(sql:sql-transaction &conn-r; &command-r;
   &status-r; &optional-amp; (clear-p &t;))</code></term>
 <listitem><simpara>execute the &command-r; via &conn-r;;
   if the status does not match &status-r;, &err-sig;;
   if <replaceable>clear-p</replaceable> is
   non-&nil; <function>sql:pq-clear</function> the &res-r;;
   otherwise return it</simpara></listitem></varlistentry>
<varlistentry><term><code>(sql:with-sql-transaction (&res-r; &conn-r;
   &command-r; status) &body-amp; &body-r;)</code></term>
 <listitem><simpara>execure the &body-r; on the &res-r; of &command-r;,
   then <function>sql:pq-clear</function> the &res-r;
</simpara></listitem></varlistentry>
<varlistentry id="sql:sql-login"><term><code>sql:*sql-login*</code></term>
 <listitem><simpara>the default <replaceable>login</replaceable>
   argument to <function>sql:sql-connect</function>
   (initially set to <literal role="data">"postgres"</literal>)
</simpara></listitem></varlistentry>
<varlistentry id="sql:sql-password"><term><code>sql:*sql-password*</code></term>
 <listitem><simpara>the default &pass-r;
   argument to <function>sql:sql-connect</function>
   (initially set to <literal role="data">"postgres"</literal>)
</simpara></listitem></varlistentry>
<varlistentry id="sql:sql-log"><term><code>sql:*sql-log*</code></term>
 <listitem><simpara>when non-&nil;, should be a &stream-t;;
   <function>sql:sql-connect</function>
   and <function>sql:sql-transaction</function>
   will write to it (initially set to &nil;)
</simpara></listitem></varlistentry></variablelist>

<warning><para>Since <function role="pq">PQfinish</function>
  and <function role="pq">PQclear</function>
  cannot be called on the same pointer twice, one needs to track their
  validity (<function>sql:sql-connect</function>
  and <function>sql:sql-transaction</function> take care of that).
  See <xref linkend="ex-dffi-validity"/>.</para></warning>

<para>For <function role="pq">PQtrace</function>, see
 <xref linkend="stdio"/>.</para>

</section>
