activerecord 1.0.0 → 4.0.0

data/lib/active_record/transactions.rb

@@ -1,102 +1,399 @@
-require 'active_record/vendor/simple.rb'
 require 'thread'
 
 module ActiveRecord
-  module Transactions # :nodoc:
-    TRANSACTION_MUTEX = Mutex.new
+  # See ActiveRecord::Transactions::ClassMethods for documentation.
+  module Transactions
+    extend ActiveSupport::Concern
+    ACTIONS = [:create, :destroy, :update]
 
-    def self.append_features(base)
-      super
-      base.extend(ClassMethods)
-
-      base.class_eval do
-        alias_method :destroy_without_transactions, :destroy
-        alias_method :destroy, :destroy_with_transactions
+    class TransactionError < ActiveRecordError # :nodoc:
+    end
 
-        alias_method :save_without_transactions, :save
-        alias_method :save, :save_with_transactions
-      end
+    included do
+      define_callbacks :commit, :rollback, :terminator => "result == false", :scope => [:kind, :name]
     end
 
-    # Transactions are protective blocks where SQL statements are only permanent if they can all succed as one atomic action. 
-    # The classic example is a transfer between two accounts where you can only have a deposit if the withdrawal succedded and
-    # vice versa. Transaction enforce the integrity of the database and guards the data against program errors or database break-downs.
-    # So basically you should use transaction blocks whenever you have a number of statements that must be executed together or
-    # not at all. Example:
+    # = Active Record Transactions
     #
-    #   Account.transaction do
+    # 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. So basically you should use transaction blocks whenever you
+    # have a number of statements that must be executed together or not at all.
+    #
+    # For example:
+    #
+    #   ActiveRecord::Base.transaction do
     #     david.withdrawal(100)
     #     mary.deposit(100)
     #   end
     #
-    # This example will only take money from David and give to Mary if neither +withdrawal+ nor +deposit+ raises an exception.
-    # Exceptions will force a ROLLBACK that returns the database to the state before the transaction was begun. Be aware, though,
-    # that the objects by default will _not_ have their instance data returned to their pre-transactional state.
+    # This example will only take money from David and give it to Mary if neither
+    # +withdrawal+ nor +deposit+ raise an exception. Exceptions will force a
+    # ROLLBACK that returns the database to the state before the transaction
+    # began. Be aware, though, that the objects will _not_ have their instance
+    # data returned to their pre-transactional state.
     #
-    # == Save and destroy are automatically wrapped in a transaction
+    # == Different Active Record classes in a single transaction
     #
-    # Both Base#save and Base#destroy come wrapped in a transaction that ensures that whatever you do in validations or callbacks
-    # will happen under the protected cover of a transaction. So you can use validations to check for values that the transaction
-    # depend on or you can raise exceptions in the callbacks to rollback.
+    # Though the transaction class method is called on some Active Record class,
+    # the objects within the transaction block need not all be instances of
+    # that class. This is because transactions are per-database connection, not
+    # per-model.
     #
-    # == Object-level transactions
+    # In this example a +balance+ record is transactionally saved even
+    # though +transaction+ is called on the +Account+ class:
     #
-    # You can enable object-level transactions for Active Record objects, though. You do this by naming the each of the Active Records
-    # that you want to enable object-level transactions for, like this:
+    #   Account.transaction do
+    #     balance.save!
+    #     account.save!
+    #   end
     #
