active_record-update_when 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 110b4ea48f85769e8a5cba616ed2a31b7aa1147449e8442a6dff525a6acd098d
+  data.tar.gz: 26499a97f0d835cf5127adaffb3e57457171d9cfad370e3084c9f6d9139a72b1
+SHA512:
+  metadata.gz: bf98d801d91afd4b516a0c906c71511cec3de26659158de7b44053e29b0704493f72be13ecafc4fcaf217e00a1c60dca2aa9438c565bf0d6f051714490e9c4aa
+  data.tar.gz: 78ae5f467b5e9e10d8a5818fb9e9485a4297a12752d297e6ade3871f19873d92f707795dd72b47bdf7baf5818e212e6626683554f7b9005d866e4f993db8c256

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2026 Minty Fresh
+
+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,95 @@
+# ActiveRecord::UpdateWhen
+
+Updates ActiveRecord records only when they match a condition in the database.
+
+The condition is part of the UPDATE statement itself, so it can't change between checking it and updating the record
+(eg. by a concurrent update).
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'active_record-update_when', github: 'mintyfresh/active_record-update_when'
+```
+
+And then execute:
+
+```bash
+$ bundle
+```
+
+Then include `ActiveRecord::UpdateWhen` in your models (typically in `ApplicationRecord`, so all models get it):
+
+```ruby
+class ApplicationRecord < ActiveRecord::Base
+  primary_abstract_class
+
+  include ActiveRecord::UpdateWhen
+end
+```
+
+## Usage
+
+`update_when` updates a record (as `update` would) if it matches the condition in the database:
+
+```ruby
+order = Order.find(...)
+
+if order.update_when(condition: Order.checked_out, attributes: { status: 'cancelled' })
+  # order was cancelled
+elsif order.errors.any?
+  # order was invalid
+else
+  # order wasn't checked-out
+end
+```
+
+```sql
+UPDATE "orders" SET "status" = 'cancelled', "updated_at" = ...
+WHERE "orders"."id" = 1 AND "orders"."status" = 'checked_out'
+```
+
+It returns false if the record is invalid (with errors), or if it doesn't match the condition (without errors).
+When the condition isn't met, the update is rolled back, including any changes made by its callbacks
+(even within another transaction).
+
+`update_when!` updates the record as `update!` would. It returns false if the record doesn't match the condition,
+and raises whenever `update!` would (eg. `ActiveRecord::RecordInvalid`):
+
+```ruby
+order.update_when!(condition: Order.checked_out, attributes: { status: 'cancelled' })
+```
+
+### Conditions
+
+The condition is a relation of the record's model. Its WHERE clause is added to the UPDATE:
+
+```ruby
+order.update_when(condition: Order.where(status: %w[pending checked_out]), attributes: { status: 'cancelled' })
+```
+
+Conditions can also have joins, GROUP BY and HAVING clauses (including for models with composite primary keys),
+in which case the record is matched by an EXISTS subquery:
+
+```ruby
+order.update_when(condition: Order.checked_out.joins(:lines), attributes: { status: 'cancelled' })
+```
+
+If the attributes don't change the record, nothing is updated (as with `update`) and the condition isn't checked.
+
+## Development
+
+The specs run against a dummy Rails application in `spec/dummy`, using SQLite by default:
+
+```bash
+$ bin/rspec
+$ bin/rubocop
+```
+
+PostgreSQL and MySQL are selected with the `DATABASE_ADAPTER` and `DATABASE_URL` environment variables
+(see `.github/workflows/ci.yml`).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+require 'rubocop/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/active_record/update_when/version.rb

@@ -0,0 +1,8 @@
+# typed: true
+# frozen_string_literal: true
+
+module ActiveRecord
+  module UpdateWhen
+    VERSION = '0.1.0'
+  end
+end

data/lib/active_record/update_when.rb

@@ -0,0 +1,125 @@
+# typed: true
+# frozen_string_literal: true
+
+require 'active_record'
+require 'active_record/update_when/version'
+
+module ActiveRecord
+  # Updates records only when they match a condition in the database, as part of the UPDATE statement itself,
+  # so that the condition can't change between checking it and updating the record (eg. by a concurrent update):
+  #
+  #   class ApplicationRecord < ActiveRecord::Base
+  #     include ActiveRecord::UpdateWhen
+  #   end
+  #
+  #   if order.update_when(condition: Order.checked_out, attributes: { status: 'cancelled' })
+  #     # the order was cancelled
+  #   elsif order.errors.any?
+  #     # the order was invalid
+  #   else
+  #     # the order wasn't checked-out
+  #   end
+  module UpdateWhen
+    # Raised from within the update when the record doesn't match the condition, to roll it back.
+    class ConditionNotMet < ActiveRecord::ActiveRecordError
+    end
+    private_constant :ConditionNotMet
+
+    # Updates the record (see `update`) if it matches the condition in the database.
+    # Returns false if the record is invalid (with errors), or if it doesn't match the condition (without errors),
+    # in which case the update is rolled back (including any changes made by its callbacks).
+    #
+    # The condition can have joins, GROUP BY and HAVING clauses (see `update_when_scope`).
+    # If the attributes don't change the record, nothing is updated and the condition isn't checked.
+    #
+    #: (condition: ActiveRecord::Relation, attributes: Hash[Symbol | String, untyped]) -> bool
+    def update_when(condition:, attributes:)
+      with_update_when_condition(condition) { update(attributes) }
+    end
+
+    # Updates the record (see `update!`) if it matches the condition in the database.
+    # Returns false if the record doesn't match the condition (see `update_when`),
+    # and raises whenever `update!` would (eg. if the record is invalid).
+    #
+    #: (condition: ActiveRecord::Relation, attributes: Hash[Symbol | String, untyped]) -> bool
+    def update_when!(condition:, attributes:)
+      with_update_when_condition(condition) { update!(attributes) }
+    end
+
+  private
+
+    # Updates within a savepoint, so that an unmatched condition rolls back the update's callbacks
+    # even within another transaction (which `update` would otherwise join).
+    #
+    #: (ActiveRecord::Relation condition) { () -> bool } -> bool
+    def with_update_when_condition(condition, &block)
+      validate_update_when_condition!(condition)
+
+      @update_when_condition = condition
+      self.class.transaction(requires_new: true, &block)
+    rescue ConditionNotMet
+      false
+    ensure
+      @update_when_condition = nil
+    end
+
+    #: (untyped condition) -> void
+    def validate_update_when_condition!(condition)
+      persisted? or
+        raise ArgumentError, "Can't conditionally update a #{self.class.name} which isn't persisted."
+
+      (condition.is_a?(ActiveRecord::Relation) && condition.model.base_class == self.class.base_class) or
+        raise ArgumentError, "Expected a relation of `#{self.class.base_class.name}`, got #{condition.inspect}."
+    end
+
+    # Constrains the UPDATE by the WHERE clause of the condition (see `ActiveRecord::Persistence._update_record`).
+    #
+    #: (Array[String] attribute_names, ?String attempted_action) -> Integer
+    def _update_row(attribute_names, attempted_action = 'update')
+      condition = @update_when_condition
+      return super if condition.nil?
+
+      affected_rows = update_when_scope(condition).scoping(all_queries: true) { super }
+
+      affected_rows.positive? or
+        raise ConditionNotMet, "#{self.class.name} #{attempted_action} matched no rows"
+
+      affected_rows
+    end
+
+    # Only the WHERE clause of a scope applies to the UPDATE, so conditions with other clauses (eg. joins)
+    # are matched by an EXISTS subquery of the primary keys of the records which match them.
+    #
+    # The subquery selects from a derived table, since MySQL can't otherwise select from the table being updated,
+    # and is DISTINCT, so that MySQL doesn't merge the derived table back into the subquery
+    # (as Rails' MySQL adapter does for `update_all`).
+    #
+    #: (ActiveRecord::Relation condition) -> ActiveRecord::Relation
+    def update_when_scope(condition)
+      return condition if where_clause_only?(condition)
+
+      model = self.class
+      primary_key = Array(model.primary_key)
+      matching_table = Arel::Table.new('update_when_condition')
+      matching = condition.unscope(:order).select(*primary_key.map { |column| model.arel_table[column] }).distinct
+
+      model.unscoped.where(
+        model.unscoped.from(matching, model.adapter_class.quote_table_name(matching_table.name)).select(Arel.sql('1'))
+          .where(same_record_condition(matching_table, primary_key)).arel.exists
+      )
+    end
+
+    #: (Arel::Table matching_table, Array[String] primary_key) -> Arel::Nodes::Node
+    def same_record_condition(matching_table, primary_key)
+      table = self.class.arel_table
+
+      Arel::Nodes::And.new(primary_key.map { |column| matching_table[column].eq(table[column]) })
+    end
+
+    #: (ActiveRecord::Relation condition) -> bool
+    def where_clause_only?(condition)
+      condition.joins_values.empty? && condition.left_outer_joins_values.empty? &&
+        condition.group_values.empty? && condition.having_clause.empty?
+    end
+  end
+end

metadata

@@ -0,0 +1,63 @@
+--- !ruby/object:Gem::Specification
+name: active_record-update_when
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Minty Fresh
+bindir: bin
+cert_chain: []
+date: 1980-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: '8.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.1'
+description: Updates ActiveRecord records only when they match a condition in the
+  database, atomically, as part of the UPDATE statement.
+email:
+- 7896757+mintyfresh@users.noreply.github.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- lib/active_record/update_when.rb
+- lib/active_record/update_when/version.rb
+homepage: https://github.com/mintyfresh/active_record-update_when
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/mintyfresh/active_record-update_when
+  source_code_uri: https://github.com/mintyfresh/active_record-update_when
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: Conditional updates for ActiveRecord records
+test_files: []