activerecord-updateinbulk 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4ecff8b9c04987407c4d1d3e1bc0dd14e3bb0f54ff53cffd09cbdf76ba0afdc3
+  data.tar.gz: 2f6031daf51bbac0fb3455ffc02bba6d2590dff17c95665cfc4fe31994487ea7
+SHA512:
+  metadata.gz: 16eda867b24725afda253569d0474db0c02658dd59e6a31623d2279dfdbad26bbedf3717d3a72240bf59b7de03e5745d7cd0c8c54ab6e992b8bcfdbad059b840
+  data.tar.gz: a960ee63d7ec9ba055b61a636a7acb735c0aca31ab9f2f114f28ea45045f142a1bc266ac9287371253c57df8145a68617937956382a24f287c1ef65da2724c47

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bruno Carvalho
+
+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,165 @@
+# ActiveRecord Update in Bulk
+
+Introduces ``Relation#update_in_bulk``, a method to update many records in a table with different values in a single SQL statement,
+something traditionally performed with either $N$ consecutive updates or a series of repetitive `CASE` statements.
+
+The method generates a single `UPDATE` query with an inner join to a handcrafted `VALUES` table constructor holding both row matching _conditions_ and the values to assign to each set of rows matched.
+This construct is available on the latest versions of all databases supported by rails.
+
+Similar to `update_all`, it returns the number of affected rows, and bumps update timestamps by default.
+
+Tested on Ruby 3.4 and Rails 8 for all builtin databases on latest versions.
+
+## Usage
+
+```ruby
+# Indexed format: hash of primary key => attributes to update.
+Employee.update_in_bulk({
+  1 => { salary: 75_000, title: "Software engineer" },
+  2 => { title: "Claude prompter" },
+  3 => { salary: 68_000 }
+})
+
+# Composite primary keys work as well.
+FlightSeat.update_in_bulk({
+  ["AA100", "12A"] => { passenger: "Alice" },
+  ["AA100", "12B"] => { passenger: "Bob" }
+})
+
+# Paired format: array of [conditions, assigns] pairs.
+# Conditions don't have to be primary keys, they can refer to any columns in the target table.
+Employee.update_in_bulk([
+  [{ department: "Sales" },       { bonus: 2500 }],
+  [{ department: "Engineering" }, { bonus: 500 }]
+])
+
+# Separated format: parallel arrays of conditions and assigns.
+# Primary key conditions can be given in their natural form.
+Employee.update_in_bulk(
+  [1, 2, { id: 3 }],
+  [{ salary: 75_000, title: "Software engineer" }, { title: "Claude prompter" }, { salary: 68_000 }]
+)
+```
+
+### Relation scoping
+
+Relation constraints are preserved, including joins:
+
+```ruby
+# Only adjust salaries for currently active employees.
+Employee.where(active: true).update_in_bulk([
+  [{ department: "Sales" },       { bonus: 2500 }],
+  [{ department: "Engineering" }, { bonus: 500 }]
+])
+
+# Joins work too - update orders that have at least one shipped item.
+Order.joins(:items).where(items: { status: :shipped }).update_in_bulk({
+  10 => { status: :fulfilled },
+  11 => { status: :fulfilled }
+})
+```
+
+### Record timestamps
+
+By default `update_in_bulk` implicitly bumps update timestamps similar to `upsert_all`.
+- If the model has `updated_at`/`updated_on`, these are bumped *iff the row actually changed*.
+- Passing `record_timestamps: false` can disable bumping the update timestamps for the query.
+- The `updated_at` columns can also be manually assigned, this disables the implicit bump behaviour.
+
+```ruby
+Employee.update_in_bulk({
+  1 => { department: "Engineering" },
+  2 => { department: "Sales" }
+}, record_timestamps: false)
+```
+
+### Formulas (computed assignments)
+
+In all examples so far the queries simply assign predetermined values to rows matched, irrespective of their previous values.
+
+Formulas can augment this in the predictable way of letting you set a custom expression for the assignment, where the new value can be based on the state of current row, the incoming value(s) for that row, and even values in other tables joined in.
+
+```ruby
+# Fulfill an order: subtract different quantities from each product stock in one statement.
+Inventory.update_in_bulk({
+  "Christmas balls" => { quantity: 73 },
+  "Christmas tree"  => { quantity: 1 }
+}, formulas: { quantity: :subtract })
+# Generates: inventories.quantity = inventories.quantity - t.column2
+```
+
+Built-in formulas:
+- `:add :subtract :min :max :concat_append :concat_prepend`
+
+Custom formulas are supported by providing a `Proc`. The proc takes `(lhs,rhs,model)` and must return an **Arel node**.
+Here `lhs` and `rhs` are instances of `Arel::Attribute` corresponding to the target table and values table respectively.
+
+```ruby
+# Restock some products, but cap inventory at some maximum amount.
+# LEAST(metadata.max_stock, inventories.quantity + t.quantity)
+add_capped = proc |lhs, rhs| do
+  Arel::Nodes::Least.new([Arel::Attribute.new("metadata", "max_stock"), lhs + rhs])
+end
+Inventory.joins(:metadata).update_in_bulk({
+  "Christmas balls" => { quantity: 300 },
+  "Christmas tree"  => { quantity: 10 }
+}, formulas: { quantity: add_capped })
+```
+
+## Notes
+
+Running `EXPLAIN` on the database engines indicates they do run these queries as one would expect, using the correct index based on the join condition, but there are no tests or benchmarks for this yet.
+
+Given the nature of the query being an inner join with the condition columns, all conditions must use the same keys, and they should not have _NULL_ values, which won't match any rows.
+
+Conditions and assigns must reference actual columns on the target table. Virtual columns for use with formulas are not implemented (requires explicit casting interface to be usable in postgres).
+
+The `UPDATE` is single-shot in any compliant database:
+- Either all rows matched are updated or none are.
+- Errors may occur for any of the usual reasons: a calculation error, or a check/unique constraint violation.
+- This can be used to design a query that updates zero rows if it fails to update any of them, something which usually requires a transaction.
+- Rows earlier in the statement do not affect later rows - the row updates are not 'sequenced'.
+
+## Limitations
+
+There is no support for `ORDER BY`, `LIMIT`, `OFFSET`, `GROUP` or `HAVING` clauses in the relation.
+
+The implementation does not automatically batch (nor reject) impermissibly large queries. The size of the values table is `rows * columns` when all rows assign to the same columns, or `rows * (distinct_columns + 1)` when the assign columns are not uniform (an extra bitmask indicator column is used).
+
+## Examples
+
+The query's skeleton looks like this:
+```sql
+--- postgres
+UPDATE "books" SET "name" = "t"."column2"
+FROM "books" JOIN (VALUES (1, 'C++'), (2, 'Web'), ...) "t" ON "books"."id" = "t"."column1"
+WHERE ...
+```
+
+Example use cases:
+- Offset `position` in a set of many ordered records after an element is added or removed from the middle of the list.
+- Decrement (or increment) `stock` or `balance` simultaneously in multiple rows by different amounts, noop-ing if any value would go outside permissible bounds. => add/subtract formula with database types or check constraints
+
+
+## Testing & Development
+
+It is important to test both MariaDB and MySQL: their values table semantics differ significantly.
+
+```bash
+# setup local test databases
+bundle exec rake db:prepare:postgresql
+bundle exec rake db:prepare:mysql2
+
+# run on local databases, force rebuilds schemas
+bundle exec rake test:sqlite3
+bundle exec rake test:postgresql
+bundle exec rake test:mysql2
+
+# run on docker-compose databases
+bin/test-docker sqlite3
+bin/test-docker postgresql
+bin/test-docker mysql2
+bin/test-docker mariadb
+
+bundle exec rubocop -a
+```