-    #   Account.transaction(david, mary) do
-    #     david.withdrawal(100)
-    #     mary.deposit(100)
+    # The +transaction+ method is also available as a model instance method.
+    # For example, you can also do this:
+    #
+    #   balance.transaction do
+    #     balance.save!
+    #     account.save!
+    #   end
+    #
+    # == Transactions are not distributed across database connections
+    #
+    # A transaction acts on a single database connection. If you have
+    # multiple class-specific databases, the transaction will not protect
+    # interaction among them. One workaround is to begin a transaction
+    # on each class whose models you alter:
+    #
+    #   Student.transaction do
+    #     Course.transaction do
+    #       course.enroll(student)
+    #       student.units += course.units
+    #     end
+    #   end
+    #
+    # This is a poor solution, but fully distributed transactions are beyond
+    # the scope of Active Record.
+    #
+    # == +save+ and +destroy+ are automatically wrapped in a transaction
+    #
+    # Both +save+ and +destroy+ come wrapped in a transaction that ensures
+    # that whatever you do in validations or callbacks will happen under its
+    # protected cover. So you can use validations to check for values that
+    # the transaction depends on or you can raise exceptions in the callbacks
+    # to rollback, including <tt>after_*</tt> callbacks.
+    #
+    # As a consequence changes to the database are not seen outside your connection
+    # until the operation is complete. For example, if you try to update the index
+    # of a search engine in +after_save+ the indexer won't see the updated record.
+    # The +after_commit+ callback is the only one that is triggered once the update
+    # is committed. See below.
+    #
+    # == Exception handling and rolling back
+    #
+    # Also have in mind that exceptions thrown within a transaction block will
+    # be propagated (after triggering the ROLLBACK), so you should be ready to
+    # catch those in your application code.
+    #
+    # One exception is the <tt>ActiveRecord::Rollback</tt> exception, which will trigger
+    # a ROLLBACK when raised, but not be re-raised by the transaction block.
+    #
+    # *Warning*: one should not catch <tt>ActiveRecord::StatementInvalid</tt> exceptions
+    # inside a transaction block. <tt>ActiveRecord::StatementInvalid</tt> exceptions indicate that an
+    # error occurred at the database level, for example when a unique constraint
+    # is violated. On some database systems, such as PostgreSQL, database errors
+    # inside a transaction cause the entire transaction to become unusable
+    # until it's restarted from the beginning. Here is an example which
+    # demonstrates the problem:
+    #
+    #   # Suppose that we have a Number model with a unique column called 'i'.
+    #   Number.transaction do
+    #     Number.create(i: 0)
+    #     begin
+    #       # This will raise a unique constraint error...
+    #       Number.create(i: 0)
+    #     rescue ActiveRecord::StatementInvalid
+    #       # ...which we ignore.
+    #     end
+    #
+    #     # On PostgreSQL, the transaction is now unusable. The following
+    #     # statement will cause a PostgreSQL error, even though the unique
+    #     # constraint is no longer violated:
+    #     Number.create(i: 1)
+    #     # => "PGError: ERROR:  current transaction is aborted, commands
+    #     #     ignored until end of transaction block"
+    #   end
+    #
+    # One should restart the entire transaction if an
+    # <tt>ActiveRecord::StatementInvalid</tt> occurred.
+    #
+    # == Nested transactions
+    #
+    # +transaction+ calls can be nested. By default, this makes all database
+    # statements in the nested transaction block become part of the parent
+    # transaction. For example, the following behavior may be surprising:
+    #
+    #   User.transaction do
+    #     User.create(username: 'Kotori')
+    #     User.transaction do
+    #       User.create(username: 'Nemu')
+    #       raise ActiveRecord::Rollback
+    #     end
+    #   end
+    #
+    # creates both "Kotori" and "Nemu". Reason is the <tt>ActiveRecord::Rollback</tt>
+    # exception in the nested block does not issue a ROLLBACK. Since these exceptions
+    # are captured in transaction blocks, the parent block does not see it and the
+    # real transaction is committed.
+    #
+    # In order to get a ROLLBACK for the nested transaction you may ask for a real
+    # sub-transaction by passing <tt>requires_new: true</tt>. If anything goes wrong,
+    # the database rolls back to the beginning of the sub-transaction without rolling
+    # back the parent transaction. If we add it to the previous example:
+    #
+    #   User.transaction do
+    #     User.create(username: 'Kotori')
+    #     User.transaction(requires_new: true) do
+    #       User.create(username: 'Nemu')
+    #       raise ActiveRecord::Rollback
+    #     end
     #   end
     #
