Permalink
Find file
Fetching contributors…
Cannot retrieve contributors at this time
172 lines (141 sloc) 7.28 KB
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Migrating to Postmodern 1.10</title>
<link rel="stylesheet" type="text/css" href="style.css"/>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
</head>
<body>
<h1>Migrating to Postmodern 1.10</h1>
<p>A number of backwards-incompatible changes are introduced in
this version of the library &#x2015; there are a few small
cleanups, and the database-access object system has been
completely overhauled.</p>
<h2><code>with-connection</code></h2>
<p>The old <code>with-connection</code> form has been replaced by
what used to be called <a
href="postmodern.html#with-connection"><code>with-connection*</code></a>.
This means that if you had code like this...</p>
<pre class="code">
(with-connection ("my-db" "harry" "****" "localhost") ...)</pre>
<p>... you should change it to ...</p>
<pre class="code">
(with-connection (list "my-db" "harry" "****" "localhost") ...)</pre>
<p>... since the whole list is now evaluated. Similarly, if you
were using <code>with-connection*</code>, you should remove the
asterisk.</p>
<h2>Integrating custom data types</h2>
<p>CL-postgres now exports <a href="cl-postgres.html#reading">ways
to manipulate</a> the way it reads values from query results. The
old <code>s-sql:sql-ize</code> generic has been moved to
<code>cl-posgres:<a
href="cl-postgres.html#to-sql-string">to-sql-string</a></code>,
and can be used to control the way values are written out when
passed as arguments to prepared statements or inserted in <a
href="s-sql.html">S-SQL</a> query forms.</p>
<p><a href="simple-date.html"><code>simple-date</code></a> is no
longer depended on by CL-postgres and S-SQL, but uses the above
interface to integrate itself. Load it <em>after</em> loading
CL-postgres, and suitable readers and writers for its types will
be registered. Integrating other date/time libraries is
trivial.</p>
<h2>Errors and reconnecting</h2>
<p>In previous versions, only the
<code>database-connection-lost</code> conditions offered a
<code>:reconnect</code> restart. There are now various conditions
offering this restart, all subtypes of <a
href="cl-postgres.html#database-connection-error"><code>database-connection-error</code></a>,
and the library tries its very best to wrap all hard-to-prevent
errors with such a restart (socket errors, database shutdowns).
The goal is that you can use this feature to cleanly and simply
add functionality for recovering from connectivity problems and
server restarts. If you still have issues here, please discuss
them on the mailing list (universal error recovery is rather hard
to test).</p>
<p>There is now also a large set of condition types exported from
the <code>cl-postgres-error</code> package, which can make writing
<code>handler-case</code> forms around database code a lot more
pleasant. See <code>cl-postgres/error.lisp</code> for the list (or
just cause the error you are interested in to be raised, and look
at its type).</p>
<h2>The DAO system</h2>
<p>This is where upgrading might be somewhat painful. The old
<code>deftable</code> macro has been dropped completely, in favour
of the <a
href="postmodern.html#dao-class"><code>dao-class</code></a>
metaclass. The focus of this part of the library has shifted from
defining <em>tables</em> to defining <em>access objects</em>. You
can still generate simple CREATE TABLE statements using the <a
href="postmodern.html#dao-table-definition"><code>dao-table-definition</code></a>
function, but this is intended to just be a shortcut. Table
definition is now the responsibility of the library user, not the
library.</p>
<p>So why this regression in functionality? It turned out that
coupling access objects and table definitions like this was not
such a good idea. You might want to create access objects for
views, or for tables with all kinds of complicated constraints.
Adding support for this to <code>deftable</code> would have turned
it into an even bigger behemoth than it already was, and not
fundamentally solve the problem.</p>
<p>So now we have a nice, clean DAO interface, and no
schema-definition interface at all (<code>create-template</code>
and friends were also dropped). The most notable change is
probably that the <code>:auto-id</code> option is gone. This was
very convenient but horribly 'magical'. If you had something like
this:</p>
<pre class="code">
(deftable product ()
((name :type string :initarg :name :accessor product-name)
(weight :type float :initarg :weight :accessor product-weight))
(:class-name product)
(:auto-id t)
(:indices (:unique name)))
(defun create-tables ()
; ...
(create-table 'product))</pre>
<p>The equivalent could look like this:</p>
<pre class="code">
(defclass product ()
((id :col-type serial :initarg :id :accessor product-id)
(name :col-type string :initarg :name :accessor product-name)
(weight :col-type float :initarg :weight :accessor product-weight))
(:keys id)
(:metaclass dao-class))
(defun create-tables ()
; ...
(execute (dao-table-definition 'product))
(execute (:create-unique-index 'product-name :on 'product :fields 'name)))</pre>
<p>Or you could explicitly create the id sequence and give the
<code>id</code> field a <code>:col-default</code> of
<code>(:nextval "product_ids")</code>, to have more control over
the id generation.</p>
<p>The above example should give you a basic idea of the new
interface: DAO classes are now created by regular class
definitions. Instead of <code>:type</code> options, column slots
should get <code>:column</code> or <code>:col-type</code> options.
The semantics of creating and inserting DAOs have been slightly
adjusted: There is no magic happening when you create a DAO
instance (it used to fetch id values), except when you give
<code>make-instance</code> a <code>:fetch-defaults</code> keyword
argument, in which case it will query the database for the rows'
default values, and put them in the instance. Usually, it is
cleaner to not use this, since it generates extra queries and does
not work for stuff like <code>serial</code> fields anyway, where no
proper <code>:col-default</code> can be given. When an object is
inserted into the database with <a
href="postmodern.html#insert-dao"><code>insert-dao</code></a>, some
slots may be unbound. These will then, both in the database and in
the object, be assigned values based on the column defaults. For
example, if you have the above <code>product</code> class:</p>
<pre class="code">
(defvar *p* (make-instance 'product :name "brick" :weight 2))
;; The id slot is unbound
(insert-dao *p*)
(print (product-id *p*))
;; Here it will have received a new id value</pre>
<p>Note that this works even for <code>serial</code> types, since
the defaults are fetched by giving the INSERT statement a
RETURNING clause, so the association between default values and
columns is handled by the database, not the DAO class.</p>
</body>
</html>