data/lib/activerecord-updateinbulk/adapters/abstract_adapter.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module ActiveRecord::UpdateInBulk
+  module AbstractAdapter
+    # Whether the database supports the SQL VALUES table constructor.
+    def supports_values_tables?
+      true
+    end
+
+    # A string prepended to each row literal in the VALUES table constructor.
+    # Empty by default, per the standard. MySQL overrides this to <tt>"ROW"</tt>
+    # to produce <tt>VALUES ROW(1, 2), ROW(3, 4)</tt>.
+    def values_table_row_prefix
+      ""
+    end
+
+    # Whether VALUES table serialization must always include explicit column
+    # aliases (because defaults are missing or not statically known).
+    def values_table_requires_aliasing?
+      false
+    end
+
+    # Returns an array of +width+ column names used by the database for a
+    # VALUES table constructor of the given width. These are the native names
+    # assigned to each column position when values_table_requires_aliasing?
+    # is false; otherwise they are alias conventions.
+    def values_table_default_column_names(width)
+      (1..width).map { |i| "column#{i}" }
+    end
+
+    # Hook for adapters that add explicit type casts to VALUES table entries
+    # so column types are correctly inferred by the database.
+    #
+    # Receives the +values_table+ (<tt>Arel::Nodes::ValuesTable</tt>) and
+    # +columns+ (an array of <tt>ActiveRecord::ConnectionAdapters::Column</tt>).
+    #
+    # Returns the typecasted Arel node: a new node or +values_table+ itself,
+    # possibly modified in place.
+    def typecast_values_table(values_table, _columns)
+      values_table
+    end
+  end
+end
+
+ActiveRecord::ConnectionAdapters::AbstractAdapter.include(ActiveRecord::UpdateInBulk::AbstractAdapter)