-    # If the transaction fails, David and Mary will be returned to their pre-transactional state. No money will have changed hands in
-    # neither object nor database.
+    # only "Kotori" is created. This works on MySQL and PostgreSQL. SQLite3 version >= '3.6.8' also supports it.
+    #
+    # Most databases don't support true nested transactions. At the time of
+    # writing, the only database that we're aware of that supports true nested
+    # transactions, is MS-SQL. Because of this, Active Record emulates nested
+    # transactions by using savepoints on MySQL and PostgreSQL. See
+    # http://dev.mysql.com/doc/refman/5.6/en/savepoint.html
+    # for more information about savepoints.
+    #
+    # === Callbacks
+    #
+    # There are two types of callbacks associated with committing and rolling back transactions:
+    # +after_commit+ and +after_rollback+.
+    #
+    # +after_commit+ callbacks are called on every record saved or destroyed within a
+    # transaction immediately after the transaction is committed. +after_rollback+ callbacks
+    # are called on every record saved or destroyed within a transaction immediately after the
+    # transaction or savepoint is rolled back.
     #
-    # == Exception handling
+    # These callbacks are useful for interacting with other systems since you will be guaranteed
+    # that the callback is only executed when the database is in a permanent state. For example,
+    # +after_commit+ is a good spot to put in a hook to clearing a cache since clearing it from
+    # within a transaction could trigger the cache to be regenerated before the database is updated.
     #
-    # Also have in mind that exceptions thrown within a transaction block will be propagated (after triggering the ROLLBACK), so you
-    # should be ready to catch those in your application code.
+    # === Caveats
+    #
+    # If you're on MySQL, then do not use DDL operations in nested transactions
+    # blocks that are emulated with savepoints. That is, do not execute statements
+    # like 'CREATE TABLE' inside such blocks. This is because MySQL automatically
+    # releases all savepoints upon executing a DDL operation. When +transaction+
+    # is finished and tries to release the savepoint it created earlier, a
+    # database error will occur because the savepoint has already been
+    # automatically released. The following example demonstrates the problem:
+    #
+    #   Model.connection.transaction do                           # BEGIN
+    #     Model.connection.transaction(requires_new: true) do  # CREATE SAVEPOINT active_record_1
+    #       Model.connection.create_table(...)                    # active_record_1 now automatically released
+    #     end                                                     # RELEASE savepoint active_record_1
+    #                                                             # ^^^^ BOOM! database error!
+    #   end
+    #
+    # Note that "TRUNCATE" is also a MySQL DDL statement!
+    module ClassMethods
+      # See ActiveRecord::Transactions::ClassMethods for detailed documentation.
+      def transaction(options = {}, &block)
+        # See the ConnectionAdapters::DatabaseStatements#transaction API docs.
+        connection.transaction(options, &block)
+      end
+
+      # This callback is called after a record has been created, updated, or destroyed.
+      #
+      # You can specify that the callback should only be fired by a certain action with
+      # the +:on+ option:
+      #
+      #   after_commit :do_foo, on: :create
+      #   after_commit :do_bar, on: :update
+      #   after_commit :do_baz, on: :destroy
+      #
+      #   after_commit :do_foo_bar, :on [:create, :update]
+      #   after_commit :do_bar_baz, :on [:update, :destroy]
+      #
+      # Note that transactional fixtures do not play well with this feature. Please
+      # use the +test_after_commit+ gem to have these hooks fired in tests.
+      def after_commit(*args, &block)
+        set_options_for_callbacks!(args)
+        set_callback(:commit, :after, *args, &block)
+      end
+
+      # This callback is called after a create, update, or destroy are rolled back.
+      #
+      # Please check the documentation of +after_commit+ for options.
+      def after_rollback(*args, &block)
+        set_options_for_callbacks!(args)
+        set_callback(:rollback, :after, *args, &block)
+      end
+
+      private
+
+      def set_options_for_callbacks!(args)
+        options = args.last
+        if options.is_a?(Hash) && options[:on]
+          assert_valid_transaction_action(options[:on])
+          options[:if] = Array(options[:if])
+          fire_on = Array(options[:on]).map(&:to_sym)
+          options[:if] << "transaction_include_any_action?(#{fire_on})"
+        end
+      end
+
+      def assert_valid_transaction_action(actions)
+        actions = Array(actions)
+        if (actions - ACTIONS).any?
+          raise ArgumentError, ":on conditions for after_commit and after_rollback callbacks have to be one of #{ACTIONS.join(",")}"
+        end
+      end
+    end
+
+    # See ActiveRecord::Transactions::ClassMethods for detailed documentation.
+    def transaction(options = {}, &block)
+      self.class.transaction(options, &block)
+    end
+
+    def destroy #:nodoc:
+      with_transaction_returning_status { super }
+    end
+
+    def save(*) #:nodoc:
+      rollback_active_record_state! do
+        with_transaction_returning_status { super }
+      end
+    end
+
+    def save!(*) #:nodoc:
+      with_transaction_returning_status { super }
+    end
+
+    # Reset id and @new_record if the transaction rolls back.
+    def rollback_active_record_state!
+      remember_transaction_record_state
+      yield
+    rescue Exception
+      restore_transaction_record_state
+      raise
+    ensure
+      clear_transaction_record_state
+    end
+
+    # Call the after_commit callbacks
     #
