3 # == What is Optimistic Locking
5 # Optimistic locking allows multiple users to access the same record for edits, and assumes a minimum of
6 # conflicts with the data. It does this by checking whether another process has made changes to a record since
7 # it was opened, an ActiveRecord::StaleObjectError is thrown if that has occurred and the update is ignored.
9 # Check out ActiveRecord::Locking::Pessimistic for an alternative.
13 # Active Records support optimistic locking if the field <tt>lock_version</tt> is present. Each update to the
14 # record increments the lock_version column and the locking facilities ensure that records instantiated twice
15 # will let the last one saved raise a StaleObjectError if the first was also updated. Example:
20 # p1.first_name = "Michael"
23 # p2.first_name = "should fail"
24 # p2.save # Raises a ActiveRecord::StaleObjectError
26 # Optimistic locking will also check for stale data when objects are destroyed. Example:
31 # p1.first_name = "Michael"
34 # p2.destroy # Raises a ActiveRecord::StaleObjectError
36 # You're then responsible for dealing with the conflict by rescuing the exception and either rolling back, merging,
37 # or otherwise apply the business logic needed to resolve the conflict.
39 # You must ensure that your database schema defaults the lock_version column to 0.
41 # This behavior can be turned off by setting <tt>ActiveRecord::Base.lock_optimistically = false</tt>.
42 # To override the name of the lock_version column, invoke the <tt>set_locking_column</tt> method.
43 # This method uses the same syntax as <tt>set_table_name</tt>
45 def self.included(base
) #:nodoc:
46 base
.extend ClassMethods
48 base
.cattr_accessor
:lock_optimistically, :instance_writer => false
49 base
.lock_optimistically
= true
51 base
.alias_method_chain
:update, :lock
52 base
.alias_method_chain
:destroy, :lock
53 base
.alias_method_chain
:attributes_from_column_definition, :lock
56 alias_method
:locking_column=, :set_locking_column
60 def locking_enabled
? #:nodoc:
61 self.class.locking_enabled
?
65 def attributes_from_column_definition_with_lock
66 result
= attributes_from_column_definition_without_lock
68 # If the locking column has no default value set,
69 # start the lock version at zero. Note we can't use
70 # locking_enabled? at this point as @attributes may
71 # not have been initialized yet
73 if lock_optimistically
&& result
.include?(self.class.locking_column
)
74 result
[self.class.locking_column
] ||= 0
80 def update_with_lock(attribute_names
= @attributes.keys
) #:nodoc:
81 return update_without_lock(attribute_names
) unless locking_enabled
?
82 return 0 if attribute_names
.empty
?
84 lock_col
= self.class.locking_column
85 previous_value
= send(lock_col
).to_i
86 send(lock_col
+ '=', previous_value
+ 1)
88 attribute_names
+= [lock_col
]
92 affected_rows
= connection
.update(<<-end_sql, "#{self.class.name} Update with optimistic locking")
93 UPDATE #{self.class.quoted_table_name}
94 SET #{quoted_comma_pair_list(connection, attributes_with_quotes(false, false, attribute_names))}
95 WHERE #{self.class.primary_key} = #{quote_value(id)}
96 AND #{self.class.quoted_locking_column} = #{quote_value(previous_value)}
99 unless affected_rows
== 1
100 raise ActiveRecord
::StaleObjectError, "Attempted to update a stale object"
105 # If something went wrong, revert the version.
107 send(lock_col
+ '=', previous_value
)
112 def destroy_with_lock
#:nodoc:
113 return destroy_without_lock
unless locking_enabled
?
116 lock_col
= self.class.locking_column
117 previous_value
= send(lock_col
).to_i
119 affected_rows
= connection
.delete(
120 "DELETE FROM #{self.class.quoted_table_name} " +
121 "WHERE #{connection.quote_column_name(self.class.primary_key)} = #{quoted_id} " +
122 "AND #{self.class.quoted_locking_column} = #{quote_value(previous_value)}",
123 "#{self.class.name} Destroy"
126 unless affected_rows
== 1
127 raise ActiveRecord
::StaleObjectError, "Attempted to delete a stale object"
135 DEFAULT_LOCKING_COLUMN
= 'lock_version'
137 def self.extended(base
)
139 alias_method_chain :update_counters, :lock
143 # Is optimistic locking enabled for this table? Returns true if the
144 # +lock_optimistically+ flag is set to true (which it is, by default)
145 # and the table includes the +locking_column+ column (defaults to
148 lock_optimistically && columns_hash[locking_column]
151 # Set the column to use for optimistic locking. Defaults to +lock_version+.
152 def set_locking_column(value = nil, &block)
153 define_attr_method :locking_column, value, &block
157 # The version column used for optimistic locking. Defaults to +lock_version+.
162 # Quote the column name used for optimistic locking.
163 def quoted_locking_column
164 connection.quote_column_name(locking_column)
167 # Reset the column used for optimistic locking back to the +lock_version+ default.
168 def reset_locking_column
169 set_locking_column DEFAULT_LOCKING_COLUMN
172 # Make sure the lock version column gets updated when counters are
174 def update_counters_with_lock(id, counters)
175 counters = counters.merge(locking_column => 1) if locking_enabled?
176 update_counters_without_lock(id, counters)