data/lib/activerecord-updateinbulk/adapters/abstract_mysql_adapter.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "active_record/connection_adapters/abstract_mysql_adapter"
+
+module ActiveRecord::UpdateInBulk
+  module AbstractMysqlAdapter
+    def supports_values_tables?
+      mariadb? ? database_version >= "10.3.3" : database_version >= "8.0.19"
+    end
+
+    def values_table_row_prefix
+      mariadb? ? "" : "ROW"
+    end
+
+    def values_table_default_column_names(width)
+      if mariadb?
+        (1..width).map { |i| "column#{i}" } # convention
+      else
+        (0...width).map { |i| "column_#{i}" }
+      end
+    end
+
+    # MariaDB always requires aliasing since there are no fixed column names
+    def values_table_requires_aliasing?
+      mariadb?
+    end
+  end
+end
+
+ActiveRecord::ConnectionAdapters::AbstractMysqlAdapter.include(ActiveRecord::UpdateInBulk::AbstractMysqlAdapter)

data/lib/activerecord-updateinbulk/adapters/postgresql_adapter.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "active_record/connection_adapters/postgresql_adapter"
+
+module ActiveRecord::UpdateInBulk
+  module PostgreSQLAdapter
+    SAFE_TYPES_FOR_VALUES_TABLE = [:integer, :string, :text, :boolean].freeze
+
+
+    def typecast_values_table(values_table, columns)
+      types = columns.map.with_index do |column, index|
+        case column
+        when ActiveRecord::ConnectionAdapters::PostgreSQL::Column
+          if SAFE_TYPES_FOR_VALUES_TABLE.exclude?(column.type) ||
+              values_table.rows.all? { |row| row[index].nil? }
+            column.sql_type
+          end
+        when Arel::Nodes::SqlLiteral, nil
+          column
+        else
+          raise ArgumentError, "Unexpected column type: #{column.class.name}"
+        end
+      end
+
+      return values_table if types.all?(&:nil?)
+
+      aliases = values_table.columns
+      default_columns = values_table_default_column_names(values_table.width)
+      values_table = Arel::Nodes::ValuesTable.new(values_table.name, values_table.rows, default_columns)
+
+      # from("t") is not required in postgres 16+, can be from(nil)
+      values_table.from("t").project((0...values_table.width).map do |index|
+        proj = Arel::Nodes::UnqualifiedColumn.new(values_table[index])
+        proj = proj.cast(proj, Arel.sql(types[index])) if types[index]
+        proj = proj.as(Arel::Nodes::UnqualifiedColumn.new(aliases[index])) if aliases[index] != default_columns[index]
+        proj
+      end)
+    end
+  end
+end
+
+ActiveRecord::ConnectionAdapters::PostgreSQLAdapter.include(ActiveRecord::UpdateInBulk::PostgreSQLAdapter)

data/lib/activerecord-updateinbulk/adapters/sqlite3_adapter.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "active_record/connection_adapters/sqlite3_adapter"
+
+module ActiveRecord::UpdateInBulk
+  module SQLite3Adapter
+  end
+end
+
+ActiveRecord::ConnectionAdapters::SQLite3Adapter.include(ActiveRecord::UpdateInBulk::SQLite3Adapter)

data/lib/activerecord-updateinbulk/arel/math.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Arel
+  module Math
+    def least(other)
+      lhs = is_a?(Arel::Nodes::Least) ? self.expressions : [self]
+      rhs = other.is_a?(Arel::Nodes::Least) ? other.expressions : [other]
+      Arel::Nodes::Least.new(lhs + rhs)
+    end
+
+    def greatest(other)
+      lhs = is_a?(Arel::Nodes::Greatest) ? self.expressions : [self]
+      rhs = other.is_a?(Arel::Nodes::Greatest) ? other.expressions : [other]
+      Arel::Nodes::Greatest.new(lhs + rhs)
+    end
+  end
+end

data/lib/activerecord-updateinbulk/arel/nodes/greatest.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Arel::Nodes
+  class Greatest < Function
+  end
+end

data/lib/activerecord-updateinbulk/arel/nodes/least.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Arel::Nodes
+  class Least < Function
+  end
+end

data/lib/activerecord-updateinbulk/arel/nodes/values_table.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Arel::Nodes
+  # Represents a SQL VALUES table constructor as an Arel node.
+  # Mirrors Arel::Table behavior by requiring a name at construction time.
+  # Column names are also required because adapter defaults vary; obtain
+  # defaults through <tt>connection.values_table_default_column_names(width)</tt>.
+  #
+  class ValuesTable < Arel::Nodes::Node
+    attr_reader :name, :width, :rows, :columns
+    alias :table_alias :name
+
+    # +name+    - The table name (required to mirror Arel::Table).
+    # +rows+    - An array of arrays; each inner array is one row of values.
+    # +columns+ - An array of column name strings, typically from
+    #             <tt>connection.values_table_default_column_names(width)</tt>.
+    def initialize(name, rows, columns)
+      @name = name.to_s
+      @width = rows.first.size
+      @rows = rows
+      @columns = columns.map(&:to_s)
+    end
+
+    def [](name, table = self)
+      name = columns[name] if name.is_a?(Integer)
+      name = name.name if name.is_a?(Symbol)
+      Arel::Attribute.new(table, name)
+    end
+
+    def from(table = name)
+      Arel::SelectManager.new(table ? self.alias(table) : grouping(self))
+    end
+
+    def alias(table = name)
+      Arel::Nodes::TableAlias.new(grouping(self), table)
+    end
+
+    delegate :to_cte, to: :alias
+
+    def hash
+      [@name, @rows, @columns].hash
+    end
+
+    def eql?(other)
+      @name == other.name && @rows == other.rows && @columns == other.columns
+    end
+    alias :== :eql?
+  end
+end

