X-Git-Url: http://git.kpe.io/?p=clsql.git;a=blobdiff_plain;f=doc%2Fref-transaction.xml;h=fea95176d1e3f1547d8bea8663e959962dc54088;hp=0d708b7e5729e2182a499a35ce425892cf5f1187;hb=04df7e672f08154fbc213236dfb2d2dd2023e802;hpb=cb683851a0af33e88b7c4995435dc0cf226f6cba diff --git a/doc/ref-transaction.xml b/doc/ref-transaction.xml index 0d708b7..fea9517 100644 --- a/doc/ref-transaction.xml +++ b/doc/ref-transaction.xml @@ -6,432 +6,676 @@ ]> + Transaction Handling - + This section describes the interface provided by &clsql; for + handling database transactions. The interface allows for opening + transaction blocks, committing or rolling back changes made and + controlling autocommit behaviour. - + + + START-TRANSACTION + - ADD-TRANSACTION-COMMIT-HOOK - + Function START-TRANSACTION + Open a transaction block. Function Syntax - (ADD-TRANSACTION-COMMIT-HOOK DATABASE COMMIT-HOOK) [function] => + start-transaction &key database => &nil; Arguments and Values - + + database + + A + database + object. This will default to the value + of *default-database*. + + Description - - + Starts a transaction block on + database which defaults to + *default-database* and which continues until + rollback or commit are + called. Examples - +(in-transaction-p) +=> NIL +(select [*] :from [foo] :field-names nil) +=> NIL +(start-transaction) +=> NIL +(in-transaction-p) +=> T +(insert-records :into [foo] :av-pairs '(([bar] 1) ([baz] "one"))) +=> +(select [*] :from [foo] :field-names nil) +=> ((1 "one")) +(rollback) +=> NIL +(in-transaction-p) +=> NIL +(select [*] :from [foo] :field-names nil) +=> NIL Side Effects - + Autocommit mode is disabled and if + database is currently within the scope + of a transaction, all commit and rollback hooks are removed + and the transaction level associated with + database is modified. Affected by - - - + None. Exceptional Situations - + Signals an error of type sql-database-error + if database is not a database object. See Also - - - - - + + commit + rollback + in-transaction-p + set-autocommit + with-transaction + Notes - + start-transaction is a &clsql; extension. - + + + COMMIT + - ADD-TRANSACTION-ROLLBACK-HOOK - + Function COMMIT + Commit modifications made in the current transaction. Function Syntax - (ADD-TRANSACTION-ROLLBACK-HOOK DATABASE ROLLBACK-HOOK) [function] => + commit &key database => &nil; Arguments and Values - + + database + + A + database + object. This will default to the value + of *default-database*. + + Description - - + If database, which defaults to + *default-database*, is currently within the + scope of a transaction, commits changes made since the + transaction began. Examples - +(in-transaction-p) +=> NIL +(select [*] :from [foo] :field-names nil) +=> NIL +(start-transaction) +=> NIL +(in-transaction-p) +=> T +(insert-records :into [foo] :av-pairs '(([bar] 1) ([baz] "one"))) +=> +(select [*] :from [foo] :field-names nil) +=> ((1 "one")) +(commit) +=> NIL +(in-transaction-p) +=> NIL +(select [*] :from [foo] :field-names nil) +=> ((1 "one")) Side Effects - + Changes made within the scope of the current transaction are + committed in the underlying database and the transaction level + of database is reset. Affected by - - - + The transaction level of database which + indicates whether a transaction has been initiated by a call to + start-transaction since the last call to + rollback or commit. Exceptional Situations - - + Signals an error of type sql-database-error + if database is not a database object. A + warning of type sql-warning is signalled if there + is no transaction in progress. + See Also - - - - - + + start-transaction + rollback + in-transaction-p + add-transaction-commit-hook + set-autocommit + with-transaction + Notes - + None. - + + + ROLLBACK + - COMMIT - + Function ROLLBACK + Roll back modifications made in the current transaction. Function Syntax - (COMMIT &KEY (DATABASE *DEFAULT-DATABASE*)) [function] => + rollback &key database => &nil; Arguments and Values - + + database + + A + database + object. This will default to the value + of *default-database*. + + Description - If DATABASE, which defaults to *DEFAULT-DATABASE*, is - currently within the scope of a transaction, commits changes - made since the transaction began. + If database, which defaults to + *default-database*, is currently within the + scope of a transaction, rolls back changes made since the + transaction began. Examples - +(in-transaction-p) +=> NIL +(select [*] :from [foo] :field-names nil) +=> NIL +(start-transaction) +=> NIL +(in-transaction-p) +=> T +(insert-records :into [foo] :av-pairs '(([bar] 1) ([baz] "one"))) +=> +(select [*] :from [foo] :field-names nil) +=> ((1 "one")) +(rollback) +=> NIL +(in-transaction-p) +=> NIL +(select [*] :from [foo] :field-names nil) +=> NIL Side Effects - - + Changes made within the scope of the current transaction are + reverted in the underlying database and the transaction level + of database is reset. Affected by - - - + The transaction level of database which + indicates whether a transaction has been initiated by a call to + start-transaction since the last call to + rollback or commit. Exceptional Situations - + Signals an error of type sql-database-error + if database is not a database object. A + warning of type sql-warning is signalled if + there is no transaction in progress. See Also - - - - - + + start-transaction + commit + in-transaction-p + add-transaction-rollback-hook + set-autocommit + with-transaction + Notes - + None. - + + IN-TRANSACTION-P + - IN-TRANSACTION-P - + Function IN-TRANSACTION-P + A predicate for testing whether a transaction is currently in progress. Function Syntax - (IN-TRANSACTION-P &KEY (DATABASE *DEFAULT-DATABASE*)) [function] => + in-transaction-p &key database => result Arguments and Values - + + database + + A + database + object. This will default to the value + of *default-database*. + + + + result + + A Boolean. + + Description - A predicate to test whether DATABASE, which - defaults to *DEFAULT-DATABASE*, is currently within - the scope of a transaction. + A predicate to test whether + database, which defaults to + *default-database*, is currently within the + scope of a transaction. Examples - +(in-transaction-p) +=> NIL +(start-transaction) +=> NIL +(in-transaction-p) +=> T +(commit) +=> NIL +(in-transaction-p) +=> NIL Side Effects - + None. Affected by - - - - + + None. Exceptional Situations - + None. See Also - - - - - + + start-transaction + commit + rollback + set-autocommit + Notes - + in-transaction-p is a &clsql; extension. - + + + ADD-TRANSACTION-COMMIT-HOOK + - ROLLBACK - + Function ADD-TRANSACTION-COMMIT-HOOK + Specify hooks to be run when committing changes. Function Syntax - (ROLLBACK &KEY (DATABASE *DEFAULT-DATABASE*)) [function] => + add-transaction-commit-hook commit-hook &key database => result Arguments and Values - + + commit-hook + + A designator for a function with no required arguments. + + + + database + + A + database + object. This will default to the value + of *default-database*. + + + + result + + The list of currently defined commit hooks for + database. + + + Description - If DATABASE, which defaults to *DEFAULT-DATABASE*, is - currently within the scope of a transaction, rolls back changes - made since the transaction began. + + Adds commit-hook, which should a + designator for a function with no required arguments, to the + list of hooks run when commit is called + on database which defaults to + *default-database*. Examples - +(start-transaction) +=> NIL +(add-transaction-commit-hook #'(lambda () (print "Successfully committed."))) +=> (#<Interpreted Function (LAMBDA # #) {48E2E689}>) +(commit) +"Successfully committed." +=> NIL Side Effects - + commit-hook is added to the list of + commit hooks for database. Affected by - - - + None. Exceptional Situations - + If commit-hook has one or more required + arguments, an error will be signalled when + commit is called. See Also - - - - - - - + + commit + rollback + add-transaction-rollback-hook + with-transaction + + Notes - + add-transaction-commit-hook is a &clsql; extension. - + + + ADD-TRANSACTION-ROLLBACK-HOOK + - SET-AUTOCOMMIT - + Function ADD-TRANSACTION-ROLLBACK-HOOK + Specify hooks to be run when rolling back changes. Function Syntax - (SET-AUTOCOMMIT VALUE &KEY (DATABASE *DEFAULT-DATABASE*)) [function] => + add-transaction-rollback-hook rollback-hook &key database => result Arguments and Values - + + rollback-hook + + A designator for a function with no required arguments. + + + + database + + A + database + object. This will default to the value + of *default-database*. + + + + result + + The list of currently defined rollback hooks for + database. + + + Description - Sets autocommit on or off. Returns old value of of autocommit flag. - + + Adds rollback-hook, which should a + designator for a function with no required arguments, to the + list of hooks run when rollback is called + on database which defaults to + *default-database*. Examples - +(start-transaction) +=> NIL +(add-transaction-rollback-hook #'(lambda () (print "Successfully rolled back."))) +=> (#<Interpreted Function (LAMBDA # #) {48E37C31}>) +(rollback) +"Successfully rolled back." +=> NIL Side Effects - + rollback-hook is added to the list of + rollback hooks for database. Affected by - - - + None. Exceptional Situations - + If rollback-hook has one or more + required arguments, an error will be signalled when + rollback is called. - + See Also - - - - - - + + commit + rollback + add-transaction-commit-hook + + Notes - + add-transaction-rollback-hook is a &clsql; extension. - - - - + + + SET-AUTOCOMMIT + - START-TRANSACTION - + Function SET-AUTOCOMMIT + Turn on or off autocommit for a database. Function Syntax - (START-TRANSACTION &KEY (DATABASE *DEFAULT-DATABASE*)) [function] => + set-autocommit value &key database => result Arguments and Values - + + value + + A Boolean specifying the desired autocommit + behaviour for database. + + + + + database + + A + database + object. This will default to the value + of *default-database*. + + + + result + + The previous autocommit value for + database. + + + Description - Starts a transaction block on DATABASE which defaults to - *DEFAULT-DATABASE* and which continues until ROLLBACK or COMMIT - are called. + Turns autocommit off for database + if value is &nil;, and otherwise turns it + on. Returns the old value of autocommit flag. + + + For RDBMS (such as Oracle) which don't automatically commit + changes, turning autocommit on has the effect of explicitly + committing changes made whenever SQL statements are executed. + + + Autocommit is turned on by default. @@ -443,103 +687,145 @@ Side Effects - + database is associated with the specified + autocommit mode. Affected by - - - + None. Exceptional Situations - + None. See Also - - - - - + + start-transaction + commit + add-transaction-commit-hook + with-transaction + Notes - + set-autocommit is a &clsql; extension. + + WITH-TRANSACTION + - WITH-TRANSACTION - - Function + Macro WITH-TRANSACTION + Execute a body of code within a transaction. + Macro Syntax - (WITH-TRANSACTION &KEY (DATABASE '*DEFAULT-DATABASE*) &REST BODY) [macro] => + with-transaction &key database &rest body => result Arguments and Values - + + database + + A + database + object. This will default to the value + of *default-database*. + + + body + + + A body of Lisp code. + + + + + result + + The result of executing body. + + + Description - Starts a transaction in the database - specified by DATABASE, which is *DEFAULT-DATABASE* by - default, and executes BODY within that transaction. If - BODY aborts or throws, DATABASE is rolled back and - otherwise the transaction is committed. + Starts a transaction in the database specified by + database, which is + *default-database* by default, and executes + body within that transaction. If + body aborts or throws, + database is rolled back and otherwise the + transaction is committed. Examples - +(in-transaction-p) +=> NIL +(select [email] :from [employee] :where [= [emplid] 1] :flatp t :field-names nil) +=> ("lenin@soviet.org") +(with-transaction () + (update-records [employee] + :av-pairs '((email "lenin-nospam@soviet.org")) + :where [= [emplid] 1])) +=> NIL +(select [email] :from [employee] :where [= [emplid] 1] :flatp t :field-names nil) +=> ("lenin-nospam@soviet.org") +(in-transaction-p) +=> NIL Side Effects - + Changes specified in body may be made + to the underlying database if body + completes successfully. Affected by - - - + None. Exceptional Situations - - + Signals an error of type sql-database-error + if database is not a database object. + See Also - - - - - + + start-transaction + commit + rollback + add-transaction-commit-hook + add-transaction-rollback-hook + Notes - + None.