doc/migrating-to-1.10.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>Migrating to Postmodern 1.10</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>Migrating to Postmodern 1.10</h1>
  13
  14     <p>A number of backwards-incompatible changes are introduced in
  15     this version of the library &#x2015; there are a few small
  16     cleanups, and the database-access object system has been
  17     completely overhauled.</p>
  18
  19     <h2><code>with-connection</code></h2>
  20
  21     <p>The old <code>with-connection</code> form has been replaced by
  22     what used to be called <a
  23     href="postmodern.html#with-connection"><code>with-connection*</code></a>.
  24     This means that if you had code like this...</p>
  25
  26     <pre class="code">
  27 (with-connection ("my-db" "harry" "****" "localhost") ...)</pre>
  28
  29     <p>... you should change it to ...</p>
  30
  31     <pre class="code">
  32 (with-connection (list "my-db" "harry" "****" "localhost") ...)</pre>
  33
  34     <p>... since the whole list is now evaluated. Similarly, if you
  35     were using <code>with-connection*</code>, you should remove the
  36     asterisk.</p>
  37
  38     <h2>Integrating custom data types</h2>
  39
  40     <p>CL-postgres now exports <a href="cl-postgres.html#reading">ways
  41     to manipulate</a> the way it reads values from query results. The
  42     old <code>s-sql:sql-ize</code> generic has been moved to
  43     <code>cl-posgres:<a
  44     href="cl-postgres.html#to-sql-string">to-sql-string</a></code>,
  45     and can be used to control the way values are written out when
  46     passed as arguments to prepared statements or inserted in <a
  47     href="s-sql.html">S-SQL</a> query forms.</p>
  48
  49     <p><a href="simple-date.html"><code>simple-date</code></a> is no
  50     longer depended on by CL-postgres and S-SQL, but uses the above
  51     interface to integrate itself. Load it <em>after</em> loading
  52     CL-postgres, and suitable readers and writers for its types will
  53     be registered. Integrating other date/time libraries is
  54     trivial.</p>
  55
  56     <h2>Errors and reconnecting</h2>
  57
  58     <p>In previous versions, only the
  59     <code>database-connection-lost</code> conditions offered a
  60     <code>:reconnect</code> restart. There are now various conditions
  61     offering this restart, all subtypes of <a
  62     href="cl-postgres.html#database-connection-error"><code>database-connection-error</code></a>,
  63     and the library tries its very best to wrap all hard-to-prevent
  64     errors with such a restart (socket errors, database shutdowns).
  65     The goal is that you can use this feature to cleanly and simply
  66     add functionality for recovering from connectivity problems and
  67     server restarts. If you still have issues here, please discuss
  68     them on the mailing list (universal error recovery is rather hard
  69     to test).</p>
  70
  71     <p>There is now also a large set of condition types exported from
  72     the <code>cl-postgres-error</code> package, which can make writing
  73     <code>handler-case</code> forms around database code a lot more
  74     pleasant. See <code>cl-postgres/error.lisp</code> for the list (or
  75     just cause the error you are interested in to be raised, and look
  76     at its type).</p>
  77
  78     <h2>The DAO system</h2>
  79
  80     <p>This is where upgrading might be somewhat painful. The old
  81     <code>deftable</code> macro has been dropped completely, in favour
  82     of the <a
  83     href="postmodern.html#dao-class"><code>dao-class</code></a>
  84     metaclass. The focus of this part of the library has shifted from
  85     defining <em>tables</em> to defining <em>access objects</em>. You
  86     can still generate simple CREATE TABLE statements using the <a
  87     href="postmodern.html#dao-table-definition"><code>dao-table-definition</code></a>
  88     function, but this is intended to just be a shortcut. Table
  89     definition is now the responsibility of the library user, not the
  90     library.</p>
  91
  92     <p>So why this regression in functionality? It turned out that
  93     coupling access objects and table definitions like this was not
  94     such a good idea. You might want to create access objects for
  95     views, or for tables with all kinds of complicated constraints.
  96     Adding support for this to <code>deftable</code> would have turned
  97     it into an even bigger behemoth than it already was, and not
  98     fundamentally solve the problem.</p>
  99
 100     <p>So now we have a nice, clean DAO interface, and no
 101     schema-definition interface at all (<code>create-template</code>
 102     and friends were also dropped). The most notable change is
 103     probably that the <code>:auto-id</code> option is gone. This was
 104     very convenient but horribly 'magical'. If you had something like
 105     this:</p>
 106
 107     <pre class="code">
 108 (deftable product ()
 109   ((name :type string :initarg :name :accessor product-name)
 110    (weight :type float :initarg :weight :accessor product-weight))
 111   (:class-name product)
 112   (:auto-id t)
 113   (:indices (:unique name)))
 114
 115 (defun create-tables ()
 116   ; ...
 117   (create-table 'product))</pre>
 118
 119     <p>The equivalent could look like this:</p>
 120
 121     <pre class="code">
 122 (defclass product ()
 123   ((id :col-type serial :initarg :id :accessor product-id)
 124    (name :col-type string :initarg :name :accessor product-name)
 125    (weight :col-type float :initarg :weight :accessor product-weight))
 126   (:keys id)
 127   (:metaclass dao-class))
 128
 129 (defun create-tables ()
 130   ; ...
 131   (execute (dao-table-definition 'product))
 132   (execute (:create-unique-index 'product-name :on 'product :fields 'name)))</pre>
 133
 134    <p>Or you could explicitly create the id sequence and give the
 135    <code>id</code> field a <code>:col-default</code> of
 136    <code>(:nextval "product_ids")</code>, to have more control over
 137    the id generation.</p>
 138
 139    <p>The above example should give you a basic idea of the new
 140    interface: DAO classes are now created by regular class
 141    definitions. Instead of <code>:type</code> options, column slots
 142    should get <code>:column</code> or <code>:col-type</code> options.
 143    The semantics of creating and inserting DAOs have been slightly
 144    adjusted: There is no magic happening when you create a DAO
 145    instance (it used to fetch id values), except when you give
 146    <code>make-instance</code> a <code>:fetch-defaults</code> keyword
 147    argument, in which case it will query the database for the rows'
 148    default values, and put them in the instance. Usually, it is
 149    cleaner to not use this, since it generates extra queries and does
 150    not work for stuff like <code>serial</code> fields anyway, where no
 151    proper <code>:col-default</code> can be given. When an object is
 152    inserted into the database with <a
 153    href="postmodern.html#insert-dao"><code>insert-dao</code></a>, some
 154    slots may be unbound. These will then, both in the database and in
 155    the object, be assigned values based on the column defaults. For
 156    example, if you have the above <code>product</code> class:</p>
 157
 158    <pre class="code">
 159 (defvar *p* (make-instance 'product :name "brick" :weight 2))
 160 ;; The id slot is unbound
 161 (insert-dao *p*)
 162 (print (product-id *p*))
 163 ;; Here it will have received a new id value</pre>
 164
 165     <p>Note that this works even for <code>serial</code> types, since
 166     the defaults are fetched by giving the INSERT statement a
 167     RETURNING clause, so the association between default values and
 168     columns is handled by the database, not the DAO class.</p>
 169
 170   </body>
 171 </html>