data/lib/activerecord-updateinbulk/arel/select_manager.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module ActiveRecord::UpdateInBulk
+  module SelectManager
+    def alias(name)
+      Arel::Nodes::TableAlias.new(self, name)
+    end
+  end
+end
+
+Arel::SelectManager.include(ActiveRecord::UpdateInBulk::SelectManager)

data/lib/activerecord-updateinbulk/arel/visitors/sqlite.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module ActiveRecord::UpdateInBulk
+  module SQLiteToSql
+    private
+      def visit_Arel_Nodes_Least(o, collector)
+        collector << "MIN("
+        inject_join(o.expressions, collector, ", ")
+        collector << ")"
+      end
+
+      def visit_Arel_Nodes_Greatest(o, collector)
+        collector << "MAX("
+        inject_join(o.expressions, collector, ", ")
+        collector << ")"
+      end
+  end
+end
+
+Arel::Visitors::SQLite.prepend(ActiveRecord::UpdateInBulk::SQLiteToSql)

data/lib/activerecord-updateinbulk/arel/visitors/to_sql.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module ActiveRecord::UpdateInBulk
+  module ToSql
+    def visit_Arel_Nodes_Least(o, collector)
+      collector << "LEAST("
+      inject_join(o.expressions, collector, ", ")
+      collector << ")"
+    end
+
+    def visit_Arel_Nodes_Greatest(o, collector)
+      collector << "GREATEST("
+      inject_join(o.expressions, collector, ", ")
+      collector << ")"
+    end
+
+    def visit_Arel_Nodes_ValuesTable(o, collector)
+      row_prefix = @connection.values_table_row_prefix
+
+      if !@connection.values_table_requires_aliasing? && o.columns == @connection.values_table_default_column_names(o.width)
+        return build_values_table_constructor(o.rows, collector, row_prefix)
+      end
+
+      column_aliases = o.columns
+
+      # Extract the first row into a handrolled SELECT and put the aliases there.
+      collector << "SELECT "
+      o.rows[0].each_with_index do |value, i|
+        collector << ", " unless i == 0
+        collector = build_values_table_single_value(value, collector)
+        collector << " " << quote_column_name(column_aliases[i])
+      end
+      unless o.rows.size == 1
+        collector << " UNION ALL "
+        collector = build_values_table_constructor(o.rows[1...], collector, row_prefix)
+      end
+      collector
+    end
+
+    private
+      def build_values_table_single_value(value, collector)
+        case value
+        when Arel::Nodes::SqlLiteral, Arel::Nodes::BindParam, ActiveModel::Attribute
+          visit(value, collector)
+        else
+          collector << quote(value).to_s
+        end
+      end
+
+      def build_values_table_constructor(rows, collector, row_prefix = "")
+        collector << "VALUES "
+        rows.each_with_index do |row, i|
+          collector << ", " unless i == 0
+          collector << row_prefix << "("
+          row.each_with_index do |value, i|
+            collector << ", " unless i == 0
+            collector = build_values_table_single_value(value, collector)
+          end
+          collector << ")"
+        end
+        collector
+      end
+  end
+end
+
+Arel::Visitors::ToSql.prepend(ActiveRecord::UpdateInBulk::ToSql)

data/lib/activerecord-updateinbulk/base.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "active_record"
+
+module ActiveRecord
+  module UpdateInBulk
+    ADAPTER_PATH = "activerecord-updateinbulk/adapters"
+    ADAPTER_EXTENSION_MAP = {
+      "mysql2" => "abstract_mysql",
+      "trilogy" => "abstract_mysql",
+    }
+
+    def self.require_adapter(adapter)
+      adapter = ADAPTER_EXTENSION_MAP.fetch(adapter, adapter)
+      require File.join(ADAPTER_PATH, "#{adapter}_adapter")
+    end
+
+    def self.load_from_connection_pool(connection_pool)
+      require_adapter connection_pool.db_config.adapter
+    end
+  end
+end
+
+require "activerecord-updateinbulk/builder"
+require "activerecord-updateinbulk/arel/math"
+require "activerecord-updateinbulk/arel/nodes/least"
+require "activerecord-updateinbulk/arel/nodes/greatest"
+require "activerecord-updateinbulk/arel/nodes/values_table"
+require "activerecord-updateinbulk/arel/visitors/to_sql"
+require "activerecord-updateinbulk/arel/visitors/sqlite"
+require "activerecord-updateinbulk/arel/select_manager"
+require "activerecord-updateinbulk/relation"
+require "activerecord-updateinbulk/querying"
+
+require "activerecord-updateinbulk/adapters/abstract_adapter"
+
+module ActiveRecord::UpdateInBulk
+  module ConnectionHandler
+    def establish_connection(*args, **kwargs, &block)
+      pool = super(*args, **kwargs, &block)
+      ActiveRecord::UpdateInBulk.load_from_connection_pool pool
+      pool
+    end
+  end
+end
+
+ActiveRecord::ConnectionAdapters::ConnectionHandler.prepend(ActiveRecord::UpdateInBulk::ConnectionHandler)

