doc/cl-postgres.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
   2 <html xmlns="http://www.w3.org/1999/xhtml">
   3
   4   <head>
   5     <title>CL-postgres reference manual</title>
   6     <link rel="stylesheet" type="text/css" href="style.css"/>
   7     <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
   8   </head>
   9
  10   <body>
  11
  12     <h1>CL-postgres reference manual</h1>
  13
  14     <p>The CL-postgres module implements a rather low-level interface
  15     for communicating with a <a
  16     href="http://postgresql.org">PostgreSQL</a> database server. It is
  17     part of the <a href="index.html">Postmodern</a> library, but can
  18     be used separately.</p>
  19
  20     <h2>Contents</h2>
  21
  22     <ol>
  23       <li><a href="#connecting">Connecting</a></li>
  24       <li><a href="#querying">Querying</a></li>
  25       <li><a href="#reading">Reading values</a></li>
  26       <li><a href="#row-readers">Row readers</a></li>
  27       <li><a href="#bulk-copying">Bulk Copying</a></li>
  28       <li><a href="#conditions">Conditions</a></li>
  29       <li><a href="#index">Symbol-index</a></li>
  30     </ol>
  31
  32     <h2><a name="connecting">Connecting</a></h2>
  33
  34     <p class="def">
  35       <span>class</span>
  36       <a name="database-connection"></a>
  37       database-connection
  38     </p>
  39
  40     <p class="desc">Objects of this type represent database
  41     connections.</p>
  42
  43     <p class="def">
  44       <span>function</span>
  45       <a name="open-database"></a>
  46       open-database (database user password host &amp;optional (port 5432) (use-ssl :no))
  47       <br/>&#8594; database-connection
  48     </p>
  49
  50     <p class="desc">Create and open a connection for the specified
  51     server, database, and user. <code>use-ssl</code> may be
  52     <code>:no</code>, <code>:yes</code>, or <code>:try</code>, where
  53     <code>:try</code> means 'if the server supports it'. When it is
  54     anything but <code>:no</code>, you must have the <a
  55     href="http://common-lisp.net/project/cl-plus-ssl/">CL+SSL</a>
  56     package loaded to initiate the connection.</p>
  57
  58     <p class="desc">On SBCL and Clozure CL, the value
  59     <code>:unix</code> may be passed for <code>host</code>, in order
  60     to connect using a Unix domain socket instead of a TCP socket.</p>
  61
  62     <p class="def">
  63       <span>function</span>
  64       <a name="close-database"></a>
  65       close-database (database-connection)
  66     </p>
  67
  68     <p class="desc">Close a database connection. It is advisable to
  69     call this on connections when you are done with them. Otherwise
  70     the open socket will stick around until it is garbage collected,
  71     and no one will tell the database server that we are done
  72     with it.</p>
  73
  74     <p class="def">
  75       <span>function</span>
  76       <a name="reopen-database"></a>
  77       reopen-database (database-connection)
  78     </p>
  79
  80     <p class="desc">Re-establish a database connection for a
  81     previously closed connection object. (Calling this on a connection
  82     that is still open is harmless.)</p>
  83
  84     <p class="def">
  85       <span>function</span>
  86       <a name="database-open-p"></a>
  87       database-open-p (database-connection)
  88       <br/>&#8594; boolean
  89     </p>
  90
  91     <p class="desc">Test whether a database connection is still
  92     open.</p>
  93
  94     <p class="def">
  95       <span>method</span>
  96       <a name="connection-meta"></a>
  97       connection-meta (database-connection)
  98       <br/>&#8594; hash-table
  99     </p>
 100
 101     <p class="desc">This method provides access to a hash table that
 102     is associated with the current database connection. When the
 103     connection is closed and re-opened this hash table is reset. The
 104     most obvious use for this is for storing information about the
 105     prepared statements that have been parsed for this connection.</p>
 106
 107     <p class="def">
 108       <span>method</span>
 109       <a name="connection-parameters"></a>
 110       connection-parameters (database-connection)
 111       <br/>&#8594; hash-table
 112     </p>
 113
 114     <p class="desc">This method returns a mapping (string to string)
 115     containing all the <a
 116     href="http://www.postgresql.org/docs/current/static/runtime-config.html">configuration
 117     parameters</a> for the connection.</p>
 118
 119     <p class="def">
 120       <span>variable</span>
 121       <a name="*unix-socket-dir*"></a>
 122       *unix-socket-dir*
 123     </p>
 124
 125     <p class="desc">On SBCL, when using the <code>:unix</code> keyword
 126     as host argument when creating a connection, this variable
 127     determines the directory in which CL-Postgres will look for the
 128     socket file.</p>
 129
 130     <p class="def">
 131       <span>variable</span>
 132       <a name="*ssl-certificate-file*"></a>
 133       *ssl-certificate-file*<br/>
 134       <span>variable</span>
 135       <a name="*ssl-key-file*"></a>
 136       *ssl-key-file*
 137     </p>
 138
 139     <p class="desc">When using SSL (see <a
 140     href="#open-database"><code>open-database</code></a>), these can
 141     be used to provide client key and certificate files. They can be
 142     either <code>NIL</code>, for no file, or a pathname.</p>
 143
 144     <p class="def">
 145       <span>function</span>
 146       <a name="wait-for-notification"></a>
 147       wait-for-notification (database-connection)
 148     </p>
 149
 150     <p class="desc">This function blocks until a notification is
 151       received on the connection.  The PostgreSQL <code>LISTEN</code>
 152       command must be used to enable listening for notifications.</p>
 153
 154     <h2><a name="querying">Querying</a></h2>
 155
 156     <p class="def">
 157       <span>function</span>
 158       <a name="exec-query"></a>
 159       exec-query (database-connection query &amp;optional (row-reader '<a href="#ignore-row-reader"><code>ignore-row-reader</code></a>))
 160       <br/>&#8594; result
 161     </p>
 162
 163     <p class="desc">Sends the given query to the given connection, and
 164     interprets the results (if there are any) with the given <a
 165     href="#reading">row-reader</a>. If the database returns
 166     information about the amount of rows affected, this is returned as
 167     a second value.</p>
 168
 169     <p class="def">
 170       <span>function</span>
 171       <a name="prepare-query"></a>
 172       prepare-query (database-connection name query)
 173     </p>
 174
 175     <p class="desc">Parse and plan the given query, and store it under
 176     the given name. Note that prepared statements are per-connection,
 177     so they can only be executed through the same connection that
 178     prepared them.</p>
 179
 180     <p class="def">
 181       <span>function</span>
 182       <a name="exec-prepared"></a>
 183       exec-prepared (database-connection name parameters &amp;optional (row-reader '<a href="#ignore-row-reader"><code>ignore-row-reader</code></a>))
 184       <br/>&#8594; result
 185     </p>
 186
 187     <p class="desc">Execute the prepared statement by the given name.
 188     Parameters should be given as a list. Each value in this list
 189     should be of a type that <a
 190     href="#to-sql-string"><code>to-sql-string</code></a> has been
 191     specialised on. (Byte arrays will be passed in their binary form,
 192     without being put through <a
 193     href="#to-sql-string"><code>to-sql-string</code></a>.) The result
 194     of the executing the statement, if any, is interpreted by the
 195     given <a href="#row-readers">row reader</a>, and returned. Again,
 196     the number or affected rows is optionally returned as a second
 197     value.</p>
 198
 199     <p class="def">
 200       <span>function</span>
 201       <a name="unprepare-query"></a>
 202       unprepare-query (database-connection name)
 203     </p>
 204
 205     <p class="desc">Close the prepared statement by the given name.
 206     This will free resources and allow the name to be associated with
 207     a new prepared query.</p>
 208
 209     <p class="def">
 210       <span>method</span>
 211       <a name="to-sql-string"></a>
 212       to-sql-string (value)
 213       <br/>&#8594; (values string needs-escaping)
 214     </p>
 215
 216     <p class="desc">Convert a Lisp value to its textual
 217     <em>unescaped</em> SQL representation. Returns a second value
 218     indicating whether this value should be escaped if it is to be put
 219     directly into a query.</p>
 220
 221     <p class="desc">You can define <code>to-sql-string</code> methods
 222     for your own datatypes if you want to be able to pass them to <a
 223     href="#exec-prepared"><code>exec-prepared</code></a>. When a
 224     non-<code>NIL</code> second value is returned, this may be
 225     <code>T</code> to indicate that the first value should simply be
 226     escaped as a string, or a second string providing a type prefix
 227     for the value. (This is used by <a
 228     href="s-sql.html">S-SQL</a>.)</p>
 229
 230     <p class="def">
 231       <span>variable</span>
 232       <a name="*silently-truncate-rationals*"></a>
 233       *silently-truncate-rationals*
 234     </p>
 235
 236     <p class="desc">When a rational number is passed into a query (as
 237     per <a href="#to-sql-string"><code>to-sql-string</code></a>), but
 238     it can not be expressed within 38 decimal digits (for example
 239     <code>1/3</code>), it will be truncated, and lose some precision.
 240     Set this variable to <code>nil</code> to suppress that behaviour
 241     and raise an error instead.</p>
 242
 243     <p class="def">
 244       <span>variable</span>
 245       <a name="*query-log*"></a>
 246       *query-log*
 247     </p>
 248
 249     <p class="desc">When debugging, it can be helpful to inspect the
 250     queries that are being sent to the database. Set this variable to
 251     an output stream value (<code>*standard-output*</code>, for
 252     example) to have CL-postgres log every query it makes.</p>
 253
 254     <p class="def">
 255       <span>variable</span>
 256       <a name="*query-callback*"></a>
 257       *query-callback*
 258     </p>
 259
 260     <p class="desc">
 261       When profiling or debugging,
 262       the <a href="#*query-log*"><code>*query-log*</code></a> may not
 263       give enough information, or reparsing its output may not be
 264       feasible.  This variable may be set to a designator of function
 265       taking two arguments.  This function will be then called after
 266       every query, and receive query string and internal time units
 267       (as in <code>(CL:GET-INTERNAL-REAL-TIME)</code>) spent in query
 268       as its arguments.
 269     </p>
 270
 271     <p class="desc">
 272       Default value of this variable
 273       is <a href="#log-query"><code>'LOG-QUERY</code></a>, which takes
 274       care of <a href="#*query-log*"><code>*QUERY-LOG*</code></a>
 275       processing.  If you provide custom query callback and wish to
 276       keep <a href="#*query-log*"><code>*QUERY-LOG*</code></a>
 277       functionality, you will have to
 278       call <a href="#log-query"><code>LOG-QUERY</code></a> from your
 279       callback function
 280     </p>
 281
 282     <p class="def">
 283       <span>function</span>
 284       <a name="log-query"></a>
 285       log-query (query internal-time)
 286     </p>
 287
 288     <p class="desc">
 289       This function is default value
 290       of <a href="#*query-callback*"><code>*QUERY-CALLBACK*</code></a>
 291       and logs queries
 292       to <a href="#*query-log*"><code>*QUERY-LOG*</code></a> if it is
 293       not <code>NIL</code>.
 294     </p>
 295
 296     <h2><a name="reading">Reading values</a></h2>
 297
 298     <p>CL-postgres knows how to convert commonly used PostgreSQL data
 299     types to Lisp values. This table shows the mapping:</p>
 300
 301     <table>
 302       <thead>
 303         <tr><th>PostgreSQL</th><th>Lisp</th></tr>
 304       </thead>
 305       <tbody>
 306         <tr><td>smallint</td><td>integer</td></tr>
 307         <tr><td>integer</td><td>integer</td></tr>
 308         <tr><td>bigint</td><td>integer</td></tr>
 309         <tr><td>numeric</td><td>ratio</td></tr>
 310         <tr><td>real</td><td>float</td></tr>
 311         <tr><td>double precision</td><td>double-float</td></tr>
 312         <tr><td>boolean</td><td>boolean</td></tr>
 313         <tr><td>varchar</td><td>string</td></tr>
 314         <tr><td>text</td><td>string</td></tr>
 315         <tr><td>bytea</td><td>(vector (unsigned-byte 8))</td></tr>
 316       </tbody>
 317     </table>
 318
 319     <p>The mapping from PostgreSQL types (identified by OID numbers)
 320     to the functions that interpret them is kept in so-called SQL
 321     readtables. All types for which no reader is defined will be
 322     returned as string values containing their PostgreSQL
 323     representation.</p>
 324
 325     <p class="def">
 326       <span>variable</span>
 327       <a name="*sql-readtable*"></a>
 328       *sql-readtable*
 329     </p>
 330
 331     <p class="desc">This variable is used to choose the current
 332     readtable. For simple use, you will not have to touch this, but it
 333     is possible that code within a Lisp image requires different
 334     readers in different situations, in which case you can create
 335     separate read tables.</p>
 336
 337     <p class="def">
 338       <span>function</span>
 339       <a name="copy-sql-readtable"></a>
 340       copy-sql-readtable (table)
 341       <br/>&#8594; readtable
 342     </p>
 343
 344     <p class="desc">Copies a given readtable.</p>
 345
 346     <p class="def">
 347       <span>function</span>
 348       <a name="default-sql-readtable"></a>
 349       default-sql-readtable ()
 350       <br/>&#8594; readtable
 351     </p>
 352
 353     <p class="desc">Returns the default readtable, containing only the
 354     readers defined by CL-postgres itself.</p>
 355
 356     <p class="def">
 357       <span>function</span>
 358       <a name="set-sql-reader"></a>
 359       set-sql-reader (oid function &amp;key table binary-p)
 360     </p>
 361
 362     <p class="desc">Define a new reader for a given type.
 363     <code>table</code> defaults to <a
 364     href="#*sql-readtable"><code>*sql-readtable*</code></a>. The
 365     reader function should take a single argument, a string, and
 366     transform that into some kind of equivalent Lisp value. When
 367     <code>binary-p</code> is true, the reader function is supposed to
 368     directly read the binary representation of the value. In most
 369     cases this is not recommended, but if you want to use it: provide
 370     a function that takes a binary input stream and an integer (the
 371     size of the value, in bytes), and reads the value from that
 372     stream. Note that reading less or more bytes than the given size
 373     will horribly break your connection.</p>
 374
 375     <p class="def">
 376       <span>function</span>
 377       <a name="set-sql-datetime-readers"></a>
 378       set-sql-datetime-readers (&amp;key date timestamp timestamp-with-timezone time interval table)
 379     </p>
 380
 381     <p class="desc">Since there is no widely recognised standard way
 382     of representing dates and times in Common Lisp, and reading these
 383     from string representation is clunky and slow, this function
 384     provides a way to easily plug in binary readers for the
 385     <code>date</code>, <code>time</code>, <code>timestamp</code>, and
 386     <code>interval</code> types. It should be given functions with the
 387     following signatures:</p>
 388
 389     <dl class="desc">
 390       <dt><code>:date (days)</code></dt>
 391       <dd>Where <code>days</code> is the amount of days since January
 392       1st, 2000.</dd>
 393       <dt><code>:timestamp (useconds)</code></dt>
 394       <dd>Timestamps have a microsecond resolution. Again, the zero
 395       point is the start of the year 2000, UTC.</dd>
 396       <dt><code>:timestamp-with-timezone</code></dt>
 397       <dd>Like <code>:timestamp</code>, but for values of the
 398       'timestamp with time zone' type (which PostgreSQL internally
 399       stores exactly the same as regular timestamps).</dd>
 400       <dt><code>:time (useconds)</code></dt>
 401       <dd>Refers to a time of day, counting from midnight.</dd>
 402       <dt><code>:interval (months days useconds)</code></dt>
 403       <dd>An interval is represented as several separate components.
 404       The reason that days and microseconds are separated is that you
 405       might want to take leap seconds into account.</dd>
 406     </dl>
 407
 408     <h2><a name="row-readers"></a>Row readers</h2>
 409
 410     <p>Row readers are a way to read and group the results of queries.
 411     Roughly, they are functions that perform the iteration over the
 412     rows and cells in the result, and do <em>something</em> with the
 413     returned values.</p>
 414
 415     <p class="def">
 416       <span>macro</span>
 417       <a name="row-reader"></a>
 418       row-reader ((fields) &amp;body body)
 419       <br/>&#8594; function
 420     </p>
 421
 422     <p class="desc">Creates a row-reader, using the given name for the
 423     variable. Inside the body this variable refers to a vector of
 424     field descriptions. On top of that, two local functions are bound,
 425     <code>next-row</code> and <code>next-field</code>. The first will
 426     start reading the next row in the result, and returns a boolean
 427     indicating whether there is another row. The second will read and
 428     return one field, and should be passed the corresponding field
 429     description from the fields argument as a parameter.</p>
 430
 431     <p class="desc">A row reader should take care to iterate over all
 432     the rows in a result, and within each row iterate over all the
 433     fields. This means it should contain an outer loop that calls
 434     <code>next-row</code>, and every time <code>next-row</code>
 435     returns <code>T</code> it should iterate over the fields vector
 436     and call <code>next-field</code> for every field.</p>
 437
 438     <p class="desc">The definition of <a
 439     href="#list-row-reader"><code>list-row-reader</code></a> should
 440     give you an idea what a row reader looks like:</p>
 441
 442     <pre class="desc code">
 443 (row-reader (fields)
 444   (loop :while (next-row)
 445         :collect (loop :for field :across fields
 446                        :collect (next-field field))))</pre>
 447
 448     <p class="desc">Obviously, row readers should <em>not</em> do
 449     things with the database connection like, say, close it or start a
 450     new query, since it still reading out the results from the current
 451     query.</p>
 452
 453     <p class="def">
 454       <span>macro</span>
 455       <a name="def-row-reader"></a>
 456       def-row-reader (name (fields) &amp;body body)
 457     </p>
 458
 459     <p class="desc">The <code>defun</code>-like variant of <a
 460     href="#row-reader"><code>row-reader</code></a>: creates a row
 461     reader and gives it a top-level function name.</p>
 462
 463     <p class="def">
 464       <span>method</span>
 465       <a name="field-name"></a>
 466       field-name (field)
 467       <br/>&#8594; string
 468     </p>
 469
 470     <p class="desc">This can be used to get information about the
 471     fields read by a row reader. Given a field description, it returns
 472     the name the database associated with this column.</p>
 473
 474     <p class="def">
 475       <span>method</span>
 476       <a name="field-type"></a>
 477       field-type (field)
 478       <br/>&#8594; oid
 479     </p>
 480
 481     <p class="desc">This extracts the PostgreSQL <a
 482     href="http://www.postgresql.org/docs/current/static/datatype-oid.html">OID</a>
 483     associated with this column. You can, if you really want to, query
 484     the pg_types table to find out more about the types denoted by
 485     OIDs.</p>
 486
 487     <p class="def">
 488       <span>function</span>
 489       <a name="list-row-reader"></a>
 490       list-row-reader (socket fields)
 491       <br/>&#8594; list
 492     </p>
 493
 494     <p class="desc">A row reader that builds a list of lists from the
 495     query results.</p>
 496
 497     <p class="def">
 498       <span>function</span>
 499       <a name="alist-row-reader"></a>
 500       alist-row-reader (socket fields)
 501       <br/>&#8594; alist
 502     </p>
 503
 504     <p class="desc">A row reader that returns a list of alists, which
 505     associate column names with values.</p>
 506
 507     <p class="def">
 508       <span>function</span>
 509       <a name="ignore-row-reader"></a>
 510       ignore-row-reader (socket fields)
 511     </p>
 512
 513     <p class="desc">A row reader that completely ignores the result of
 514     a query.</p>
 515
 516     <h2><a name="bulk-copying">Bulk Copying</a></h2>
 517
 518     <p>When loading large amounts of data into PostgreSQL, it can be done
 519     significantly faster using the bulk copying feature.  The drawback to
 520     this approach is that you don't find out about data integrity errors
 521     until the entire batch is completed but sometimes the speed is worth it
 522     </p>
 523
 524     <p class="def">
 525       <span>function</span>
 526       <a name="open-db-writer"></a>
 527       open-db-writer (db table &optional columns)
 528     </p>
 529
 530     <p class="desc">Opens a table stream into which rows can be
 531     written one at a time
 532     using <code>db-write-row</code>. <code>db</code> is either
 533     a <a href="#database-connection">connection</a> object or a list
 534     of arguments that could be passed to <code>open-database</code>.
 535     <code>table</code> is the name of an existing table into which this writer
 536     will write rows.  If you don't have data for all columns, use
 537     <code>columns</code> to indicate those that you do.
 538     </p>
 539
 540     <p class="def">
 541       <span>function</span>
 542       <a name="close-db-writer"></a>
 543       close-db-writer (writer &key abort)
 544     </p>
 545
 546     <p class="desc">Closes a bulk writer opened
 547     by <code>open-db-writer</code>. Will close the associated database
 548     connection when it was created for this copier,
 549     or <code>abort</code> is true.</p>
 550
 551     <p class="def">
 552       <span>function</span>
 553       <a name="db-write-row"></a>
 554       db-write-row (writer row-data)
 555     </p>
 556
 557     <p class="desc">Writes <code>row-data</code> into the table and columns
 558     referenced by the writer.  <code>row-data</code> is a list of Lisp objects,
 559     one for each column included when opening the writer.  Arrays (the elements
 560     of which must all be the same type) will be serialized into their PostgreSQL
 561     representation before being written into the DB.
 562     </p>
 563
 564     <h2><a name="conditions">Conditions</a></h2>
 565
 566     <p>Opening or querying a database may raise errors. CL-postgres
 567     will wrap the errors that the server returns in a lisp condition,
 568     and raise conditions of the same type when it detects some problem
 569     itself. Socket errors are let through as they are.</p>
 570
 571     <p class="def">
 572       <span>condition</span>
 573       <a name="database-error"></a>
 574       database-error
 575     </p>
 576
 577     <p class="desc">The type of database-related conditions. For
 578     errors that you may want to catch by type, the
 579     <code>cl-postgres-error</code> package defines a bucket of
 580     subtypes used for specific errors. See the
 581     <code>cl-postgres/package.lisp</code> file for a list.</p>
 582
 583     <p class="def">
 584       <span>method</span>
 585       <a name="database-error-message"></a>
 586       database-error-message (database-error)
 587       <br/>&#8594; string
 588     </p>
 589
 590     <p class="desc">A short message associated with this error.</p>
 591
 592     <p class="def">
 593       <span>method</span>
 594       <a name="database-error-detail"></a>
 595       database-error-detail (database-error)
 596       <br/>&#8594; string
 597     </p>
 598
 599     <p class="desc">A longer description of the problem, or
 600     <code>NIL</code> if none is available.</p>
 601
 602     <p class="def">
 603       <span>method</span>
 604       <a name="database-error-code"></a>
 605       database-error-code (database-error)
 606       <br/>&#8594; string
 607     </p>
 608
 609     <p class="desc">The error code PostgreSQL associated with this
 610     error, if any. See the <a
 611     href="http://www.postgresql.org/docs/current/static/errcodes-appendix.html">PostgreSQL
 612     manual</a> for their meaning.</p>
 613
 614     <p class="def">
 615       <span>method</span>
 616       <a name="database-error-query"></a>
 617       database-error-query (database-error)
 618       <br/>&#8594; string
 619     </p>
 620
 621     <p class="desc">The query that led to this error, or
 622     <code>NIL</code> if no query was involved.</p>
 623
 624     <p class="def">
 625       <span>method</span>
 626       <a name="database-error-cause"></a>
 627       database-error-cause (database-error)
 628       <br/>&#8594; condition
 629     </p>
 630
 631     <p class="desc">The condition that caused this error, or
 632     <code>NIL</code> when it was not caused by another condition.</p>
 633
 634     <p class="def">
 635       <span>function</span>
 636       <a name="database-error-constraint-name"></a>
 637       database-error-constraint-name (database-error)
 638       <br/>&#8594; string
 639     </p>
 640
 641     <p class="desc">For integrity-violation errors, returns the name
 642     of the constraint that was violated (or <code>nil</code> if no
 643     constraint was found.)</p>
 644
 645     <p class="def">
 646       <span>condition</span>
 647       <a name="database-connection-error"></a>
 648       database-connection-error
 649     </p>
 650
 651     <p class="desc">Subtype of <a
 652     href="#database-error"><code>database-error</code></a>. An error
 653     of this type (or one of its subclasses) is signaled when a query
 654     is attempted with a connection object that is no longer connected,
 655     or a database connection becomes invalid during a query. Always
 656     provides a <code>:reconnect</code> restart, which will cause the
 657     library to make an attempt to restore the connection and re-try
 658     the query.</p>
 659
 660     <p class="desc">The following shows an example use of this
 661     feature, a way to ensure that the first connection error causes a
 662     reconnect attempt, while others pass through as normal. A
 663     variation on this theme could continue trying to reconnect, with
 664     successively longer pauses.</p>
 665
 666     <pre class="desc code">
 667 (defun call-with-single-reconnect (fun)
 668   (let ((reconnected nil))
 669     (handler-bind
 670         ((database-connection-error
 671           (lambda (err)
 672             (when (not reconnected)
 673               (setf reconnected t)
 674               (invoke-restart :reconnect)))))
 675       (funcall fun))))</pre>
 676
 677     <p class="def">
 678       <span>condition</span>
 679       <a name="postgresql-notification"></a>
 680       postgresql-notification
 681     </p>
 682
 683     <p class="desc">The condition that is signalled when a
 684       notification message is received from the PostgreSQL server.
 685       This is a <code>WARNING</code> condition which is caught by
 686       the <code>WAIT-FOR-NOTIFICATION</code> function that implements
 687       synchronous waiting for notifications.</p>
 688
 689     <p class="def">
 690       <span>method</span>
 691       <a name="postgresql-notification-channel"></a>
 692       postgresql-notification-channel (postgresql-notification)
 693       <br/>&#8594; string
 694     </p>
 695
 696     <p class="desc">The channel string of this notification.</p>
 697
 698     <p class="def">
 699       <span>method</span>
 700       <a name="postgresql-notification-payload"></a>
 701       postgresql-notification-payload (postgresql-notification)
 702       <br/>&#8594; string
 703     </p>
 704
 705     <p class="desc">The payload of this notification.</p>
 706
 707     <p class="def">
 708       <span>method</span>
 709       <a name="postgresql-notification-pid"></a>
 710       postgresql-notification-pid (postgresql-notification)
 711       <br/>&#8594; integer
 712     </p>
 713
 714     <p class="desc">The process ID of the process that sent the
 715     notification.</p>
 716
 717     <h2><a name="index">Symbol-index</a></h2>
 718
 719     <ul class="symbol-index">
 720       <li><a href="#alist-row-reader">alist-row-reader</a></li>
 721       <li><a href="#close-database">close-database</a></li>
 722       <li><a href="#close-db-writer">close-db-writer</a></li>
 723       <li><a href="#connection-meta">connection-meta</a></li>
 724       <li><a href="#connection-parameters">connection-parameters</a></li>
 725       <li><a href="#copy-sql-readtable">copy-sql-readtable</a></li>
 726       <li><a href="#database-connection">database-connection</a></li>
 727       <li><a href="#database-connection-error">database-connection-error</a></li>
 728       <li><a href="#database-error">database-error</a></li>
 729       <li><a href="#database-error-cause">database-error-cause</a></li>
 730       <li><a href="#database-error-code">database-error-code</a></li>
 731       <li><a href="#database-error-constraint-name">database-error-constraint-name</a></li>
 732       <li><a href="#database-error-detail">database-error-detail</a></li>
 733       <li><a href="#database-error-message">database-error-message</a></li>
 734       <li><a href="#database-error-query">database-error-query</a></li>
 735       <li><a href="#database-open-p">database-open-p</a></li>
 736       <li><a href="#def-row-reader">def-row-reader</a></li>
 737       <li><a href="#default-sql-readtable">default-sql-readtable</a></li>
 738       <li><a href="#exec-prepared">exec-prepared</a></li>
 739       <li><a href="#exec-query">exec-query</a></li>
 740       <li><a href="#field-name">field-name</a></li>
 741       <li><a href="#field-type">field-type</a></li>
 742       <li><a href="#ignore-row-reader">ignore-row-reader</a></li>
 743       <li><a href="#list-row-reader">list-row-reader</a></li>
 744       <li><a href="#log-query">log-query</a></li>
 745       <li><a href="#row-reader">next-field</a></li>
 746       <li><a href="#row-reader">next-row</a></li>
 747       <li><a href="#open-database">open-database</a></li>
 748       <li><a href="#open-db-writer">open-db-writer</a></li>
 749       <li><a href="#postgresql-notification">postgresql-notification</a></li>
 750       <li><a href="#postgresql-notification-channel">postgresql-notification-channel</a></li>
 751       <li><a href="#postgresql-notification-payload">postgresql-notification-payload</a></li>
 752       <li><a href="#postgresql-notification-pid">postgresql-notification-pid</a></li>
 753       <li><a href="#prepare-query">prepare-query</a></li>
 754       <li><a href="#*query-callback*">*query-callback*</a></li>
 755       <li><a href="#*query-log*">*query-log*</a></li>
 756       <li><a href="#reopen-database">reopen-database</a></li>
 757       <li><a href="#row-reader">row-reader</a></li>
 758       <li><a href="#set-sql-datetime-readers">set-sql-datetime-readers</a></li>
 759       <li><a href="#set-sql-reader">set-sql-reader</a></li>
 760       <li><a href="#write-db-row">write-db-row</a></li>
 761       <li><a href="#*silently-truncate-rationals*">*silently-truncate-rationals*</a></li>
 762       <li><a href="#*sql-readtable*">*sql-readtable*</a></li>
 763       <li><a href="#*ssl-certificate-file*">*ssl-certificate-file*</a></li>
 764       <li><a href="#*ssl-key-file*">*ssl-key-file*</a></li>
 765       <li><a href="#to-sql-string">to-sql-string</a></li>
 766       <li><a href="#*unix-socket-dir*">*unix-socket-dir*</a></li>
 767       <li><a href="#wait-for-notification">wait-for-notification</a></li>
 768     </ul>
 769   </body>
 770 </html>