-    # Tribute: Object-level transactions are implemented by Transaction::Simple by Austin Ziegler.
-    module ClassMethods      
-      def transaction(*objects, &block)
-        TRANSACTION_MUTEX.lock
+    # Ensure that it is not called if the object was never persisted (failed create),
+    # but call it after the commit of a destroyed object
+    def committed! #:nodoc:
+      run_callbacks :commit if destroyed? || persisted?
+    ensure
+      clear_transaction_record_state
+    end
 
+    # Call the after rollback callbacks. The restore_state argument indicates if the record
+    # state should be rolled back to the beginning or just to the last savepoint.
+    def rolledback!(force_restore_state = false) #:nodoc:
+      run_callbacks :rollback
+    ensure
+      restore_transaction_record_state(force_restore_state)
+    end
+
+    # Add the record to the current transaction so that the :after_rollback and :after_commit callbacks
+    # can be called.
+    def add_to_transaction
+      if self.class.connection.add_transaction_record(self)
+        remember_transaction_record_state
+      end
+    end
+
+    # Executes +method+ within a transaction and captures its return value as a
+    # status flag. If the status is true the transaction is committed, otherwise
+    # a ROLLBACK is issued. In any case the status flag is returned.
+    #
+    # This method is available within the context of an ActiveRecord::Base
+    # instance.
+    def with_transaction_returning_status
+      status = nil
+      self.class.transaction do
+        add_to_transaction
         begin
-          objects.each { |o| o.extend(Transaction::Simple) }
-          objects.each { |o| o.start_transaction }
-          connection.begin_db_transaction
-
-          block.call
-  
-          connection.commit_db_transaction
-          objects.each { |o| o.commit_transaction }
-        rescue Exception => exception
-          connection.rollback_db_transaction
-          objects.each { |o| o.abort_transaction }
-          raise exception
-        ensure
-          TRANSACTION_MUTEX.unlock
+          status = yield
+        rescue ActiveRecord::Rollback
+          @_start_transaction_state[:level] = (@_start_transaction_state[:level] || 0) - 1
+          status = nil
         end
+
+        raise ActiveRecord::Rollback unless status
+      end
+      status
+    end
+
+    protected
+
+    # Save the new record state and id of a record so it can be restored later if a transaction fails.
+    def remember_transaction_record_state #:nodoc:
+      @_start_transaction_state[:id] = id if has_attribute?(self.class.primary_key)
+      unless @_start_transaction_state.include?(:new_record)
+        @_start_transaction_state[:new_record] = @new_record
       end
+      unless @_start_transaction_state.include?(:destroyed)
+        @_start_transaction_state[:destroyed] = @destroyed
+      end
+      @_start_transaction_state[:level] = (@_start_transaction_state[:level] || 0) + 1
+      @_start_transaction_state[:frozen?] = @attributes.frozen?
+    end
+
+    # Clear the new record state and id of a record.
+    def clear_transaction_record_state #:nodoc:
+      @_start_transaction_state[:level] = (@_start_transaction_state[:level] || 0) - 1
+      @_start_transaction_state.clear if @_start_transaction_state[:level] < 1
     end
 
