2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
4 <!ENTITY % myents SYSTEM "entities.inc">
8 <!-- Transaction handling -->
10 <reference id="ref-transaction">
11 <title>Transaction Handling</title>
14 This section describes the interface provided by &clsql; for
15 handling database transactions. The interface allows for opening
16 transaction blocks, committing or rolling back changes made and
17 controlling autocommit behaviour.
21 In contrast to &commonsql;, &clsql;, by default, starts in
22 transaction AUTOCOMMIT mode (see <link
23 linkend="set-autocommit"><function>set-autocommit</function></link>).
24 To begin a transaction in autocommit mode, <link
25 linkend="start-transaction"><function>start-transaction</function></link>
26 has to be called explicitly.
31 <refentry id="start-transaction">
33 <refentrytitle>START-TRANSACTION</refentrytitle>
36 <refname>START-TRANSACTION</refname>
37 <refpurpose>Open a transaction block.</refpurpose>
38 <refclass>Function</refclass>
43 <function>start-transaction</function> &key <replaceable>database</replaceable> => <returnvalue>&nil;</returnvalue></synopsis>
46 <title>Arguments and Values</title>
49 <term><parameter>database</parameter></term>
52 <glossterm linkend="gloss-database-object">database
53 object</glossterm>. This will default to the value
54 of <symbol>*default-database*</symbol>.</para>
60 <title>Description</title>
61 <para>Starts a transaction block on
62 <parameter>database</parameter> which defaults to
63 <symbol>*default-database*</symbol> and which continues until
64 <function>rollback</function> or <function>commit</function> are
69 <title>Examples</title>
73 (select [*] :from [foo] :field-names nil)
79 (insert-records :into [foo] :av-pairs '(([bar] 1) ([baz] "one")))
81 (select [*] :from [foo] :field-names nil)
87 (select [*] :from [foo] :field-names nil)
92 <title>Side Effects</title>
94 Autocommit mode is disabled and if
95 <parameter>database</parameter> is currently within the scope
96 of a transaction, all commit and rollback hooks are removed
97 and the transaction level associated with
98 <parameter>database</parameter> is modified.
102 <title>Affected by</title>
108 <title>Exceptional Situations</title>
110 Signals an error of type <symbol>sql-database-error</symbol>
111 if <parameter>database</parameter> is not a database object.
115 <title>See Also</title>
117 <member><link linkend="commit"><function>commit</function></link></member>
118 <member><link linkend="rollback"><function>rollback</function></link></member>
119 <member><link linkend="in-transaction-p"><function>in-transaction-p</function></link></member>
120 <member><link linkend="set-autocommit"><function>set-autocommit</function></link></member>
121 <member><link linkend="with-transaction"><function>with-transaction</function></link></member>
127 <function>start-transaction</function> is a &clsql; extension.
132 <refentry id="commit">
134 <refentrytitle>COMMIT</refentrytitle>
137 <refname>COMMIT</refname>
138 <refpurpose>Commit modifications made in the current transaction.</refpurpose>
139 <refclass>Function</refclass>
142 <title>Syntax</title>
144 <function>commit</function> &key <replaceable>database</replaceable> => <returnvalue>&nil;</returnvalue></synopsis>
147 <title>Arguments and Values</title>
150 <term><parameter>database</parameter></term>
153 <glossterm linkend="gloss-database-object">database
154 object</glossterm>. This will default to the value
155 of <symbol>*default-database*</symbol>.</para>
161 <title>Description</title>
162 <para>If <parameter>database</parameter>, which defaults to
163 <symbol>*default-database*</symbol>, is currently within the
164 scope of a transaction, commits changes made since the
169 <title>Examples</title>
173 (select [*] :from [foo] :field-names nil)
179 (insert-records :into [foo] :av-pairs '(([bar] 1) ([baz] "one")))
181 (select [*] :from [foo] :field-names nil)
187 (select [*] :from [foo] :field-names nil)
192 <title>Side Effects</title>
194 Changes made within the scope of the current transaction are
195 committed in the underlying database and the transaction level
196 of <parameter>database</parameter> is reset.
200 <title>Affected by</title>
202 The transaction level of <parameter>database</parameter> which
203 indicates whether a transaction has been initiated by a call to
204 <function>start-transaction</function> since the last call to
205 <function>rollback</function> or <function>commit</function>.
209 <title>Exceptional Situations</title>
211 Signals an error of type <symbol>sql-database-error</symbol>
212 if <parameter>database</parameter> is not a database object. A
213 warning of type <symbol>sql-warning</symbol> is signalled if there
214 is no transaction in progress.
218 <title>See Also</title>
220 <member><link linkend="start-transaction"><function>start-transaction</function></link></member>
221 <member><link linkend="rollback"><function>rollback</function></link></member>
222 <member><link linkend="in-transaction-p"><function>in-transaction-p</function></link></member>
223 <member><link linkend="add-transaction-commit-hook"><function>add-transaction-commit-hook</function></link></member>
224 <member><link linkend="set-autocommit"><function>set-autocommit</function></link></member>
225 <member><link linkend="with-transaction"><function>with-transaction</function></link></member>
236 <refentry id="rollback">
238 <refentrytitle>ROLLBACK</refentrytitle>
241 <refname>ROLLBACK</refname>
242 <refpurpose>Roll back modifications made in the current transaction.</refpurpose>
243 <refclass>Function</refclass>
246 <title>Syntax</title>
248 <function>rollback</function> &key <replaceable>database</replaceable> => <returnvalue>&nil;</returnvalue></synopsis>
251 <title>Arguments and Values</title>
254 <term><parameter>database</parameter></term>
257 <glossterm linkend="gloss-database-object">database
258 object</glossterm>. This will default to the value
259 of <symbol>*default-database*</symbol>.</para>
265 <title>Description</title>
266 <para>If <parameter>database</parameter>, which defaults to
267 <symbol>*default-database*</symbol>, is currently within the
268 scope of a transaction, rolls back changes made since the
273 <title>Examples</title>
277 (select [*] :from [foo] :field-names nil)
283 (insert-records :into [foo] :av-pairs '(([bar] 1) ([baz] "one")))
285 (select [*] :from [foo] :field-names nil)
291 (select [*] :from [foo] :field-names nil)
296 <title>Side Effects</title>
298 Changes made within the scope of the current transaction are
299 reverted in the underlying database and the transaction level
300 of <parameter>database</parameter> is reset. </para>
303 <title>Affected by</title>
305 The transaction level of <parameter>database</parameter> which
306 indicates whether a transaction has been initiated by a call to
307 <function>start-transaction</function> since the last call to
308 <function>rollback</function> or <function>commit</function>.
312 <title>Exceptional Situations</title>
314 Signals an error of type <symbol>sql-database-error</symbol>
315 if <parameter>database</parameter> is not a database object. A
316 warning of type <symbol>sql-warning</symbol> is signalled if
317 there is no transaction in progress.
321 <title>See Also</title>
323 <member><link linkend="start-transaction"><function>start-transaction</function></link></member>
324 <member><link linkend="commit"><function>commit</function></link></member>
325 <member><link linkend="in-transaction-p"><function>in-transaction-p</function></link></member>
326 <member><link linkend="add-transaction-rollback-hook"><function>add-transaction-rollback-hook</function></link></member>
327 <member><link linkend="set-autocommit"><function>set-autocommit</function></link></member>
328 <member><link linkend="with-transaction"><function>with-transaction</function></link></member>
339 <refentry id="in-transaction-p">
341 <refentrytitle>IN-TRANSACTION-P</refentrytitle>
344 <refname>IN-TRANSACTION-P</refname>
345 <refpurpose>A predicate for testing whether a transaction is currently in progress.</refpurpose>
346 <refclass>Function</refclass>
349 <title>Syntax</title>
351 <function>in-transaction-p</function> &key <replaceable>database</replaceable> => <returnvalue>result</returnvalue></synopsis>
354 <title>Arguments and Values</title>
357 <term><parameter>database</parameter></term>
360 <glossterm linkend="gloss-database-object">database
361 object</glossterm>. This will default to the value
362 of <symbol>*default-database*</symbol>.</para>
366 <term><parameter>result</parameter></term>
368 <para>A Boolean.</para>
374 <title>Description</title>
375 <para>A predicate to test whether
376 <parameter>database</parameter>, which defaults to
377 <symbol>*default-database*</symbol>, is currently within the
378 scope of a transaction.
382 <title>Examples</title>
397 <title>Side Effects</title>
403 <title>Affected by</title>
409 <title>Exceptional Situations</title>
415 <title>See Also</title>
417 <member><link linkend="start-transaction"><function>start-transaction</function></link></member>
418 <member><link linkend="commit"><function>commit</function></link></member>
419 <member><link linkend="rollback"><function>rollback</function></link></member>
420 <member><link linkend="set-autocommit"><function>set-autocommit</function></link></member>
426 <function>in-transaction-p</function> is a &clsql; extension.
431 <refentry id="add-transaction-commit-hook">
433 <refentrytitle>ADD-TRANSACTION-COMMIT-HOOK</refentrytitle>
436 <refname>ADD-TRANSACTION-COMMIT-HOOK</refname>
437 <refpurpose>Specify hooks to be run when committing changes.</refpurpose>
438 <refclass>Function</refclass>
441 <title>Syntax</title>
443 <function>add-transaction-commit-hook</function> <replaceable>commit-hook</replaceable> &key <replaceable>database</replaceable> => <returnvalue>result</returnvalue></synopsis>
446 <title>Arguments and Values</title>
449 <term><parameter>commit-hook</parameter></term>
451 <para>A designator for a function with no required arguments.</para>
455 <term><parameter>database</parameter></term>
458 <glossterm linkend="gloss-database-object">database
459 object</glossterm>. This will default to the value
460 of <symbol>*default-database*</symbol>.</para>
464 <term><parameter>result</parameter></term>
466 <para>The list of currently defined commit hooks for
467 <parameter>database</parameter>.
474 <title>Description</title>
476 Adds <parameter>commit-hook</parameter>, which should a
477 designator for a function with no required arguments, to the
478 list of hooks run when <function>commit</function> is called
479 on <parameter>database</parameter> which defaults to
480 <symbol>*default-database*</symbol>.
484 <title>Examples</title>
488 (add-transaction-commit-hook #'(lambda () (print "Successfully committed.")))
489 => (#<Interpreted Function (LAMBDA # #) {48E2E689}>)
491 "Successfully committed."
496 <title>Side Effects</title>
498 <parameter>commit-hook</parameter> is added to the list of
499 commit hooks for <parameter>database</parameter>.
503 <title>Affected by</title>
509 <title>Exceptional Situations</title>
511 If <parameter>commit-hook</parameter> has one or more required
512 arguments, an error will be signalled when
513 <function>commit</function> is called.
517 <title>See Also</title>
519 <member><link linkend="commit"><function>commit</function></link></member>
520 <member><link linkend="rollback"><function>rollback</function></link></member>
521 <member><link linkend="add-transaction-rollback-hook"><function>add-transaction-rollback-hook</function></link></member>
522 <member><link linkend="with-transaction"><function>with-transaction</function></link></member>
524 </refsect1> <refsect1>
527 <function>add-transaction-commit-hook</function> is a &clsql; extension.
532 <refentry id="add-transaction-rollback-hook">
534 <refentrytitle>ADD-TRANSACTION-ROLLBACK-HOOK</refentrytitle>
537 <refname>ADD-TRANSACTION-ROLLBACK-HOOK</refname>
538 <refpurpose>Specify hooks to be run when rolling back changes.</refpurpose>
539 <refclass>Function</refclass>
542 <title>Syntax</title>
544 <function>add-transaction-rollback-hook</function> <replaceable>rollback-hook</replaceable> &key <replaceable>database</replaceable> => <returnvalue>result</returnvalue></synopsis>
547 <title>Arguments and Values</title>
550 <term><parameter>rollback-hook</parameter></term>
552 <para>A designator for a function with no required arguments.</para>
556 <term><parameter>database</parameter></term>
559 <glossterm linkend="gloss-database-object">database
560 object</glossterm>. This will default to the value
561 of <symbol>*default-database*</symbol>.</para>
565 <term><parameter>result</parameter></term>
567 <para>The list of currently defined rollback hooks for
568 <parameter>database</parameter>.
575 <title>Description</title>
577 Adds <parameter>rollback-hook</parameter>, which should a
578 designator for a function with no required arguments, to the
579 list of hooks run when <function>rollback</function> is called
580 on <parameter>database</parameter> which defaults to
581 <symbol>*default-database*</symbol>. </para>
584 <title>Examples</title>
588 (add-transaction-rollback-hook #'(lambda () (print "Successfully rolled back.")))
589 => (#<Interpreted Function (LAMBDA # #) {48E37C31}>)
591 "Successfully rolled back."
596 <title>Side Effects</title>
598 <parameter>rollback-hook</parameter> is added to the list of
599 rollback hooks for <parameter>database</parameter>.
603 <title>Affected by</title>
609 <title>Exceptional Situations</title>
611 If <parameter>rollback-hook</parameter> has one or more
612 required arguments, an error will be signalled when
613 <function>rollback</function> is called.
617 <title>See Also</title>
619 <member><link linkend="commit"><function>commit</function></link></member>
620 <member><link linkend="rollback"><function>rollback</function></link></member>
621 <member><link linkend="add-transaction-commit-hook"><function>add-transaction-commit-hook</function></link></member>
627 <function>add-transaction-rollback-hook</function> is a &clsql; extension.
632 <refentry id="set-autocommit">
634 <refentrytitle>SET-AUTOCOMMIT</refentrytitle>
637 <refname>SET-AUTOCOMMIT</refname>
638 <refpurpose>Turn on or off autocommit for a database.</refpurpose>
639 <refclass>Function</refclass>
642 <title>Syntax</title>
644 <function>set-autocommit</function> <replaceable>value</replaceable> &key <replaceable>database</replaceable> => <returnvalue>result</returnvalue></synopsis>
647 <title>Arguments and Values</title>
650 <term><parameter>value</parameter></term>
652 <para>A Boolean specifying the desired autocommit
653 behaviour for <parameter>database</parameter>.
658 <term><parameter>database</parameter></term>
661 <glossterm linkend="gloss-database-object">database
662 object</glossterm>. This will default to the value
663 of <symbol>*default-database*</symbol>.</para>
667 <term><parameter>result</parameter></term>
669 <para>The previous autocommit value for
670 <parameter>database</parameter>.
677 <title>Description</title>
678 <para>Turns autocommit off for <parameter>database</parameter>
679 if <parameter>value</parameter> is &nil;, and otherwise turns it
680 on. Returns the old value of autocommit flag.
683 For RDBMS (such as Oracle) which don't automatically commit
684 changes, turning autocommit on has the effect of explicitly
685 committing changes made whenever SQL statements are executed.
688 Autocommit is turned on by default.
692 <title>Examples</title>
698 <title>Side Effects</title>
700 <parameter>database</parameter> is associated with the specified
705 <title>Affected by</title>
711 <title>Exceptional Situations</title>
717 <title>See Also</title>
719 <member><link linkend="start-transaction"><function>start-transaction</function></link></member>
720 <member><link linkend="commit"><function>commit</function></link></member>
721 <member><link linkend="add-transaction-commit-hook"><function>add-transaction-commit-hook</function></link></member>
722 <member><link linkend="with-transaction"><function>with-transaction</function></link></member>
728 <function>set-autocommit</function> is a &clsql; extension.
733 <refentry id="with-transaction">
735 <refentrytitle>WITH-TRANSACTION</refentrytitle>
738 <refname>WITH-TRANSACTION</refname>
739 <refpurpose>Execute a body of code within a transaction.</refpurpose>
740 <refclass>Macro</refclass>
743 <title>Syntax</title>
745 <function>with-transaction</function> &key <replaceable>database</replaceable> &rest <replaceable>body</replaceable> => <returnvalue>result</returnvalue></synopsis>
748 <title>Arguments and Values</title>
751 <term><parameter>database</parameter></term>
754 <glossterm linkend="gloss-database-object">database
755 object</glossterm>. This will default to the value
756 of <symbol>*default-database*</symbol>.</para>
760 <term><parameter>body</parameter></term>
768 <term><parameter>result</parameter></term>
770 <para>The result of executing <parameter>body</parameter>.</para>
776 <title>Description</title>
777 <para>Starts a transaction in the database specified by
778 <parameter>database</parameter>, which is
779 <symbol>*default-database*</symbol> by default, and executes
780 <parameter>body</parameter> within that transaction. If
781 <parameter>body</parameter> aborts or throws,
782 <parameter>database</parameter> is rolled back and otherwise the
783 transaction is committed.
787 <title>Examples</title>
791 (select [email] :from [employee] :where [= [emplid] 1] :flatp t :field-names nil)
792 => ("lenin@soviet.org")
794 (update-records [employee]
795 :av-pairs '((email "lenin-nospam@soviet.org"))
796 :where [= [emplid] 1]))
798 (select [email] :from [employee] :where [= [emplid] 1] :flatp t :field-names nil)
799 => ("lenin-nospam@soviet.org")
805 <title>Side Effects</title>
807 Changes specified in <parameter>body</parameter> may be made
808 to the underlying database if <parameter>body</parameter>
809 completes successfully.
813 <title>Affected by</title>
819 <title>Exceptional Situations</title>
821 Signals an error of type <symbol>sql-database-error</symbol>
822 if <parameter>database</parameter> is not a database object.
826 <title>See Also</title>
828 <member><link linkend="start-transaction"><function>start-transaction</function></link></member>
829 <member><link linkend="commit"><function>commit</function></link></member>
830 <member><link linkend="rollback"><function>rollback</function></link></member>
831 <member><link linkend="add-transaction-commit-hook"><function>add-transaction-commit-hook</function></link></member>
832 <member><link linkend="add-transaction-rollback-hook"><function>add-transaction-rollback-hook</function></link></member>