:::{php:namespace} Atk4\Data\Persistence\Sql :::

Transactions

When you work with the DSQL, you can work with transactions. There are 2 enhancements to the standard functionality of transactions in DSQL:

1. You can start nested transactions.
2. You can use {php:meth}Connection::atomic() which has a nicer syntax.

It is recommended to always use atomic() in your code.

:::{php:class} Connection :::

:::{php:method} atomic($callback) Execute callback within the SQL transaction. If callback encounters an exception, whole transaction will be automatically rolled back:

$c->atomic(function () use ($c) {
    $c->dsql('user')->set('balance = balance + 10')->where('id', 10)->mode('update')->executeStatement();
    $c->dsql('user')->set('balance = balance - 10')->where('id', 14)->mode('update')->executeStatement();
});

atomic() can be nested. The successful completion of a top-most method will commit everything. Rollback of a top-most method will roll back everything. :::

:::{php:method} beginTransaction Start new transaction. If already started, will do nothing but will increase transaction depth. :::

:::{php:method} commit Will commit transaction, however if {php:meth}Connection::beginTransaction was executed more than once, will only decrease transaction depth. :::

:::{php:method} inTransaction Returns true if transaction is currently active. There is no need for you to ever use this method. :::

:::{php:method} rollBack Roll-back the transaction, however if {php:meth}Connection::beginTransaction was executed more than once, will only decrease transaction depth. :::

:::{warning} If you roll-back internal transaction and commit external transaction, then result might be unpredictable. Please discuss this https://github.com/atk4/dsql/issues/89 :::