openstax_transaction_isolation 2.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 642082ffd54b60574deeaf60055241d3382492d7cb93e33e4ab4c9910d9e7614
+  data.tar.gz: 0e364f699743134d38aac37dbdc3fb30129a230daf2433cfd007642337221af0
+SHA512:
+  metadata.gz: 4461123948d11de2e25044a691845bbed39e3dc167f7edc3868bf5351efae9cdd165d341e99d03297c277ccaea32be320c6d35b13a3886050609b69b33256752
+  data.tar.gz: 8e2a38504706b6a815b5080600bf670dd28cdb6e54116135e3af3578a431105d6f2a7d0a8a47c7fb50b1cd50f9376a69314106ca382768e0e7d78c0941c92169

data/.gitignore

@@ -0,0 +1,6 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+.idea
+test/log/*.log

data/Gemfile

@@ -0,0 +1,22 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in kontolib.gemspec
+gemspec
+
+group :test do
+  # Use the gem instead of a dated version bundled with Ruby
+  gem 'minitest', '5.3.4'
+  
+  gem 'simplecov', :require => false
+
+  gem 'mysql2'
+  gem 'pg'
+  gem 'sqlite3'
+end
+
+group :development do
+  gem 'rake'
+  # enhance irb
+  gem 'awesome_print', :require => false
+  gem 'pry', :require => false
+end

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (C) 2012 Piotr 'Qertoip' Włodarek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,118 @@
+NO LONGER MAINTAINED - PLEASE FORK OR SEEK OTHER SOLUTIONS
+
+
+# transaction_isolation
+
+Set transaction isolation level in the ActiveRecord in a database agnostic way.
+Works with MySQL, PostgreSQL and SQLite as long as you are using new adapters mysql2, pg or sqlite3.
+Supports all ANSI SQL isolation levels: :serializable, :repeatable_read, :read_committed, :read_uncommitted.
+
+See also [transaction_retry](https://github.com/qertoip/transaction_retry) gem for auto-retrying transactions 
+on deadlocks and serialization errors.
+
+## Example
+
+    ActiveRecord::Base.isolation_level( :serializable ) do
+      # your code
+    end
+
+## Installation
+
+Add this to your Gemfile:
+
+    gem 'transaction_isolation'
+
+Then run:
+
+    bundle
+
+__It works out of the box with Ruby on Rails__.
+
+If you have a standalone ActiveRecord-based project you'll need to call:
+
+    TransactionIsolation.apply_activerecord_patch     # after connecting to the database
+
+__after__ connecting to the database. This is because ActiveRecord loads adapters lazilly and only then they can be patched.
+
+## Features
+
+ * Setting transaction isolation level: :serializable, :repeatable_read, :read_committed, :read_uncommitted
+ * Auto-reverting to the original isolation level after the block
+ * Database agnostic
+ * MySQL, PostgreSQL and SQLite supported
+ * Exception translation. All deadlocks and serialization errors are wrapped in a ActiveRecord::TransactionIsolationConflict exception
+ * Use it in your Rails application or a standalone ActiveRecord-based project
+
+## Testimonials
+
+This gem was initially developed for and successfully works in production at [Kontomierz.pl](http://kontomierz.pl) - the finest Polish personal finance app.
+
+## Real world example
+
+When implementing a table-based job queue you should ensure that only one worker process can pop a particular job from the queue.
+Wrapping your code in a transaction is not enough because by default databases do not isolate transactions to the full extent,
+which leads to occasional phantom reads. It is therefore necessary to manually raise the transaction isolation level.
+The highest level of transaction isolation is called "serializable" and that's what we need here:
+
+    class QueuedJob < ActiveRecord::Base
+
+      # Job status
+      TODO = 1
+      PROCESSING = 2
+      DONE = 3
+
+      # Returns first job from the queue or nil if the queue is empty
+      def pop
+        QueuedJob.isolation_level( :serializable ) do
+          QueuedJob.transaction do
+            queued_job = find_by_status( TODO )
+            if queud_job
+              queued_job.update_attribute( :status, PROCESSING )
+              return queued_job
+            else
+              return nil
+            end
+          end
+        end
+      rescue ActiveRecord::TransactionIsolationConflict => e
+        logger.warn( e.message )
+        retry
+      end
+
+    end
+
+[Read more about isolation levels in Wikipedia](http://tinyurl.com/nrqjbb)
+
+## Requirements
+
+ * Ruby 1.9.2
+ * ActiveRecord 3.0.11+
+
+## Running tests
+
+Run tests on the selected database (mysql2 by default):
+
+    db=mysql2 bundle exec rake test
+    db=postgresql bundle exec rake test
+    db=sqlite3 bundle exec rake test
+
+Run tests on all supported databases:
+
+    ./tests
+
+Database configuration is hardcoded in test/db/db.rb; feel free to improve this and submit a pull request.
+
+## How intrusive is this gem?
+
+You should be very suspicious about any gem that monkey patches your stock Ruby on Rails framework.
+
+This gem is carefully written to not be more intrusive than it needs to be:
+
+ * introduces several new methods to Mysql2Adapter, PostgreSQLAdapter, SQLite3Adapter; names are carefully taken to not collide with future changes
+ * wraps #translate_exception method using alias_method_chain to add new translation
+ * introduces new class ActiveRecord::TransactionIsolationConflict in the ActiveRecord module
+ * introduces new convenience method ActiveRecord::Base.isolation_level akin to ActiveRecord::Base.transaction
+
+## License
+
+Released under the MIT license. Copyright (C) 2012 Piotr 'Qertoip' Włodarek.

data/Rakefile

@@ -0,0 +1,11 @@
+require "bundler/gem_tasks"
+
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs += ["test", "lib"]
+  t.pattern = 'test/integration/**/*_test.rb'
+  t.verbose = true
+end
+
+task :default => [:test]

