Activerecord::Transactionable

---

Provides a method, transaction_wrapper at the class and instance levels that can be used instead of ActiveRecord#transaction. Enables you to do transactions properly, with custom rescues and retry, including with or without locking.

Project	Activerecord::Transactionable
install	bundle add activerecord-transactionable
compatibility	Ruby >= 2.5
license
download rank
version
code triage
documentation	on RDoc.info
live chat
expert support
Spread ♡ⓛⓞⓥⓔ♡	🌏, 👼,

Useful as an example of correct behavior for wrapping transactions.

NOTE: Rails' transactions are per-database connection, not per-model, nor per-instance, see: http://api.rubyonrails.org/classes/ActiveRecord/Transactions/ClassMethods.html

Upgrading to Version 2

In version 1 the transaction_wrapper returned true or false. In version 2 it returns an instance of Activerecord::Transactionable::Result, which has a value, and three methods:

args = {}
result = transaction_wrapper(**args) do
  # some code that might fail here
end
result.fail?
result.success?
result.to_h # => a hash with diagnostic information, particularly useful when things go wrong

Where you used to have:

if result
  # ...
end

You must update to:

if result.success?
  # ...
end

Installation

Add this line to your application's Gemfile:

gem "activerecord-transactionable"

And then execute:

$ bundle

Or install it yourself as:

$ gem install activerecord-transactionable

Compatibility

Targeted ruby compatibility is non-EOL versions of Ruby, currently 2.6, 2.7, 3.0, 3.1, 3.2, 3.3. Ruby is limited to 2.5+ in the gemspec, and when it changes there will be a major release. The main branch currently targets 3.0.x releases.

Ruby OAuth Version	Maintenance Branch	Officially Supported Rubies	Unofficially Supported Rubies
3.0.x	main	2.6, 2.7, 3.0, 3.1, 3.2, 3.3	2.5
2.0.x	v2-maintenance	2.1, 2.2, 2.3, 2.4, 2.5, 2.6, 2.7, 3.0

NOTE: 2.0.5 is anticipated as last release of the 2.x series.

Usage

class Car < ActiveRecord::Base
  include Activerecord::Transactionable # Note lowercase "r" in Activerecord (different namespace than rails' module)

  validates_presence_of :name
end

When creating, saving, deleting within the transaction make sure to use the bang methods (!) in order to ensure a rollback on failure.

When everything works:

car = Car.new(name: "Fiesta")
car.transaction_wrapper do
  car.save!
end
car.persisted? # => true

When something goes wrong:

car = Car.new(name: nil)
car.transaction_wrapper do
  car.save!
end
car.persisted? # => false
car.errors.full_messages # => ["Name can't be blank"]

These examples are too simple to be useful with transactions, but if you are working with multiple records then it will make sense.

Also see the specs.

If you need to lock the car as well as have a transaction (note: will reload the car):

car = Car.new(name: nil)
car.transaction_wrapper(lock: true) do # uses ActiveRecord's with_lock
  car.save!
end
car.persisted? # => false
car.errors.full_messages # => ["Name can't be blank"]

If you need to know if the transaction succeeded:

car = Car.new(name: nil)
result = car.transaction_wrapper(lock: true) do # uses ActiveRecord's with_lock
  car.save!
end
result # => an instance of Activerecord::Transactionable::Result
result.success? # => true or false

Update Example

@client = Client.find(params[:id])
transaction_result = @client.transaction_wrapper(lock: true) do
  @client.assign_attributes(client_params)
  @client.save!
end
if transaction_result.success?
  render :show, locals: {client: @client}, status: :ok
else
  # Something prevented update, transaction_result.to_h will have all the available details
  render json: {record_errors: @client.errors, transaction_result: transaction_result.to_h}, status: :unprocessable_entity
end

Find or create

NOTE: The is_retry is passed to the block by the gem, and indicates whether the block is running for the first time or the second, or nth, time. The block will never be retried more than once.

Car.transaction_wrapper(outside_retriable_errors: ActivRecord::RecordNotFound, outside_num_retry_attempts: 3) do |is_retry|
  # is_retry will be falsey on first attempt, thereafter will be the integer number of the attempt
  if is_retry
    Car.create!(vin: vin)
  else
    Car.find_by!(vin: vin)
  end
end

Create or find

NOTE: The is_retry is passed to the block by the gem, and indicates whether the block is running for the first time or the second time. The block will never be retried more than once.

Car.transaction_wrapper(outside_retriable_errors: ActivRecord::RecordNotUnique) do |is_retry|
  # is_retry will be falsey on first attempt, thereafter will be the integer number of the attempt
  if is_retry
    Car.find_by!(vin: vin)
  else
    Car.create!(vin: vin)
  end
end

Reporting to SAAS Error Tools (like Raygun, etc)

Hopefully there will be a better integration at some point, but for now, somewhere in your code do:

module SendToRaygun
  def transaction_error_logger(**args)
    super
    if args[:error]
      begin
        Raygun.track_exception(args[:error])
        Rails.logger.debug("Sent Error to Raygun: #{args[:error].class}: #{args[:error].message}")
      rescue StandardError => e
        Rails.logger.error("Sending Error #{args[:error].class}: #{args[:error].message} to Raygun Failed with: #{e.class}: #{e.message}")
      end
    end
  end
end

Activerecord::Transactionable::ClassMethods.class_eval do
  prepend SendToRaygun
end

🪇 Code of Conduct

Everyone interacting in this project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

🛞 DVCS

This project does not trust any one version control system, so it abides the principles of "Distributed Version Control Systems"

Find this project on:

Any	Of	These	DVCS
🐙hub	🧊berg	🛖hut	🧪lab

🤝 Contributing

See CONTRIBUTING.md

🌈 Contributors

Contributor tiles (GitHub only) made with contributors-img.

Learn more about, or become one of, our 🎖 contributors on:

Any	Of	These	DVCS
🐙hub contributors	🧊berg contributors	🛖hut contributors	🧪lab contributors

📌 Versioning

This Library adheres to Semantic Versioning 2.0.0. Violations of this scheme should be reported as bugs. Specifically, if a minor or patch version is released that breaks backward compatibility, a new version should be immediately released that restores compatibility. Breaking changes to the public API will only be introduced with new major versions.

To get a better understanding of how SemVer is intended to work over a project's lifetime, read this article from the creator of SemVer:

• "Major Version Numbers are Not Sacred"

As a result of this policy, you can (and should) specify a dependency on these libraries using the Pessimistic Version Constraint with two digits of precision.

For example:

spec.add_dependency("activerecord-transactionable", "~> 3.0")

Contact

Author and maintainer is Peter Boling (@pboling).

Feedback and questions are welcome on the GitHub Discussions board.

For security-related issues see SECURITY.

📄 License

The gem is available as open source under the terms of the MIT License . See LICENSE.txt for the official Copyright Notice.

© Copyright

• Copyright (c) 2016-2018, 2021-2022, 2024 Peter H. Boling of Rails Bling