# 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.

In contrast to &commonsql;, &clsql;, by default, starts in transaction AUTOCOMMIT mode (see `set-autocommit`). To begin a transaction in autocommit mode, `start-transaction` has to be called explicitly.

START-TRANSACTION

START-TRANSACTION

Open a transaction block.

Function

### Syntax

          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

COMMIT

Commit modifications made in the current transaction.

Function

### Syntax

          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

ROLLBACK

Roll back modifications made in the current transaction.

Function

### Syntax

          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, 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

A predicate for testing whether a transaction is currently in progress.

Function

### Syntax

          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.

### 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

ADD-TRANSACTION-COMMIT-HOOK

Specify hooks to be run when committing changes.

Function

### Syntax

          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

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

ADD-TRANSACTION-ROLLBACK-HOOK

Specify hooks to be run when rolling back changes.

Function

### Syntax

          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

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

SET-AUTOCOMMIT

Turn on or off autocommit for a database.

Function

### Syntax

          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

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.

### Examples

### 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

Execute a body of code within a transaction.

Macro

### Syntax

          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.

### 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.