data/lib/transaction_isolation/active_record/base.rb

@@ -0,0 +1,13 @@
+require 'active_record/base'
+
+module TransactionIsolation
+  module ActiveRecord
+    module Base
+      def isolation_level( isolation_level, &block )
+        connection.isolation_level( isolation_level, &block )
+      end
+    end
+  end
+end
+
+ActiveRecord::Base.extend( TransactionIsolation::ActiveRecord::Base )

data/lib/transaction_isolation/active_record/connection_adapters/abstract_adapter.rb

@@ -0,0 +1,32 @@
+require 'active_record/connection_adapters/abstract_adapter'
+
+module TransactionIsolation
+  module ActiveRecord
+    module ConnectionAdapters # :nodoc:
+      module AbstractAdapter
+
+        VALID_ISOLATION_LEVELS = [:read_uncommitted, :read_committed, :repeatable_read, :serializable]
+
+        # If true, #isolation_level(level) method is available
+        def supports_isolation_levels?
+          false
+        end
+
+        def isolation_level( level )
+          raise NotImplementedError
+        end
+
+        private
+
+          def validate_isolation_level( isolation_level )
+            unless VALID_ISOLATION_LEVELS.include?( isolation_level )
+              raise ArgumentError, "Invalid isolation level '#{isolation_level}'. Supported levels include #{VALID_ISOLATION_LEVELS.join( ', ' )}."
+            end
+          end
+
+      end
+    end
+  end
+end
+
+ActiveRecord::ConnectionAdapters::AbstractAdapter.send( :include, TransactionIsolation::ActiveRecord::ConnectionAdapters::AbstractAdapter )

data/lib/transaction_isolation/active_record/connection_adapters/mysql2_adapter.rb