-    def destroy_with_transactions #:nodoc:
-      if TRANSACTION_MUTEX.locked?
-        destroy_without_transactions
-      else
-        ActiveRecord::Base.transaction { destroy_without_transactions }
+    # Restore the new record state and id of a record that was previously saved by a call to save_record_state.
+    def restore_transaction_record_state(force = false) #:nodoc:
+      unless @_start_transaction_state.empty?
+        @_start_transaction_state[:level] = (@_start_transaction_state[:level] || 0) - 1
+        if @_start_transaction_state[:level] < 1 || force
+          restore_state = @_start_transaction_state
+          was_frozen = restore_state[:frozen?]
+          @attributes = @attributes.dup if @attributes.frozen?
+          @new_record = restore_state[:new_record]
+          @destroyed  = restore_state[:destroyed]
+          if restore_state.has_key?(:id)
+            self.id = restore_state[:id]
+          else
+            @attributes.delete(self.class.primary_key)
+            @attributes_cache.delete(self.class.primary_key)
+          end
+          @attributes.freeze if was_frozen
+          @_start_transaction_state.clear
+        end
       end
     end
-    
-    def save_with_transactions(perform_validation = true) #:nodoc:
-      result = nil
-      if TRANSACTION_MUTEX.locked?
-        result = save_without_transactions(perform_validation)
-      else
-        ActiveRecord::Base.transaction { result = save_without_transactions(perform_validation) }
+
+    # Determine if a record was created or destroyed in a transaction. State should be one of :new_record or :destroyed.
+    def transaction_record_state(state) #:nodoc:
+      @_start_transaction_state[state]
+    end
+
+    # Determine if a transaction included an action for :create, :update, or :destroy. Used in filtering callbacks.
+    def transaction_include_any_action?(actions) #:nodoc:
+      actions.any? do |action|
+        case action
+        when :create
+          transaction_record_state(:new_record)
+        when :destroy
+          destroyed?
+        when :update
+          !(transaction_record_state(:new_record) || destroyed?)
+        end
       end
-      return result
     end
   end
-end
+end

data/lib/active_record/translation.rb

@@ -0,0 +1,22 @@
+module ActiveRecord
+  module Translation
+    include ActiveModel::Translation
+
+    # Set the lookup ancestors for ActiveModel.
+    def lookup_ancestors #:nodoc:
+      klass = self
+      classes = [klass]
+      return classes if klass == ActiveRecord::Base
+
+      while klass != klass.base_class
+        classes << klass = klass.superclass
+      end
+      classes
+    end
+
+    # Set the i18n scope to overwrite ActiveModel.
+    def i18n_scope #:nodoc:
+      :activerecord
+    end
+  end
+end

data/lib/active_record/validations/associated.rb

@@ -0,0 +1,49 @@
+module ActiveRecord
+  module Validations
+    class AssociatedValidator < ActiveModel::EachValidator #:nodoc:
+      def validate_each(record, attribute, value)
+        if Array.wrap(value).reject {|r| r.marked_for_destruction? || r.valid?}.any?
+          record.errors.add(attribute, :invalid, options.merge(:value => value))
+        end
+      end
+    end
+
+    module ClassMethods
+      # Validates whether the associated object or objects are all valid.
+      # Works with any kind of association.
+      #
+      #   class Book < ActiveRecord::Base
+      #     has_many :pages
+      #     belongs_to :library
+      #
+      #     validates_associated :pages, :library
+      #   end
+      #
+      # WARNING: This validation must not be used on both ends of an association.
+      # Doing so will lead to a circular dependency and cause infinite recursion.
+      #
+      # NOTE: This validation will not fail if the association hasn't been
+      # assigned. If you want to ensure that the association is both present and
+      # guaranteed to be valid, you also need to use +validates_presence_of+.
+      #
+      # Configuration options:
+      #
+      # * <tt>:message</tt> - A custom error message (default is: "is invalid").
+      # * <tt>:on</tt> - Specifies when this validation is active. Runs in all
+      #   validation contexts by default (+nil+), other options are <tt>:create</tt>
+      #   and <tt>:update</tt>.
+      # * <tt>:if</tt> - Specifies a method, proc or string to call to determine
+      #   if the validation should occur (e.g. <tt>if: :allow_validation</tt>,
+      #   or <tt>if: Proc.new { |user| user.signup_step > 2 }</tt>). The method,
+      #   proc or string should return or evaluate to a +true+ or +false+ value.
+      # * <tt>:unless</tt> - Specifies a method, proc or string to call to
+      #   determine if the validation should not occur (e.g. <tt>unless: :skip_validation</tt>,
+      #   or <tt>unless: Proc.new { |user| user.signup_step <= 2 }</tt>). The
+      #   method, proc or string should return or evaluate to a +true+ or +false+
+      #   value.
+      def validates_associated(*attr_names)
+        validates_with AssociatedValidator, _merge_attributes(attr_names)
+      end
+    end
+  end
+end

