Transactions

revIgniter's database abstraction allows you to use transactions with databases that support transaction-safe table types. In MySQL, you'll need to be running InnoDB or BDB table types rather than the more common MyISAM. Most other database platforms support transactions natively.

If you are not familiar with transactions it is recommended, that you find a good online resource to learn about them for your particular database. The information below assumes you have a basic understanding of transactions.

revIgniter's Approach to Transactions

revIgniter utilizes an approach to transactions that is very similar to the process used by the popular database class ADODB. This approach greatly simplifies the process of running transactions. In most cases all that is required are two lines of code.

Traditionally, transactions have required a fair amount of work to implement since they demand, that you keep track of your queries and determine whether to commit or rollback based on the success or failure of your queries. This is particularly cumbersome with nested queries. In contrast, revIgniter uses a smart transaction system that does all this for you automatically (you can also manage your transactions manually if you choose to, but there's really no benefit).

Running Transactions

To run your queries using transactions you will use the rigDbTransStart and rigTransComplete() handlers as follows:

rigDbTransStart
get rigDbQuery("AN SQL QUERY…")
get rigDbQuery("ANOTHER QUERY…")
get rigDbQuery("AND YET ANOTHER QUERY…")
get rigTransComplete()

You can run as many queries as you want between the start/complete handlers and they will all be committed or rolled back based on success or failure of any given query.

Strict Mode

By default revIgniter runs all transactions in Strict Mode. When strict mode is enabled, if you are running multiple groups of transactions, if one group fails all groups will be rolled back. If strict mode is disabled, each group is treated independently, meaning a failure of one group will not affect any others.

Strict Mode can be disabled as follows:

rigDbTransStrict FALSE

Managing Errors

If you have error reporting enabled in your config/database.lc file you'll see a standard error message if the commit was unsuccessful. If debugging is turned off, you can manage your own errors like this:

rigDbTransStart
get rigDbQuery("AN SQL QUERY…")
get rigDbQuery("ANOTHER QUERY…")
get rigTransComplete()

if rigDbTransStatus() is FALSE then
	# generate an error... or use the rigLogMessage handler to log your error
end if

Enabling Transactions

Transactions are enabled automatically the moment you use rigDbTransStart. If you would like to disable transactions you can do so using rigDbTransOff:

rigDbTransOff

rigDbTransStart
get rigDbQuery("AN SQL QUERY…")
get rigTransComplete()

When transactions are disabled, your queries will be auto-commited, just as they are when running queries without transactions.

Test Mode

You can optionally put the transaction system into "test mode", which will cause your queries to be rolled back -- even if the queries produce a valid result. To use test mode simply set the first parameter in the rigDbTransStart handler to TRUE:

rigDbTransStart TRUE -- Query will be rolled back
get rigDbQuery("AN SQL QUERY…")
get rigTransComplete()

Running Transactions Manually

If you would like to run transactions manually you can do so as follows:

get rigTransBegin()

get rigDbQuery("AN SQL QUERY…")
get rigDbQuery("ANOTHER QUERY…")
get rigDbQuery("AND YET ANOTHER QUERY…")


if rigDbTransStatus() is FALSE then
  rigTransRollback
else
  rigTransCommit
end if

Note: Make sure to use rigTransBegin() when running manual transactions, NOT rigDbTransStart.