@@ -0,0 +1,77 @@
+if defined?( ActiveRecord::ConnectionAdapters::Mysql2Adapter )
+
+  module TransactionIsolation
+    module ActiveRecord
+      module ConnectionAdapters # :nodoc:
+        module Mysql2Adapter
+
+          def self.included( base )
+            base.class_eval do
+              alias_method :translate_exception_without_transaction_isolation_conflict, :translate_exception
+              alias_method :translate_exception, :translate_exception_with_transaction_isolation_conflict
+            end
+          end
+
+          def supports_isolation_levels?
+            true
+          end
+
+          VENDOR_ISOLATION_LEVEL = {
+              :read_uncommitted => 'READ UNCOMMITTED',
+              :read_committed => 'READ COMMITTED',
+              :repeatable_read => 'REPEATABLE READ',
+              :serializable => 'SERIALIZABLE'
+          }
+
+          ANSI_ISOLATION_LEVEL = {
+              'READ UNCOMMITTED' => :read_uncommitted,
+              'READ COMMITTED' => :read_committed,
+              'REPEATABLE READ' => :repeatable_read,
+              'SERIALIZABLE' => :serializable
+          }
+
+          def current_isolation_level
+            ANSI_ISOLATION_LEVEL[current_vendor_isolation_level]
+          end
+
+          def current_vendor_isolation_level
+            select_value( "SELECT @@session.tx_isolation" ).gsub( '-', ' ' )
+          end
+
+          def isolation_level( level )
+            validate_isolation_level( level )
+
+            original_vendor_isolation_level = current_vendor_isolation_level if block_given?
+
+            execute( "SET SESSION TRANSACTION ISOLATION LEVEL #{VENDOR_ISOLATION_LEVEL[level]}" )
+
+            begin
+              yield
+            ensure
+              execute "SET SESSION TRANSACTION ISOLATION LEVEL #{original_vendor_isolation_level}"
+            end if block_given?
+          end
+
+          def translate_exception_with_transaction_isolation_conflict( exception, **args )
+            if isolation_conflict?( exception )
+              ::ActiveRecord::TransactionIsolationConflict.new( "Transaction isolation conflict detected: #{exception.message}" )
+            else
+              translate_exception_without_transaction_isolation_conflict( exception, **args )
+            end
+          end
+
+          def isolation_conflict?( exception )
+            [ "Deadlock found when trying to get lock",
+              "Lock wait timeout exceeded"].any? do |error_message|
+              exception.message =~ /#{Regexp.escape( error_message )}/i
+            end
+          end
+
+        end
+      end
+    end
+  end
+
+  ActiveRecord::ConnectionAdapters::Mysql2Adapter.send( :include, TransactionIsolation::ActiveRecord::ConnectionAdapters::Mysql2Adapter )
+
+end

data/lib/transaction_isolation/active_record/connection_adapters/postgresql_adapter.rb

@@ -0,0 +1,77 @@
+if defined?( ActiveRecord::ConnectionAdapters::PostgreSQLAdapter )
+
+  module TransactionIsolation
+    module ActiveRecord
+      module ConnectionAdapters # :nodoc:
+        module PostgreSQLAdapter
+
+          def self.included( base )
+            base.class_eval do
+              alias_method :translate_exception_without_transaction_isolation_conflict, :translate_exception
+              alias_method :translate_exception, :translate_exception_with_transaction_isolation_conflict
+            end
+          end
+
+          def supports_isolation_levels?
+            true
+          end
+
+          VENDOR_ISOLATION_LEVEL = {
+              :read_uncommitted => 'READ UNCOMMITTED',
+              :read_committed => 'READ COMMITTED',
+              :repeatable_read => 'REPEATABLE READ',
+              :serializable => 'SERIALIZABLE'
+          }
+
+          ANSI_ISOLATION_LEVEL = {
+              'READ UNCOMMITTED' => :read_uncommitted,
+              'READ COMMITTED' => :read_committed,
+              'REPEATABLE READ' => :repeatable_read,
+              'SERIALIZABLE' => :serializable
+          }
+
+          def current_isolation_level
+            ANSI_ISOLATION_LEVEL[current_vendor_isolation_level]
+          end
+
+          def current_vendor_isolation_level
+            select_value( "SHOW TRANSACTION ISOLATION LEVEL" ).upcase
+          end
+
+          def isolation_level( level )
+            validate_isolation_level( level )
+
+            original_vendor_isolation_level = current_vendor_isolation_level if block_given?
+
+            execute "SET SESSION CHARACTERISTICS AS TRANSACTION ISOLATION LEVEL #{VENDOR_ISOLATION_LEVEL[level]}"
+
+            begin
+              yield
+            ensure
+              execute "SET SESSION CHARACTERISTICS AS TRANSACTION ISOLATION LEVEL #{original_vendor_isolation_level}"
+            end if block_given?
+          end
+
+          def translate_exception_with_transaction_isolation_conflict( exception, **args )
+            if isolation_conflict?( exception )
+              ::ActiveRecord::TransactionIsolationConflict.new( "Transaction isolation conflict detected: #{exception.message}" )
+            else
+              translate_exception_without_transaction_isolation_conflict( exception, **args )
+            end
+          end
+
+          def isolation_conflict?( exception )
+            [ "deadlock detected",
+              "could not serialize access" ].any? do |error_message|
+              exception.message =~ /#{Regexp.escape( error_message )}/i
+            end
+          end
+
+        end
+      end
+    end
+  end
+
+  ActiveRecord::ConnectionAdapters::PostgreSQLAdapter.send( :include, TransactionIsolation::ActiveRecord::ConnectionAdapters::PostgreSQLAdapter )
+
+end