data/lib/activerecord-updateinbulk/builder.rb

@@ -0,0 +1,312 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/enumerable"
+
+module ActiveRecord::UpdateInBulk
+  class Builder
+    FORMULAS = %w[add subtract concat_append concat_prepend min max].freeze
+
+    class << self
+      attr_accessor :values_table_name
+
+      # Normalize all input formats into separated format [conditions, assigns].
+      def normalize_updates(model, updates, values = nil)
+        conditions = []
+        assigns = []
+
+        if values # separated format
+          unless updates.is_a?(Array) && values.is_a?(Array)
+            raise ArgumentError, "Separated format expects arrays for conditions and values"
+          end
+          if updates.size != values.size
+            raise ArgumentError, "Conditions and values must have the same length"
+          end
+
+          updates.each_with_index do |row_conditions, index|
+            row_assigns = values[index]
+            next if row_assigns.blank?
+            conditions << normalize_conditions(model, row_conditions)
+            assigns << row_assigns.stringify_keys
+          end
+        elsif updates.is_a?(Hash) # indexed format
+          updates.each do |id, row_assigns|
+            next if row_assigns.blank?
+            conditions << normalize_conditions(model, id)
+            assigns << row_assigns.stringify_keys
+          end
+        else # paired format
+          updates.each do |(row_conditions, row_assigns)|
+            next if row_assigns.blank?
+            conditions << normalize_conditions(model, row_conditions)
+            assigns << row_assigns.stringify_keys
+          end
+        end
+
+        [conditions, assigns]
+      end
+
+      def apply_formula(formula, lhs, rhs, model)
+        case formula
+        when "add"
+          lhs + rhs
+        when "subtract"
+          lhs - rhs
+        when "concat_append"
+          lhs.concat(rhs)
+        when "concat_prepend"
+          rhs.concat(lhs)
+        when "min"
+          lhs.least(rhs)
+        when "max"
+          lhs.greatest(rhs)
+        when Proc
+          node = apply_proc_formula(formula, lhs, rhs, model)
+          unless Arel.arel_node?(node)
+            raise ArgumentError, "Custom formula must return an Arel node"
+          end
+          node
+        else
+          rhs
+        end
+      end
+
+      def apply_proc_formula(formula, lhs, rhs, model)
+        case formula.arity
+        when 2
+          formula.call(lhs, rhs)
+        when 3
+          formula.call(lhs, rhs, model)
+        else
+          raise ArgumentError, "Custom formula must accept 2 or 3 arguments"
+        end
+      end
+
+      private
+        def normalize_conditions(model, conditions)
+          if conditions.is_a?(Hash)
+            conditions
+          elsif model.composite_primary_key?
+            primary_key_zip(model.primary_key, conditions)
+          else
+            { model.primary_key => primary_key_unwrap(conditions) }
+          end.stringify_keys
+        end
+
+        def primary_key_zip(keys, values)
+          unless values.is_a?(Array)
+            raise ArgumentError, "Model has composite primary key, but a condition key given is not an array"
+          end
+          if keys.size != values.size
+            raise ArgumentError, "Model primary key has length #{keys.size}, but condition key given has length #{values.size}"
+          end
+          keys.zip(values).to_h
+        end
+
+        def primary_key_unwrap(value)
+          if !value.is_a?(Array)
+            value
+          elsif value.size == 1
+            value.first
+          else
+            raise ArgumentError, "Expected a single value, but got #{value.inspect}"
+          end
+        end
+    end
+    self.values_table_name = "t"
+
+    attr_reader :model, :connection
+
+    def initialize(relation, connection, conditions, assigns, record_timestamps: nil, formulas: nil)
+      @model, @connection = relation.model, connection
+      @record_timestamps = record_timestamps.nil? ? model.record_timestamps : record_timestamps
+      @conditions = conditions
+      @assigns = assigns
+      @formulas = normalize_formulas(formulas)
+
+      resolve_attribute_aliases!
+      resolve_read_and_write_keys!
+      verify_read_and_write_keys!
+    end
+
+    def build_arel
+      values_table, bitmask_keys = build_values_table
+      join_conditions = build_join_conditions(model.arel_table, values_table)
+      set_assignments = build_set_assignments(model.arel_table, values_table, bitmask_keys)
+      derived_table = typecast_values_table(values_table)
+
+      [derived_table, join_conditions, set_assignments]
+    end
+
+    private
+      attr_reader :read_keys, :write_keys
+
+      def optional_keys
+        @optional_keys ||= write_keys - @assigns.map(&:keys).reduce(write_keys, &:intersection)
+      end
+
+      def timestamp_keys
+        @timestamp_keys ||= @record_timestamps ? model.timestamp_attributes_for_update_in_model.to_set - write_keys : Set.new
+      end
+
+      def build_values_table
+        types = (read_keys | write_keys).index_with { |key| model.type_for_attribute(key) }
+        rows, bitmask_keys = serialize_values_rows do |key, value|
+          next value if Arel::Nodes::SqlLiteral === value
+          ActiveModel::Type::SerializeCastValue.serialize(type = types[key], type.cast(value))
+        end
+        append_bitmask_column(rows, bitmask_keys) unless bitmask_keys.empty?
+        values_table = Arel::Nodes::ValuesTable.new(self.class.values_table_name, rows, connection.values_table_default_column_names(rows.first.size))
+        [values_table, bitmask_keys]
+      end
+
+      def build_join_conditions(table, values_table)
+        read_keys.map.with_index do |key, index|
+          table[key].eq(values_table[index])
+        end
+      end
+
+      def build_set_assignments(table, values_table, bitmask_keys)
+        bitmask_functions = bitmask_keys.index_with.with_index(1) do |key, index|
+          Arel::Nodes::NamedFunction.new("SUBSTRING", [values_table[-1], index, 1])
+        end
+
+        set_assignments = write_keys.map.with_index do |key, index|
+          formula = @formulas[key]
+          lhs = table[key]
+          rhs = values_table[index + read_keys.size]
+          rhs = self.class.apply_formula(formula, lhs, rhs, model) if formula
+          if function = bitmask_functions[key]
+            rhs = Arel::Nodes::Case.new(function).when("1").then(rhs).else(table[key])
+          elsif optional_keys.include?(key)
+            rhs = table.coalesce(rhs, table[key])
+          end
+          [table[key], rhs]
+        end
+
+        if timestamp_keys.any?
+          set_assignments += timestamp_assignments(set_assignments)
+        end
+
+        set_assignments
+      end
+
+      def typecast_values_table(values_table)
+        columns_hash = model.columns_hash
+        model_types = read_keys.to_a.concat(write_keys.to_a).map! { |key| columns_hash.fetch(key) }
+        connection.typecast_values_table(values_table, model_types).alias(self.class.values_table_name)
+      end
+
+      def serialize_values_rows(&)
+        bitmask_keys = Set.new
+
+        rows = @conditions.each_with_index.map do |row_conditions, row_index|
+          row_assigns = @assigns[row_index]
+          condition_values = read_keys.map do |key|
+            yield(key, row_conditions[key])
+          end
+          write_values = write_keys.map do |key|
+            next unless row_assigns.key?(key)
+            value = yield(key, row_assigns[key])
+            bitmask_keys.add(key) if optional_keys.include?(key) && might_be_nil_value?(value)
+            value
+          end
+          condition_values.concat(write_values)
+        end
+
+        [rows, bitmask_keys]
+      end
+
+      def append_bitmask_column(rows, bitmask_keys)
+        rows.each_with_index do |row, row_index|
+          row_assigns = @assigns[row_index]
+          bitmask = "0" * bitmask_keys.size
+          bitmask_keys.each_with_index do |key, index|
+            bitmask[index] = "1" if row_assigns.key?(key)
+          end
+          row.push(bitmask)
+        end
+      end
+
+      def timestamp_assignments(set_assignments)
+        case_conditions = set_assignments.map do |left, right|
+          left.is_not_distinct_from(right)
+        end
+
+        timestamp_keys.map do |key|
+          case_assignment = Arel::Nodes::Case.new.when(Arel::Nodes::And.new(case_conditions))
+                                             .then(model.arel_table[key])
+                                             .else(connection.high_precision_current_timestamp)
+          [model.arel_table[key], Arel::Nodes::Grouping.new(case_assignment)]
+        end
+      end
+
+      # When you assign a value to NULL, we need to use a bitmask to distinguish that
+      # row in the values table from rows where the column is not to be assigned at all.
+      def might_be_nil_value?(value)
+        value.nil? || value.is_a?(Arel::Nodes::SqlLiteral) || value.is_a?(Arel::Nodes::BindParam)
+      end
+
+      def normalize_formulas(formulas)
+        return {} if formulas.blank?
+
+        normalized = formulas.to_h do |key, value|
+          [key.to_s, value.is_a?(Proc) ? value : value.to_s]
+        end
+        invalid = normalized.values.reject { |v| v.is_a?(Proc) } - FORMULAS
+        if invalid.any?
+          raise ArgumentError, "Unknown formula: #{invalid.first.inspect}"
+        end
+        normalized
+      end
+
+      def resolve_attribute_aliases!
+        return if model.attribute_aliases.empty?
+
+        @conditions.each_with_index do |row_conditions, index|
+          row_assigns = @assigns[index]
+          row_conditions.transform_keys! { |attribute| model.attribute_alias(attribute) || attribute }
+          row_assigns.transform_keys! { |attribute| model.attribute_alias(attribute) || attribute }
+        end
+      end
+
+      def resolve_read_and_write_keys!
+        @read_keys = @conditions.first.keys.to_set
+        @write_keys = @assigns.flat_map(&:keys).to_set
+      end
+
+      def verify_read_and_write_keys!
+        if @conditions.empty?
+          raise ArgumentError, "Empty updates object"
+        end
+        if read_keys.empty?
+          raise ArgumentError, "Empty conditions object"
+        end
+        if write_keys.empty?
+          raise ArgumentError, "Empty values object"
+        end
+
+        @conditions.each_with_index do |row_conditions, index|
+          row_assigns = @assigns[index]
+          if row_conditions.each_value.any?(nil)
+            raise NotImplementedError, "NULL condition values are not supported"
+          end
+          if row_assigns.blank?
+            raise ArgumentError, "Empty values object"
+          end
+          if read_keys != row_conditions.keys.to_set
+            raise ArgumentError, "All objects being updated must have the same condition keys"
+          end
+        end
+        if @formulas.any?
+          unknown_formula_key = (@formulas.keys.to_set - write_keys).first
+          if unknown_formula_key
+            raise ArgumentError, "Formula given for unknown column: #{unknown_formula_key}"
+          end
+        end
+
+        columns = read_keys | write_keys
+        unknown_column = (columns - model.columns_hash.keys).first
+        raise ActiveRecord::UnknownAttributeError.new(model.new, unknown_column) if unknown_column
+      end
+  end
+end

