When you're in charge of a Rails app, there are a couple of areas where you really don't want to have problems:
- Data Integrity - Does the data in your database make sense?
- Database Performance - Do your queries return in a reasonable amount of time?
Database transactions (and their ActiveRecord counterparts) are powerful tools for avoiding these problems. Properly used, they can speed queries and ensure data integrity.
This article will introduce you to the concept of database transactions. It will also show you how to use them in Rails; but just as importantly, it will help you decide when to use them.
One cool thing about transactions is that they're actually implemented by the database. You can use them anywhere you use Postgres/MySQL/etc. Even if you're not a Ruby/Rails developer, the techniques you learn here will come in handy.
What Is A Transaction?
Transactions are typically used when you need to ensure data integrity, even if your web app crashes in the middle of a request.
From the Rails API docs
Transactions are protective blocks where SQL statements are only permanent if they can all succeed as one atomic action. The classic example is a transfer between two accounts where you can only have a deposit if the withdrawal succeeded and vice versa. Transactions enforce the integrity of the database and guard the data against program errors or database break-downs. Basically, you should use transaction blocks whenever you have a number of statements that must be executed together, or not at all.
A Classic Example
To illustrate why transactions are useful, let's consider a possible scenario.
Imagine that we are building a banking system that lets people transfer money. When John Doe (in Chicago) sends \$200 to Jane Doe (in London), we perform several DB operations.
- Check that John Doe has \$200 in his account.
- Debit the total amount from his account.
- Convert \$200 to Jane Doe's preferred currency, which is pounds.
- Credit Jane Doe's account.
An expensive problem
Implemented naively, our code might look like this:
sender.debit_account(amount) if sender.sufficient_balance(amount) credit_amount = convert_currency(amount, recipient) perform_transfer(recipient, credit_amount, sender)
What happens if our program crashes during the currency conversion? It's a crucial spot:
- After money has been taken out of John's account
- ...and before it's added to Jane's?
The money vanishes into thin air.
We need some way to ensure that errors along the way cause the database to roll back to avoid committing incomplete data. Either all of the database actions are performed, or none of them are.
Wrapping the above queries in a database transaction is your best bet for achieving data integrity.
In Rails, it might look like this:
Transfer.transaction do sender.debit_account(amount) if sender.sufficient_balance(amount) credit_amount = convert_currency(amount, recipient) perform_transfer(recipient, credit_amount, sender) end
Now, even though we might be creating and updating records, the supposed changes are not reflected in the database until the transaction is completed successfully.
States of Database Transaction
Transactions have a well-defined life cycle. At any point in time, your transaction will be in a specific state.
- Active: Our DB operations are being executed.
- Partially Committed: Our DB operations have completed successfully, but changes have not been committed to the database, and cannot be accessed outside of the transaction.
- Committed: Our DB operations have completed successfully and saved any changes to the DB.
- Failed: Some error has occurred, which caused the DB to stop the transaction. The DB has not been rolled back at this point.
- Aborted: The DB has been rolled back after a failure, and the transaction is done.
Transactions in ActiveRecord
We previously saw that our bank transfer code looked like this:
ActiveRecord::Base.transaction do sender.debit_account(amount) if sender.sufficient_balance(amount) credit_amount = convert_currency(amount, recipient) perform_transfer(recipient, credit_amount, sender) transfer.update_status end
We're calling the
transaction method on the
ActiveRecord::Base class and passing it a block. Every database operation that happens inside that block will be sent to the database as a transaction.
If any kind of unhandled error happens inside the block, the transaction will be aborted, and no changes will be made to the DB.
In the above example, I am calling the
transaction method on the
ActiveRecord::Base class. You might find yourself doing this in controller or service code.
Every ActiveRecord model has a
transaction method. Imagine that you have a
Transfer class that inherits from ActiveRecord. The following works:
Transfer.transaction do ... end
Every instance of your ActiveRecord models, also has its own
transfer = Transfer.new(...) transfer.transaction do ... end
And, because the
transaction method is an ordinary Ruby method, we can reference it in our model definitions:
class Transfer < ApplicationRecord def perform(...) self.transaction do ... end end end
How to Abort Transactions
To manually abort a transaction and prevent any of its changes from being written to the DB, you can use the
ActiveRecord::Base.transaction do @new_user = User.create!(user_params) @referrer = User.find(params[:referrer_id]) raise ActiveRecord::Rollback if @referrer.nil? @referrer.update!(params[:reference_record]) end
Exceptions During Transactions
Any unhandled exception that occurs during the transaction will also cause it to be aborted. There are two common ways to raise these exceptions:
- Using ActiveRecord methods ending with an exclamation-mark:
- Manually raising an exception
In ActiveRecord, when a method name ends with an exclamation-mark (also called a "bang"), it will raise an exception on failure.
Let's say we have a transaction that involves creating a new user account, while also updating the record of another user (the referrer):
ActiveRecord::Base.transaction do @new_user = User.create!(user_params) @referrer.update!(params[:reference_record]) end
update! methods will raise an exception if something goes wrong.
If we were to use the
update methods (without the exclamation mark), they would indicate a failure via their return value, and the transaction would keep running.
Of course, we could always check the return value ourselves and "manually" raise an exception if we wanted to:
ActiveRecord::Base.transaction do @new_user = User.create(user_params) raise ActiveRecord::RecordInvalid unless @new_user.persisted? ... end
It doesn't matter what kind of exception you raise. Any exception class will abort the transaction.
Don't forget to rescue the exception if you need to.
def create_referrer_account ActiveRecord::Base.transaction do ... raise ActiveRecord::RecordInvalid if @referrer.nil? rescue ActiveRecord::RecordInvalid => exception # handle error here... end end
The transactions we've seen so far only allow you to work with a single database. Most Rails apps only use one database, so that works out nicely.
If you need to ensure data integrity across multiple databases, you can do so by nesting ActiveRecord transactions.
In the example below, imagine that the
Referrer models point to different databases.
User.transaction do @new_user = User.create!(user_params) Referrer.transaction do @referrer.update!(params[:reference_record]) end end
If any parts of the inner transaction fail, it will cause the outer transaction to be aborted.
Beware, though, that nested transactions can be tricky to get right. It's best to avoid them if you can.
In programming, as in life, very few things are free. Transactions give us an excellent way to ensure data integrity, but they have a few possible drawbacks:
- Performance - Using a transaction will consume more resources on the DB server than the raw queries.
- Complexity - When overused, transactions can make your code more brittle and harder to understand.
For example, when you use a transaction in Rails, it ties up one of your DB connections until all the code in your transaction block finishes running. If the block contains something slow, like an API call, you could tie up a DB connection for an unreasonable amount of time.
ActiveRecord::Base.transaction do User.create!(user_params) SomeAPI.do_something(u) end
The key to using transactions well is to use them only when you really need them.
With great power comes great responsibility.
Transactions give developers the power to write SQL statements in the right way. This power has a great responsibility attached to it - one that should not be abused by sprinkling transactions everywhere.
In addition to what we have learned, here is a checklist I came with for when I use transactions:
- Do I need to handle more than one SQL statement?
- Do I need the SQL statement to succeed together?
While you make use of transactions, ensure you're raising and rescuing the errors as we saw above.