1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
|
<?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 <link linkend="package-case">case-sensitive</link>,
so you would write <code>(sql:PQconnectdb ...)</code>
when you need to call
<ulink url="&postgresql-doc;/libpq.html#LIBPQ-CONNECT"
><function>PQconnectdb()</function></ulink>.</para>
<simpara>When this module is present, &features-var;
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:</para>
<variablelist>
<varlistentry id="sql:pq-finish"><term><code>(sql:pq-finish
&conn-r;)</code></term>
<listitem><simpara><function>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>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>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 <code>PQfinish</code> and <code>PQclear</code>
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>
</section>
|