data/lib/active_record/validations/presence.rb

@@ -0,0 +1,65 @@
+module ActiveRecord
+  module Validations
+    class PresenceValidator < ActiveModel::Validations::PresenceValidator # :nodoc:
+      def validate(record)
+        super
+        attributes.each do |attribute|
+          next unless record.class.reflect_on_association(attribute)
+          associated_records = Array(record.send(attribute))
+
+          # Superclass validates presence. Ensure present records aren't about to be destroyed.
+          if associated_records.present? && associated_records.all? { |r| r.marked_for_destruction? }
+            record.errors.add(attribute, :blank, options)
+          end
+        end
+      end
+    end
+
+    module ClassMethods
+      # Validates that the specified attributes are not blank (as defined by
+      # Object#blank?), and, if the attribute is an association, that the
+      # associated object is not marked for destruction. Happens by default
+      # on save.
+      #
+      #   class Person < ActiveRecord::Base
+      #     has_one :face
+      #     validates_presence_of :face
+      #   end
+      #
+      # The face attribute must be in the object and it cannot be blank or marked
+      # for destruction.
+      #
+      # If you want to validate the presence of a boolean field (where the real values
+      # are true and false), you will want to use
+      # <tt>validates_inclusion_of :field_name, in: [true, false]</tt>.
+      #
+      # This is due to the way Object#blank? handles boolean values:
+      # <tt>false.blank? # => true</tt>.
+      #
+      # This validator defers to the ActiveModel validation for presence, adding the
+      # check to see that an associated object is not marked for destruction. This
+      # prevents the parent object from validating successfully and saving, which then
+      # deletes the associated object, thus putting the parent object into an invalid
+      # state.
+      #
+      # Configuration options:
+      # * <tt>:message</tt> - A custom error message (default is: "can't be blank").
+      # * <tt>:on</tt> - Specifies when this validation is active. Runs in all
+      #   validation contexts by default (+nil+), other options are <tt>:create</tt>
+      #   and <tt>:update</tt>.
+      # * <tt>:if</tt> - Specifies a method, proc or string to call to determine if
+      #   the validation should occur (e.g. <tt>if: :allow_validation</tt>, or
+      #   <tt>if: Proc.new { |user| user.signup_step > 2 }</tt>). The method, proc
+      #   or string should return or evaluate to a +true+ or +false+ value.
+      # * <tt>:unless</tt> - Specifies a method, proc or string to call to determine
+      #   if the validation should not occur (e.g. <tt>unless: :skip_validation</tt>,
+      #   or <tt>unless: Proc.new { |user| user.signup_step <= 2 }</tt>). The method,
+      #   proc or string should return or evaluate to a +true+ or +false+ value.
+      # * <tt>:strict</tt> - Specifies whether validation should be strict.
+      #   See <tt>ActiveModel::Validation#validates!</tt> for more information.
+      def validates_presence_of(*attr_names)
+        validates_with PresenceValidator, _merge_attributes(attr_names)
+      end
+    end
+  end
+end