data/lib/transaction_isolation/active_record/connection_adapters/sqlite3_adapter.rb

@@ -0,0 +1,76 @@
+if defined?( ActiveRecord::ConnectionAdapters::SQLite3Adapter )
+
+  module TransactionIsolation
+    module ActiveRecord
+      module ConnectionAdapters # :nodoc:
+        module SQLite3Adapter
+
+          def self.included( base )
+            base.class_eval do
+              alias_method :translate_exception_without_transaction_isolation_conflict, :translate_exception
+              alias_method :translate_exception, :translate_exception_with_transaction_isolation_conflict
+            end
+          end
+
+          def supports_isolation_levels?
+            true
+          end
+
+          VENDOR_ISOLATION_LEVEL = {
+              :read_uncommitted => 'read_uncommitted = 1',
+              :read_committed => 'read_uncommitted = 0',
+              :repeatable_read => 'read_uncommitted = 0',
+              :serializable => 'read_uncommitted = 0'
+          }
+
+          ANSI_ISOLATION_LEVEL = {
+              'read_uncommitted = 1' => :read_uncommitted,
+              'read_uncommitted = 0' => :serializable
+          }
+
+          def current_isolation_level
+            ANSI_ISOLATION_LEVEL[current_vendor_isolation_level]
+          end
+
+          def current_vendor_isolation_level
+            "read_uncommitted = #{select_value( "PRAGMA read_uncommitted" )}"
+          end
+
+          def isolation_level( level )
+            validate_isolation_level( level )
+
+            original_vendor_isolation_level = current_vendor_isolation_level if block_given?
+
+            execute "PRAGMA #{VENDOR_ISOLATION_LEVEL[level]}"
+
+            begin
+              yield
+            ensure
+              execute "PRAGMA #{original_vendor_isolation_level}"
+            end if block_given?
+          end
+
+          def translate_exception_with_transaction_isolation_conflict( exception, **args )
+            if isolation_conflict?( exception )
+              ::ActiveRecord::TransactionIsolationConflict.new( "Transaction isolation conflict detected: #{exception.message}" )
+            else
+              translate_exception_without_transaction_isolation_conflict( exception, **args )
+            end
+          end
+
+          # http://www.sqlite.org/c3ref/c_abort.html
+          def isolation_conflict?( exception )
+            [ "The database file is locked",
+              "A table in the database is locked",
+              "Database lock protocol error"].any? do |error_message|
+              exception.message =~ /#{Regexp.escape( error_message )}/i
+            end
+          end
+        end
+      end
+    end
+  end
+
+  ActiveRecord::ConnectionAdapters::SQLite3Adapter.send( :include, TransactionIsolation::ActiveRecord::ConnectionAdapters::SQLite3Adapter )
+
+end

data/lib/transaction_isolation/active_record/errors.rb

@@ -0,0 +1,10 @@
+require 'active_record/errors'
+
+module ActiveRecord
+  # This exception represents both deadlocks and serialization conflicts.
+  # Deadlocks happen when db engine is using lock-based concurrency control.
+  # Serialization conflicts happen when db engine is using multi-version concurrency control.
+  # Often db engines combine both approaches and thus generate both types of errors.
+
+  class TransactionIsolationConflict < ::ActiveRecord::WrappedDatabaseException; end
+end