data/lib/activerecord-updateinbulk/querying.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module ActiveRecord::UpdateInBulk
+  module Querying
+    def update_in_bulk(...)
+      all.update_in_bulk(...)
+    end
+  end
+end
+
+ActiveRecord::Querying.prepend(ActiveRecord::UpdateInBulk::Querying)

data/lib/activerecord-updateinbulk/railtie.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+module ActiveRecord
+  module UpdateInBulk
+    class Railtie < Rails::Railtie
+      config.active_record_update_in_bulk = ActiveSupport::OrderedOptions.new
+
+      initializer "active_record_update_in_bulk.values_table_alias", after: :load_config_initializers do |app|
+        if (bulk_alias = app.config.active_record_update_in_bulk.values_table_alias)
+          unless bulk_alias.instance_of?(String) && !bulk_alias.empty?
+            raise ArgumentError, "values_table_alias must be a non-empty String"
+          end
+          ActiveRecord::UpdateInBulk::Builder.values_table_name = bulk_alias
+        end
+      end
+    end
+  end
+end

data/lib/activerecord-updateinbulk/relation.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module ActiveRecord::UpdateInBulk
+  module Relation
+    # Updates multiple groups of records in the current relation using a single
+    # SQL UPDATE statement. This does not instantiate models and does not
+    # trigger Active Record callbacks or validations. However, values passed
+    # through still use Active Record's normal type casting and serialization.
+    # Returns the number of rows affected.
+    #
+    # Three equivalent input formats are supported:
+    #
+    # *Indexed format* — a hash mapping primary keys to attribute updates:
+    #
+    #   Book.update_in_bulk({
+    #     1 => { title: "Agile", price: 10.0 },
+    #     2 => { title: "Rails" }
+    #   })
+    #
+    # Composite primary keys are supported:
+    #
+    #   FlightSeat.update_in_bulk({
+    #     ["AA100", "12A"] => { passenger: "Alice" },
+    #     ["AA100", "12B"] => { passenger: "Bob" }
+    #   })
+    #
+    # *Paired format* — an array of <tt>[conditions, assigns]</tt> pairs.
+    # Conditions do not need to be primary keys; they may reference any columns in
+    # the target table. All pairs must specify the same set of condition
+    # columns:
+    #
+    #   Employee.update_in_bulk([
+    #     [{ department: "Sales" },       { bonus: 2500 }],
+    #     [{ department: "Engineering" }, { bonus: 500 }]
+    #   ])
+    #
+    # *Separated format* — parallel arrays of conditions and assigns:
+    #
+    #   Employee.update_in_bulk(
+    #     [1, 2, { id: 3 }],
+    #     [{ salary: 75_000 }, { salary: 80_000 }, { salary: 68_000 }]
+    #   )
+    #
+    # ==== Options
+    #
+    # [:record_timestamps]
+    #   By default, automatic setting of timestamp columns is controlled by
+    #   the model's <tt>record_timestamps</tt> config, matching typical
+    #   behavior. Timestamps are only bumped when the row actually changes.
+    #
+    #   To override this and force automatic setting of timestamp columns one
+    #   way or the other, pass <tt>:record_timestamps</tt>.
+    #
+    # [:formulas]
+    #   A hash of column names to formula identifiers or Procs. Instead of
+    #   a simple assignment, the column is set to an expression that can
+    #   reference both the current selected row value and the incoming value.
+    #
+    #   Built-in formulas: <tt>:add</tt>, <tt>:subtract</tt>, <tt>:min</tt>,
+    #   <tt>:max</tt>, <tt>:concat_append</tt>, <tt>:concat_prepend</tt>.
+    #
+    #     Inventory.update_in_bulk({
+    #       "Christmas balls" => { quantity: 73 },
+    #       "Christmas tree"  => { quantity: 1 }
+    #     }, formulas: { quantity: :subtract })
+    #
+    #   Custom formulas are supported via a Proc that takes
+    #   <tt>(lhs, rhs)</tt> or <tt>(lhs, rhs, model)</tt> and returns an
+    #   Arel node:
+    #
+    #     add_capped = ->(lhs, rhs) { lhs.least(lhs + rhs) }
+    #     Inventory.update_in_bulk(updates, formulas: { quantity: add_capped })
+    #
+    # ==== Examples
+    #
+    #   # Migration to combine two columns into one for all entries in a table.
+    #   Book.update_in_bulk([
+    #     [{ written: false, published: false }, { status: :proposed }],
+    #     [{ written: true,  published: false }, { status: :written }],
+    #     [{ written: true,  published: true },  { status: :published }]
+    #   ], record_timestamps: false)
+    #
+    #   # Relation scoping is preserved.
+    #   Employee.where(active: true).update_in_bulk({
+    #     1 => { department: "Engineering" },
+    #     2 => { department: "Sales" }
+    #   })
+    #
+    def update_in_bulk(updates, values = nil, record_timestamps: nil, formulas: nil)
+      unless limit_value.nil? && offset_value.nil? && order_values.empty? && group_values.empty? && having_clause.empty?
+        raise NotImplementedError, "No support to update grouped or ordered relations (offset, limit, order, group, having clauses)"
+      end
+
+      conditions, assigns = Builder.normalize_updates(model, updates, values)
+      return 0 if @none || conditions.empty?
+
+      model.with_connection do |c|
+        unless c.supports_values_tables?
+          raise ArgumentError, "#{c.class} does not support VALUES table constructors"
+        end
+
+        arel = eager_loading? ? apply_join_dependency.arel : arel()
+        arel.source.left = table
+
+        values_table, join_conditions, set_assignments = Builder.new(
+          self,
+          c,
+          conditions,
+          assigns,
+          record_timestamps:,
+          formulas:
+        ).build_arel
+        arel = arel.join(values_table).on(*join_conditions)
+
+        key = if model.composite_primary_key?
+          primary_key.map { |pk| table[pk] }
+        else
+          table[primary_key]
+        end
+        stmt = arel.compile_update(set_assignments, key)
+        c.update(stmt, "#{model} Update in Bulk").tap { reset }
+      end
+    end
+  end
+end
+
+ActiveRecord::Relation.prepend(ActiveRecord::UpdateInBulk::Relation)

data/lib/activerecord-updateinbulk/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module UpdateInBulk
+    VERSION = "0.1.0"
+  end
+end

data/lib/activerecord-updateinbulk.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "active_support/lazy_load_hooks"
+
+ActiveSupport.on_load(:active_record) do
+  require "activerecord-updateinbulk/base"
+end
+
+require "activerecord-updateinbulk/railtie" if defined?(Rails::Railtie)

metadata

@@ -0,0 +1,92 @@
+--- !ruby/object:Gem::Specification
+name: activerecord-updateinbulk
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Bruno Carvalho
+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.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Introduces update_in_bulk(), a method to update many records in a table
+  with different values in a single SQL statement.
+email:
+- bruno.carvalho.feup@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/activerecord-updateinbulk.rb
+- lib/activerecord-updateinbulk/adapters/abstract_adapter.rb
+- lib/activerecord-updateinbulk/adapters/abstract_mysql_adapter.rb
+- lib/activerecord-updateinbulk/adapters/postgresql_adapter.rb
+- lib/activerecord-updateinbulk/adapters/sqlite3_adapter.rb
+- lib/activerecord-updateinbulk/arel/math.rb
+- lib/activerecord-updateinbulk/arel/nodes/greatest.rb
+- lib/activerecord-updateinbulk/arel/nodes/least.rb
+- lib/activerecord-updateinbulk/arel/nodes/values_table.rb
+- lib/activerecord-updateinbulk/arel/select_manager.rb
+- lib/activerecord-updateinbulk/arel/visitors/sqlite.rb
+- lib/activerecord-updateinbulk/arel/visitors/to_sql.rb
+- lib/activerecord-updateinbulk/base.rb
+- lib/activerecord-updateinbulk/builder.rb
+- lib/activerecord-updateinbulk/querying.rb
+- lib/activerecord-updateinbulk/railtie.rb
+- lib/activerecord-updateinbulk/relation.rb
+- lib/activerecord-updateinbulk/version.rb
+homepage: https://github.com/bruno/activerecord-updateinbulk
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/bruno/activerecord-updateinbulk/issues
+  homepage_uri: https://github.com/bruno/activerecord-updateinbulk
+  source_code_uri: https://github.com/bruno/activerecord-updateinbulk
+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: 3.6.9
+specification_version: 4
+summary: Bulk update extension for ActiveRecord
+test_files: []