data/lib/transaction_isolation/version.rb

@@ -0,0 +1,3 @@
+module TransactionIsolation
+  VERSION = "2.0.0"
+end

data/lib/transaction_isolation.rb

@@ -0,0 +1,27 @@
+require "active_record"
+require_relative 'transaction_isolation/version'
+
+module TransactionIsolation
+
+  # Must be called after ActiveRecord established a connection.
+  # Only then we know which connection adapter is actually loaded and can be enhanced.
+  # Please note ActiveRecord does not load unused adapters.
+  def self.apply_activerecord_patch
+    require_relative 'transaction_isolation/active_record/errors'
+    require_relative 'transaction_isolation/active_record/base'
+    require_relative 'transaction_isolation/active_record/connection_adapters/abstract_adapter'
+    require_relative 'transaction_isolation/active_record/connection_adapters/mysql2_adapter'
+    require_relative 'transaction_isolation/active_record/connection_adapters/postgresql_adapter'
+    require_relative 'transaction_isolation/active_record/connection_adapters/sqlite3_adapter'
+  end
+
+  if defined?( ::Rails )
+    # Setup applying the patch after Rails is initialized.
+    class Railtie < ::Rails::Railtie
+      config.after_initialize do
+        TransactionIsolation.apply_activerecord_patch
+      end
+    end
+  end
+  
+end

data/transaction_isolation.gemspec

@@ -0,0 +1,21 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "transaction_isolation/version"
+
+Gem::Specification.new do |s|
+  s.name        = "openstax_transaction_isolation"
+  s.version     = TransactionIsolation::VERSION
+  s.authors     = ["Dante Soares", "Piotr 'Qertoip' Włodarek"]
+  s.email       = []
+  s.homepage    = "https://github.com/openstax/transaction_isolation"
+  s.summary     = %q{Set transaction isolation level in the ActiveRecord in a database agnostic way.}
+  s.description = %q{Set transaction isolation level in the ActiveRecord in a database agnostic way.
+Works with MySQL, PostgreSQL and SQLite as long as you are using new adapters mysql2, pg or sqlite3.
+Supports all ANSI SQL isolation levels: :serializable, :repeatable_read, :read_committed, :read_uncommitted.}
+  s.required_ruby_version = '>= 3'
+
+  s.files         = `git ls-files -z`.split("\x0").reject { |f| f == 'd' || f.start_with?('test') }
+  s.require_paths = ["lib"]
+
+  s.add_runtime_dependency "activerecord", ">= 6"
+end

metadata

@@ -0,0 +1,74 @@
+--- !ruby/object:Gem::Specification
+name: openstax_transaction_isolation
+version: !ruby/object:Gem::Version
+  version: 2.0.0
+platform: ruby
+authors:
+- Dante Soares
+- Piotr 'Qertoip' Włodarek
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6'
+description: |-
+  Set transaction isolation level in the ActiveRecord in a database agnostic way.
+  Works with MySQL, PostgreSQL and SQLite as long as you are using new adapters mysql2, pg or sqlite3.
+  Supports all ANSI SQL isolation levels: :serializable, :repeatable_read, :read_committed, :read_uncommitted.
+email: []
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- lib/transaction_isolation.rb
+- lib/transaction_isolation/active_record/base.rb
+- lib/transaction_isolation/active_record/connection_adapters/abstract_adapter.rb
+- lib/transaction_isolation/active_record/connection_adapters/mysql2_adapter.rb
+- lib/transaction_isolation/active_record/connection_adapters/postgresql_adapter.rb
+- lib/transaction_isolation/active_record/connection_adapters/sqlite3_adapter.rb
+- lib/transaction_isolation/active_record/errors.rb
+- lib/transaction_isolation/version.rb
+- transaction_isolation.gemspec
+homepage: https://github.com/openstax/transaction_isolation
+licenses: []
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.21
+signing_key:
+specification_version: 4
+summary: Set transaction isolation level in the ActiveRecord in a database agnostic
+  way.
+test_files: []