bulk_destroyer 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 49ddeb360222e4f193bd0d67f64e23ed280f700349251326eb72f96983e5f2a0
+  data.tar.gz: 02ed589f50098a4029101b2b0550e474f9e31ef7bec9b65d0d87eedce23ee815
+SHA512:
+  metadata.gz: b423cefd1a3cd77f72efee55ade3d8f75ff463087dc1d229cbac158cee2ad7c79359557263594bcbd3254ed358d21aac5c59bcf6d2f01aaa1622470f19b8717f
+  data.tar.gz: 1952408bf68dcf19ead6f2ca32626341feca96802c78b198039dfa00ab0c14cf6db9f8a93770dbe1b8fc3032866707d6f9ae7466e1ddfee57167e90d7b29bfb8

data/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 0.1.0 - 2026-10-22
+
+- Initial release: `bulk_destroy_all` and `bulk_destroy!`.
+- Fires all destroy callbacks (including children's) with set-based SQL; `after_destroy` runs after the bulk DELETE (Fiber mode).
+- Supports `dependent:` :destroy, :delete_all, :nullify, restrict_*, has_many :through, HABTM, and `belongs_to` :destroy/:delete.
+- `max_batch_records` / `oversized_tree` guard against the Fiber ceiling.
+- Rails 7.1 - 8.2, any ActiveRecord adapter (tested on SQLite and PostgreSQL).

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ramanan
+
+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,193 @@
+# BulkDestroyer
+
+`destroy_all` that fires **every destroy callback on every record** (including `dependent: :destroy`
+descendants) but deletes with set-based SQL.
+
+```ruby
+Post.where(archived: true).bulk_destroy_all            # => { "Post" => 120, "Comment" => 940, ... }
+Post.bulk_destroy_all(batch_size: 500)
+post.comments.bulk_destroy_all
+post.bulk_destroy!
+```
+
+See [Benchmarks](#benchmarks) for timings. Query count is roughly one SELECT per association per level plus one DELETE
+per 500 ids (`in_list_size`) per table, repeated for each batch of `batch_size` roots. It still grows with the
+data, but about 700x more slowly than `destroy_all`'s two-plus queries per row (32,001 vs 45 queries at 1,000
+posts, 160,001 vs 221 at 5,000).
+
+## How it works
+
+Per batch of roots (default 1000, and never more than `max_batch_records` records; see below), inside one
+transaction (`requires_new: true`):
+
+1. **Tree** - `ActiveRecord::Associations::Preloader` loads each `dependent: :destroy` association
+   once per level. Association scopes, `foreign_key`/`primary_key`, polymorphic `as:` and STI are
+   handled by Rails. A record reachable by several paths is placed at its deepest level.
+2. **Restrictions** - `restrict_with_exception` / `restrict_with_error` are checked first.
+3. **Start hooks** - each record's real `run_callbacks(:destroy)` runs inside a `Fiber` up to the
+   point where Rails would delete the row (before_destroy, first half of around_destroy), parents first.
+4. **Per level, deepest first** - `nullify` / `delete_all` / HABTM join rows, then one bulk `DELETE`
+   per table, then counter caches, then the records are marked destroyed and their fibers resume
+   (second half of around_destroy, `after_destroy`).
+
+Because Rails runs the callback chain itself, `if:`/`unless:`, `prepend:`, callback objects, ordering
+and `throw :abort` behave as in `destroy`. `after_destroy` really runs after the row is gone, and a
+child's `after_destroy` runs while its parent's row still exists (same as `destroy`).
+
+`after_commit` / `after_rollback` work: records are registered with the transaction exactly as
+`destroy` registers them, so Active Storage purges etc. fire at commit, and a rolled-back batch
+restores `destroyed?`.
+
+## Association support
+
+| Association | How it is handled | Covered by a test |
+|---|---|---|
+| `has_many` / `has_one`, `dependent: :destroy` | children loaded once per level, destroyed with their hooks | yes |
+| polymorphic `has_many ... as:`, `dependent: :destroy` | same, type column respected | yes (likes on posts and comments) |
+| polymorphic `as:`, `dependent: :delete_all` / `:nullify` | one `DELETE` / `UPDATE` filtered by owner id **and** type; nullify clears the type column too | yes (two classes sharing an id) |
+| `has_many :through` (plain `has_many` for the join, `dependent: :destroy` there) | join rows destroyed, far side untouched | yes |
+| `has_many :through ..., dependent: :destroy` on the through association itself | join records destroyed with their hooks, far side untouched (same as Rails) | yes, compared with stock `destroy_all` |
+| `has_and_belongs_to_many` | join rows deleted without callbacks (Rails does the same), from either side; far side untouched | yes |
+| `belongs_to ..., dependent: :destroy` / `:delete`, polymorphic and `delegated_type` | target destroyed after its owners, see below | yes |
+| `dependent: :restrict_with_exception` / `:restrict_with_error` | checked before any hook runs | exception form only |
+| `dependent: :destroy_async`, nested `:through` with `dependent:` | raises `BulkDestroyer::UnsupportedAssociation` | `destroy_async` only |
+
+The hash returned by `bulk_destroy_all` counts rows deleted per table, including `dependent: :delete_all` rows and
+`dependent: :delete` targets. HABTM join rows and `nullify`d rows are not counted.
+
+## Differences from `destroy_all` (by design)
+
+- All `before_destroy` hooks run before any row is deleted, rather than interleaved with child deletion.
+- `throw :abort` / a failing hook rolls back the **whole batch** and raises
+  `ActiveRecord::RecordNotDestroyed` (or the hook's own error). There is no per-record skipping.
+  Batches are separate transactions; wrap the call in your own `transaction` for all-or-nothing.
+  A hook that raises `ActiveRecord::Rollback` is treated the same way: Rails' `transaction` would swallow it
+  and the batch would silently disappear, so the gem raises `ActiveRecord::RecordNotDestroyed` instead.
+- `has_many :through, dependent: :destroy` and `has_and_belongs_to_many` remove join rows only (as Rails does).
+- `belongs_to ..., dependent: :destroy` / `:delete` (this is what `delegated_type ..., dependent: :destroy` declares)
+  is supported. Rails destroys that target from the owner's `after_destroy`, so here each level of owners is
+  deleted first and then their targets are destroyed in a nested pass inside the same transaction, with their
+  own hooks, children and further `belongs_to` targets. Targets are preloaded (one query per target class,
+  polymorphic included), a target shared by several owners is destroyed once, and models that destroy each
+  other (`Slot belongs_to :holder, dependent: :destroy` / `Memo has_one :slot, dependent: :destroy`) terminate.
+  A target whose `before_destroy` aborts rolls back the whole batch, owners included.
+- Counter caches are decremented with one grouped UPDATE per (column, amount) instead of one per row.
+- `touch: true` is a callback and still runs per record.
+- `destroy` itself is never called, so a model that overrides `destroy` (soft-delete gems) is bypassed.
+  Optimistic locking (`lock_version`) is not checked.
+
+## Not supported (raises `BulkDestroyer::UnsupportedAssociation`)
+
+`dependent: :destroy_async` (on any association), nested `:through`, `:nullify` on `:through`,
+and, for `delete_all`/`nullify`/`restrict`, composite foreign keys and instance-dependent scopes
+(`-> (owner) { ... }`). (`dependent: :destroy` goes through Rails' preloader and does not have the
+last two limits.)
+
+## Configuration
+
+```ruby
+BulkDestroyer.batch_size   = 1_000    # roots per transaction
+BulkDestroyer.in_list_size = 500      # values per IN (...) chunk, capped per adapter
+BulkDestroyer.hook_mode    = :fiber   # or :inline
+BulkDestroyer.max_batch_records = 10_000   # records with destroy hooks per batch (see below)
+BulkDestroyer.oversized_tree    = :raise   # or :inline, when ONE root's tree exceeds the cap
+```
+
+`:fiber` needs `ActiveSupport::IsolatedExecutionState.isolation_level == :thread` (the default) because
+hook fibers must share the caller's database connection; otherwise it raises `UnsupportedIsolation`.
+`:inline` runs the whole callback chain before the DELETE (so `after_destroy` still sees the row).
+Fiber-local `Thread.current[:x]` values are copied into the hook fibers.
+
+### The Fiber ceiling and `max_batch_records`
+
+In `:fiber` mode every record in a batch's tree keeps one paused Fiber until its level has been deleted, so a
+batch holds as many live Fibers as it has records with destroy hooks (the `batch_size` of 1000 counts roots, not
+records). Ruby on Linux fails with `FiberError: can't set a guard page` at about 31,700 live Fibers with the
+default `vm.max_map_count` of 65530 (two memory mappings per Fiber stack); measured on Ruby 3.4, trivial Fibers
+cost about 12 KB each, real hook stacks cost more. A tree of 700 posts with 50 comments each (35,700 records)
+used to fail this way and now works.
+
+To stay clear of it, the batch size is also capped by records:
+
+- If a batch's tree has more than `max_batch_records` records, **before any hook runs** the roots are split in
+  half and each half is run as its own batch (its own transaction), recursively. Everything still fires once;
+  you just get more, smaller batches. Splitting is not atomic across parts: wrap the call in your own
+  `transaction` if you need all-or-nothing.
+- Targets of `belongs_to ..., dependent:` (the nested pass) are split the same way, within the same transaction.
+- If a **single root's** tree alone exceeds the cap it cannot be split. By default
+  `BulkDestroyer::TreeTooLarge` is raised, before any hook runs and with nothing deleted. With
+  `oversized_tree = :inline` that batch runs its hooks without Fibers instead (its `after_destroy` hooks then run
+  before the DELETE).
+- The cap is per batch. Nested `belongs_to` batches run while the outer batch's remaining Fibers are still
+  paused, so keep `max_batch_records` well under half of the ceiling. The default of 10,000 does.
+- `:inline` mode creates no Fibers and ignores the cap.
+
+A paused Fiber has no timeout in Ruby or Rails; what stays open meanwhile is the database transaction, so the
+usual database and request timeouts apply to the whole call.
+
+## Testing
+
+```
+BULK_DESTROYER_DB=sqlite3|postgresql|trilogy|mysql2 bundle exec ruby -Itest test/bulk_destroyer_test.rb
+BULK_DESTROYER_HOOK_MODE=inline ...   # run the suite in inline hook mode
+```
+
+## Benchmarks
+
+`rake bench` seeds a large tree with `insert_all` (no callbacks; about 17 rows per post: comments, polymorphic likes,
+taggings, a HABTM join row, `delete_all` and `nullify` children, a `has_one`, counter caches) and then runs three
+strategies against identical, freshly seeded data:
+
+- `Post.destroy_all` (stock)
+- `Post.find_each(&:destroy)` (per-record loop)
+- `Post.bulk_destroy_all`
+
+It first asserts that all three leave the same rows behind and fire exactly the same hook calls, then asserts that
+`bulk_destroy_all` issues at least 10x fewer queries and is faster. Size and database are configurable:
+`BENCH_POSTS=1000 BENCH_COMMENTS=5 BULK_DESTROYER_DB=postgresql rake bench`. It is skipped by `rake test`. The same file also has a test that destroys the 35,700-record tree described
+under [The Fiber ceiling](#the-fiber-ceiling-and-max_batch_records) with default settings.
+
+Single runs on a small cloud VM, Rails 8.1.3.1, Ruby 3.4.8, database on the same machine:
+
+| Database | Posts / rows | Strategy | Seconds | Queries | Hook calls | Speedup |
+|---|---|---|---|---|---|---|
+| SQLite (in-memory) | 1,000 / 17,003 | `destroy_all` | 9.44 | 32,001 | 84,000 | 1.0x |
+| | | `find_each(&:destroy)` | 9.25 | 32,002 | 84,000 | 1.0x |
+| | | `bulk_destroy_all` | 1.34 | 45 | 84,000 | 7.1x |
+| SQLite (in-memory) | 5,000 / 85,003 | `destroy_all` | 58.33 | 160,001 | 420,000 | 1.0x |
+| | | `find_each(&:destroy)` | 56.76 | 160,006 | 420,000 | 1.0x |
+| | | `bulk_destroy_all` | 6.69 | 221 | 420,000 | 8.7x |
+| PostgreSQL 16 (TCP) | 1,000 / 17,003 | `destroy_all` | 19.73 | 32,001 | 84,000 | 1.0x |
+| | | `find_each(&:destroy)` | 20.57 | 32,002 | 84,000 | 1.0x |
+| | | `bulk_destroy_all` | 1.58 | 45 | 84,000 | 12.5x |
+
+What the numbers say: the speedup comes from removing queries, and the callbacks themselves still cost the same
+(84,000 hook calls either way), so the gap is smallest on an in-memory database and larger when each query costs
+a round trip. I only measured a database on the same machine; I would expect a remote database to widen the gap
+but have not measured it. `destroy_all` and `find_each(&:destroy)` are equivalent in cost, since both issue the
+same per-record queries; the loop only avoids loading every record at once.
+
+## Compatibility
+
+Supports Rails **7.1 through 8.2** (`activerecord >= 7.1, < 8.3`). The full suite (44 tests, foreign keys
+enforced) passes unchanged on:
+
+| Rails | SQLite 3 | PostgreSQL 16 | MariaDB 10.11 |
+|---|---|---|---|
+| 7.1.6 | pass | not run | not run |
+| 7.2.4 | pass | not run | not run |
+| 8.0.5 | pass | not run | not run |
+| 8.1.3.1 | pass | pass | not run |
+| 8.2.0.alpha (main) | pass | pass (first 22 tests; `belongs_to` tests not run) | pass (first 22 tests; `belongs_to` tests not run) |
+
+Ruby was only tested on 3.4; the `>= 3.1` floor in the gemspec is an assumption (Rails itself enforces
+its own Ruby floor). Oracle and SQL Server are unverified (IN-list ceilings are built in, nothing has been run there).
+
+**Rails 7.0 and earlier are not supported.** In 7.0 the connection lock is held by the calling fiber for the
+whole transaction, so any hook that runs a query inside a hook Fiber raises
+`ThreadError: deadlock; lock already owned by another fiber`. Rails 7.1 changed that locking. On 7.0,
+`BulkDestroyer.hook_mode = :inline` avoids Fibers (in an earlier 22-test run, 20 passed; the other two assert the
+post-DELETE `after_destroy` timing that inline mode intentionally gives up), but this is not a supported configuration.
+
+Version differences handled internally: `Model.with_connection` (7.2+, falls back to `connection` on 7.1) and
+`counter_cached_association_names` (7.2+, falls back to the `belongs_to` reflections on 7.1).

data/lib/bulk_destroyer/api.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module BulkDestroyer
+  module RelationMethods
+    # Like #destroy_all: every destroy callback fires on every record, including dependent:
+    # :destroy descendants. Unlike #destroy_all: one SELECT per association per level and one
+    # DELETE per table per level.
+    def bulk_destroy_all(batch_size: BulkDestroyer.batch_size)
+      Destroyer.new(self, batch_size: batch_size).call
+    end
+  end
+
+  module ClassMethods
+    def bulk_destroy_all(batch_size: BulkDestroyer.batch_size)
+      all.bulk_destroy_all(batch_size: batch_size)
+    end
+  end
+
+  module RecordMethods
+    def bulk_destroy!
+      Destroyer.new(self).call
+    end
+  end
+end

data/lib/bulk_destroyer/batch.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module BulkDestroyer
+  # One transaction's worth of work: a batch of root records and everything below them.
+  #
+  #   1. Tree          load the dependent: :destroy graph (one query per association per level)
+  #   2. restrictions  dependent: :restrict_with_* checked before anything runs
+  #   3. start hooks   before_destroy / first half of around_destroy, parents before children
+  #   4. per level, deepest first:
+  #        nullify / delete_all / HABTM join rows  ->  bulk DELETE  ->  counter caches
+  #        ->  mark records destroyed  ->  after_destroy / second half of around_destroy
+  #
+  # Level-by-level means a child's after_destroy runs while its parent row still exists, and a
+  # parent's after_destroy runs after its children are gone, as with plain `destroy`.
+  class Batch
+    def initialize(roots, handled: Set.new)
+      @roots = roots
+      @handled = handled
+    end
+
+    def run
+      levels = Tree.new(@roots, exclude: @handled).build
+      records = levels.flatten
+      inline = oversized?(records) # raises before anything ran if the tree is too big for Fibers
+      records.each { |record| @handled << Tree.key_for(record) }
+      counts = Hash.new(0)
+      runner = nil
+
+      begin
+        Dependents.check_restrictions!(records)
+        runner = HookRunner.build(mode: inline ? :inline : BulkDestroyer.hook_mode)
+        records.each { |record| prepare(record) }
+        levels.flatten.each do |record|
+          next if runner.start(record)
+
+          raise ActiveRecord::RecordNotDestroyed.new("Failed to destroy #{record.class.name} with #{record.class.primary_key}=#{record.id}", record)
+        end
+
+        levels.reverse_each do |level|
+          Dependents.apply_bulk_operations(level, counts)
+          delete_rows(level, counts)
+          CounterCaches.decrement(level)
+          level.each { |record| mark_destroyed(record) }
+          level.each { |record| runner.finish(record) }
+          destroy_belongs_to_targets(level, counts)
+        end
+      ensure
+        runner&.abort_all
+        records.each { |record| record.remove_instance_variable(CascadeGuard::FLAG) if record.instance_variable_defined?(CascadeGuard::FLAG) }
+      end
+
+      counts
+    end
+
+    private
+
+    # belongs_to ..., dependent: :destroy / :delete. Rails does this in the owner's after_destroy; here it
+    # happens once the whole level of owners is gone. :destroy targets go through a nested Batch (their own
+    # hooks, children, restrictions and further belongs_to targets), still inside this transaction.
+    def destroy_belongs_to_targets(level, counts)
+      found = Dependents.belongs_to_targets(level, @handled)
+
+      run_nested(found[:destroy], counts) unless found[:destroy].empty?
+
+      found[:delete].group_by { |target| target.class.base_class }.each do |base, group|
+        ids = sortable(group.map(&:id))
+        Dependents.in_slices(ids, base) do |slice|
+          deleted = base.unscoped.where(base.primary_key => slice).delete_all
+          counts[base.name] += deleted if deleted.positive?
+        end
+        # Same end state as Rails' #delete: marked destroyed, no callbacks, no commit hooks.
+        group.each do |target|
+          target.instance_variable_set(:@destroyed, true)
+          target.freeze
+        end
+      end
+    end
+
+    # Same transaction as the enclosing batch. A tree that is too big for Fibers is split by targets.
+    def run_nested(targets, counts)
+      Batch.new(targets, handled: @handled).run.each { |name, n| counts[name] += n }
+    rescue SplitRequired
+      middle = targets.size / 2
+      run_nested(targets.first(middle), counts)
+      run_nested(targets.drop(middle), counts)
+    end
+
+    # One paused Fiber per record, all alive at once, so the tree size is capped. => true when this batch
+    # has to run its hooks without Fibers.
+    def oversized?(records)
+      return false if BulkDestroyer.hook_mode == :inline
+      return false if records.size <= BulkDestroyer.max_batch_records
+      raise SplitRequired if @roots.size > 1
+
+      case BulkDestroyer.oversized_tree
+      when :inline then true
+      when :raise
+        raise TreeTooLarge,
+              "the dependent: :destroy tree below #{@roots.first.class.name}##{@roots.first.id} has " \
+              "#{records.size} records with destroy hooks, more than BulkDestroyer.max_batch_records " \
+              "(#{BulkDestroyer.max_batch_records}). Each needs a paused Fiber and Ruby on Linux fails around " \
+              "31,000. Raise max_batch_records (keep it well below that), or set " \
+              "BulkDestroyer.oversized_tree = :inline to run these hooks without Fibers " \
+              "(after_destroy then runs before the DELETE)."
+      else raise ArgumentError, "unknown oversized_tree #{BulkDestroyer.oversized_tree.inspect}"
+      end
+    end
+
+    def prepare(record)
+      record.instance_variable_set(CascadeGuard::FLAG, true)
+      record.send(:_raise_readonly_record_error) if record.readonly?
+      # Same bookkeeping Rails' with_transaction_returning_status does for a normal destroy: it
+      # lets after_commit / after_rollback fire and restores @destroyed if the batch rolls back.
+      record.send(:add_to_transaction)
+      record.send(:remember_transaction_record_state)
+    end
+
+    def delete_rows(level, counts)
+      level.group_by { |record| record.class.base_class }.each do |base, group|
+        ids = sortable(group.map(&:id))
+        base.transaction do
+          Dependents.in_slices(ids, base) do |slice|
+            counts[base.name] += base.unscoped.where(base.primary_key => slice).delete_all
+          end
+        end
+      end
+    end
+
+    # Ascending ids give concurrent bulk deletes a consistent lock order (fewer deadlocks).
+    def sortable(ids)
+      ids.sort
+    rescue ArgumentError, NoMethodError
+      ids
+    end
+
+    def mark_destroyed(record)
+      record.instance_variable_set(:@_trigger_destroy_callback, true)
+      record.instance_variable_set(:@destroyed, true)
+      record.instance_variable_set(:@previously_new_record, false)
+      record.freeze
+    end
+  end
+end

data/lib/bulk_destroyer/cascade_guard.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module BulkDestroyer
+  # Rails implements `dependent:` as a before_destroy/after_destroy lambda that calls
+  # association.handle_dependency, which loads and destroys children one by one. While a record
+  # is being handled by BulkDestroyer we handle every dependent: mode ourselves, so the owner's
+  # own callback must do nothing. Records not flagged behave exactly as in stock Rails.
+  module CascadeGuard
+    FLAG = :@__bulk_destroying
+
+    def handle_dependency
+      return if owner.instance_variable_get(FLAG)
+
+      super
+    end
+  end
+end

data/lib/bulk_destroyer/counter_caches.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module BulkDestroyer
+  # Rails decrements belongs_to counter caches inside Persistence#destroy_row, which bulk
+  # deletion bypasses. This reproduces it with one UPDATE per (counter column, amount) rather
+  # than one per row.
+  module CounterCaches
+    module_function
+
+    # Rails 7.2+ exposes counter_cached_association_names; 7.1 only has the reflections.
+    def counter_cached_reflections(klass)
+      if klass.respond_to?(:counter_cached_association_names)
+        klass.counter_cached_association_names.map { |name| klass._reflect_on_association(name) }
+      else
+        klass.reflect_on_all_associations(:belongs_to).select(&:counter_cache_column)
+      end
+    end
+
+    def decrement(records)
+      records.group_by(&:class).each do |klass, group|
+        counter_cached_reflections(klass).each do |reflection|
+          name = reflection.name
+          simple = !reflection.polymorphic? && Array(reflection.foreign_key).size == 1
+          tally = Hash.new(0)
+
+          group.each do |record|
+            # Same rule as Rails: a child destroyed via its parent's dependent: association does
+            # not touch that parent's counter.
+            via = record.destroyed_by_association
+            next if via && via.foreign_key == reflection.foreign_key
+
+            if simple
+              id = record._read_attribute(reflection.foreign_key)
+              tally[id] += 1 if id
+            else
+              record.association(name).decrement_counters
+            end
+          end
+
+          tally.group_by { |_id, n| n }.each do |n, pairs|
+            counters = { reflection.counter_cache_column => -n }
+            counters[:touch] = reflection.options[:touch] if reflection.options[:touch]
+            Dependents.in_slices(pairs.map(&:first), reflection.klass) do |ids|
+              reflection.klass.update_counters(ids.sort, counters.dup)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/bulk_destroyer/dependents.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+module BulkDestroyer
+  # Understands the `dependent:` options of ActiveRecord associations and reproduces their
+  # semantics with set-based SQL.
+  module Dependents
+    Plan = Struct.new(:reflection, :kind)
+
+    module_function
+
+    # kinds: :destroy (children join the tree), :through_destroy (join records join the tree),
+    #        :delete_all, :nullify, :restrict, :habtm (join rows are deleted without callbacks)
+    def plans_for(klass)
+      klass.reflect_on_all_associations.filter_map { |reflection| classify(reflection) }
+    end
+
+    def classify(reflection)
+      return Plan.new(reflection, :habtm) if reflection.macro == :has_and_belongs_to_many
+
+      dependent = reflection.options[:dependent]
+      return nil if dependent.nil?
+
+      if reflection.belongs_to?
+        # Includes delegated_type, which declares `belongs_to ..., polymorphic: true, dependent: ...`.
+        case dependent
+        when :destroy then return Plan.new(reflection, :belongs_to_destroy)
+        when :delete then return Plan.new(reflection, :belongs_to_delete)
+        else unsupported!(reflection, "belongs_to with dependent: #{dependent.inspect} is not supported")
+        end
+      end
+
+      through = reflection.options[:through]
+      unsupported!(reflection, "nested has_many :through is not supported") if through && reflection.nested?
+
+      case dependent
+      when :destroy
+        Plan.new(reflection, through ? :through_destroy : :destroy)
+      when :delete_all, :delete
+        Plan.new(reflection, :delete_all)
+      when :nullify
+        unsupported!(reflection, "dependent: :nullify on a :through association") if through
+        Plan.new(reflection, :nullify)
+      when :restrict_with_exception, :restrict_with_error
+        Plan.new(reflection, :restrict)
+      when :destroy_async
+        unsupported!(reflection, "dependent: :destroy_async cannot be combined with bulk destroy")
+      else
+        unsupported!(reflection, "unknown dependent: #{dependent.inspect}")
+      end
+    end
+
+    def unsupported!(reflection, message)
+      raise UnsupportedAssociation, "#{reflection.active_record.name}##{reflection.name}: #{message}"
+    end
+
+    # Checks every restrict_with_* association before any hook runs.
+    def check_restrictions!(records)
+      records.group_by(&:class).each do |klass, owners|
+        plans_for(klass).each do |plan|
+          next unless plan.kind == :restrict
+
+          reflection = plan.reflection
+          source = reflection.options[:through] ? reflection.through_reflection : reflection
+          owner_keys = owners.to_h { |o| [o._read_attribute(source.active_record_primary_key), o] }
+          blocked = Set.new
+          in_slices(owner_keys.keys, source.klass) do |keys|
+            blocked.merge(child_relation(source, keys, owners.first).distinct.pluck(source.foreign_key))
+          end
+          next if blocked.empty?
+
+          if reflection.options[:dependent] == :restrict_with_exception
+            raise ActiveRecord::DeleteRestrictionError.new(reflection.name)
+          end
+
+          owner = owner_keys.fetch(blocked.first)
+          human = owner.class.human_attribute_name(reflection.name).downcase
+          owner.errors.add(:base, :"restrict_dependent_destroy.#{reflection.has_one? ? 'has_one' : 'has_many'}", record: human)
+          raise ActiveRecord::RecordNotDestroyed.new("Failed to destroy #{owner.class.name}: #{owner.errors.full_messages.to_sentence}", owner)
+        end
+      end
+    end
+
+    # Targets of `belongs_to ..., dependent: :destroy / :delete` for one level of owners.
+    # Rails destroys these inside the owner's after_destroy, i.e. once the owner's row is gone, so
+    # Batch calls this after each level. Preloader loads them in one query per target class,
+    # polymorphic included.
+    #
+    # +handled+ holds the keys of records already in (or already taken by) this batch; those are
+    # skipped, and every target returned is added to it. That makes a target shared by several owners
+    # come back once, and stops two models that point at each other from destroying each other forever.
+    #
+    # => { destroy: [records], delete: [records] }
+    def belongs_to_targets(owners, handled)
+      found = { destroy: [], delete: [] }
+      owners.group_by(&:class).each do |klass, group|
+        plans_for(klass).each do |plan|
+          next unless plan.kind == :belongs_to_destroy || plan.kind == :belongs_to_delete
+
+          name = plan.reflection.name
+          ActiveRecord::Associations::Preloader.new(records: group, associations: [name]).call
+          bucket = plan.kind == :belongs_to_destroy ? found[:destroy] : found[:delete]
+          group.each do |owner|
+            target = owner.association(name).target
+            next if target.nil? || target.destroyed?
+            next unless handled.add?(Tree.key_for(target))
+
+            bucket << target
+          end
+        end
+      end
+      found
+    end
+
+    # :delete_all, :nullify and HABTM join rows for one level of the tree.
+    # Rows removed by dependent: :delete_all are added to +counts+ under their model's base class name
+    # (HABTM join rows are not counted: the join table has no model of its own).
+    def apply_bulk_operations(records, counts)
+      records.group_by(&:class).each do |klass, owners|
+        plans_for(klass).each do |plan|
+          reflection = plan.reflection
+          case plan.kind
+          when :delete_all
+            source = reflection.options[:through] ? reflection.through_reflection : reflection
+            each_child_relation(source, owners) do |relation|
+              deleted = relation.delete_all
+              counts[source.klass.base_class.name] += deleted if deleted.positive?
+            end
+          when :nullify
+            attributes = { reflection.foreign_key => nil }
+            attributes[reflection.type] = nil if reflection.type
+            each_child_relation(reflection, owners) { |relation| relation.update_all(attributes) }
+          when :habtm
+            middle = klass._reflections.values.find { |r| r.parent_reflection.equal?(reflection) && r.options[:through].nil? }
+            each_child_relation(middle, owners) { |relation| relation.delete_all }
+          end
+        end
+      end
+    end
+
+    def each_child_relation(reflection, owners)
+      keys = owners.map { |o| o._read_attribute(reflection.active_record_primary_key) }
+      in_slices(keys, reflection.klass) do |slice|
+        yield child_relation(reflection, slice, owners.first)
+      end
+    end
+
+    # Rows that belong to +owner_keys+ through +reflection+, honouring the association scope,
+    # custom keys, and polymorphic `as:` type columns.
+    def child_relation(reflection, owner_keys, sample_owner)
+      if Array(reflection.foreign_key).size > 1
+        unsupported!(reflection, "composite foreign keys are only supported for dependent: :destroy")
+      end
+
+      relation = reflection.klass.all
+      if reflection.scope
+        if reflection.scope.arity.positive?
+          unsupported!(reflection, "instance-dependent association scopes are only supported for dependent: :destroy")
+        end
+        relation = relation.instance_exec(&reflection.scope)
+      end
+      relation = relation.where(reflection.foreign_key => owner_keys)
+      relation = relation.where(reflection.type => sample_owner.class.polymorphic_name) if reflection.type
+      relation
+    end
+
+    # Splits long IN lists to stay below adapter limits (Oracle 1000, SQL Server ~2100, ...).
+    def in_slices(values, model, &block)
+      limit = BulkDestroyer.in_list_size_for(model)
+      values.each_slice(limit, &block)
+    end
+  end
+end

data/lib/bulk_destroyer/destroyer.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module BulkDestroyer
+  class Destroyer
+    def initialize(source, batch_size: BulkDestroyer.batch_size)
+      @source = source
+      @batch_size = Integer(batch_size)
+      raise ArgumentError, "batch_size must be positive" unless @batch_size.positive?
+    end
+
+    # => { "Post" => 3, "Comment" => 12, ... } rows deleted per table (by base class name)
+    def call
+      counts = Hash.new(0)
+      each_root_batch { |roots| run_roots(roots, counts) }
+      counts.to_h
+    end
+
+    private
+
+    def run_roots(roots, counts)
+      # requires_new: a failing batch rolls back to its own savepoint (inside a caller's
+      # transaction) or its own real transaction (outside one).
+      completed = false
+      roots.first.class.transaction(requires_new: true) do
+        Batch.new(roots).run.each { |name, n| counts[name] += n }
+        completed = true
+      end
+
+      # `transaction` swallows ActiveRecord::Rollback: it rolls the batch back and returns nil without
+      # raising. A hook that does that would otherwise make this batch vanish silently.
+      return if completed
+
+      raise ActiveRecord::RecordNotDestroyed.new(
+        "bulk destroy rolled back a batch of #{roots.size} #{roots.first.class.name} record(s): " \
+        "ActiveRecord::Rollback was raised in a destroy callback",
+        roots.first
+      )
+    rescue SplitRequired
+      # The tree under these roots has too many records for one batch of paused Fibers. Nothing ran yet
+      # (the savepoint is already rolled back); do each half as its own batch.
+      middle = roots.size / 2
+      run_roots(roots.first(middle), counts)
+      run_roots(roots.drop(middle), counts)
+    end
+
+    def each_root_batch(&block)
+      case @source
+      when ActiveRecord::Base
+        yield [@source] if @source.persisted?
+      when ActiveRecord::Relation
+        @source.find_in_batches(batch_size: @batch_size, &block)
+      else
+        raise ArgumentError, "expected an ActiveRecord relation or record, got #{@source.class}"
+      end
+    end
+  end
+end

data/lib/bulk_destroyer/errors.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module BulkDestroyer
+  class Error < StandardError; end
+
+  # An association configuration the gem cannot reproduce faithfully
+  # (e.g. belongs_to dependent:, :destroy_async, composite-key :nullify).
+  class UnsupportedAssociation < Error; end
+
+  # ActiveSupport::IsolatedExecutionState.isolation_level == :fiber and hook_mode == :fiber.
+  class UnsupportedIsolation < Error; end
+
+  # The dependent: :destroy graph contains a cycle in the data.
+  class CycleDetected < Error; end
+
+  # One root's dependent: :destroy tree has more hook-bearing records than BulkDestroyer.max_batch_records
+  # and cannot be split any further (see BulkDestroyer.oversized_tree).
+  class TreeTooLarge < Error; end
+
+  # Internal: a batch with several roots built a tree over the limit before running any hook; the caller
+  # retries with the roots split in two. Never reaches application code.
+  class SplitRequired < Error; end
+
+  # Raised inside suspended hook fibers to unwind them (so `ensure` blocks in around_destroy
+  # callbacks run). Deliberately not a StandardError so `rescue => e` in app hooks can't swallow it.
+  class Unwind < Exception; end # rubocop:disable Lint/InheritException
+end

data/lib/bulk_destroyer/hook_runner.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module BulkDestroyer
+  # Runs a record's real :destroy callback chain in two halves around the bulk DELETE.
+  #
+  # FiberRunner: each record's `run_callbacks(:destroy)` runs inside a Fiber whose block yields.
+  #   - start(record)  runs before_destroy and the first half of around_destroy, up to the block
+  #   - finish(record) resumes it after the rows are gone: second half of around_destroy, then
+  #                    after_destroy. Conditions (if:/unless:), ordering, prepend:, callback
+  #                    objects and `throw :abort` are all handled by Rails itself.
+  #
+  # InlineRunner: runs the whole chain before the DELETE (after_destroy sees the row). Only for
+  #   apps running with ActiveSupport::IsolatedExecutionState.isolation_level = :fiber.
+  module HookRunner
+    def self.build(mode: BulkDestroyer.hook_mode)
+      case mode
+      when :fiber
+        if ActiveSupport::IsolatedExecutionState.isolation_level == :fiber
+          raise UnsupportedIsolation,
+                "isolation_level is :fiber, so each hook Fiber would get its own database connection. " \
+                "Set BulkDestroyer.hook_mode = :inline (after_destroy then runs just before the DELETE)."
+        end
+        FiberRunner.new
+      when :inline then InlineRunner.new
+      else raise ArgumentError, "unknown hook_mode #{mode.inspect}"
+      end
+    end
+
+    class FiberRunner
+      def initialize
+        @fibers = {}.compare_by_identity
+        # Thread.current[] values are fiber-local; copy them so hooks that read request-scoped
+        # state (RequestStore-style) see the same values inside the hook fibers.
+        @locals = Thread.current.keys.reject { |k| k.to_s.start_with?("__") }.to_h { |k| [k, Thread.current[k]] }
+      end
+
+      # => true when the chain reached the destroy step, false when a before_destroy halted it.
+      def start(record)
+        locals = @locals
+        fiber = Fiber.new do
+          locals.each { |k, v| Thread.current[k] = v }
+          record.run_callbacks(:destroy) do
+            Fiber.yield(:ready)
+            true
+          end
+        end
+        @fibers[record] = fiber
+        fiber.resume
+        return true if fiber.alive?
+
+        @fibers.delete(record)
+        false
+      end
+
+      def finish(record)
+        fiber = @fibers.delete(record)
+        fiber&.resume
+      end
+
+      # Unwinds fibers still suspended after a failure so around_destroy `ensure` blocks run.
+      def abort_all
+        @fibers.each_value do |fiber|
+          next unless fiber.alive?
+
+          begin
+            fiber.raise(Unwind)
+          rescue Unwind, StandardError
+            nil
+          end
+        end
+        @fibers.clear
+      end
+    end
+
+    class InlineRunner
+      def start(record)
+        record.run_callbacks(:destroy) { true } ? true : false
+      end
+
+      def finish(_record); end
+
+      def abort_all; end
+    end
+  end
+end

data/lib/bulk_destroyer/tree.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module BulkDestroyer
+  # Loads the dependent: :destroy graph below a batch of root records one level at a time:
+  # one preload query per association per level, never per record.
+  #
+  # A record reachable by several paths is placed at its deepest level, so it is always deleted
+  # before anything it references.
+  class Tree
+    def self.key_for(record)
+      [record.class.base_class, record.id]
+    end
+
+    # +exclude+: keys of records that belong to an enclosing batch. Descendants found under them are
+    # left alone (roots are always taken), so a nested pass never handles a record twice.
+    def initialize(roots, exclude: nil)
+      @roots = roots
+      @exclude = exclude || Set.new
+      @records = {}
+      @depths = {}
+    end
+
+    # => Array of Arrays; index 0 holds the roots, higher indexes are deeper.
+    def build
+      frontier = []
+      @roots.each { |root| add(root, 0, frontier) }
+
+      until frontier.empty?
+        current = frontier.uniq
+        frontier = []
+        current.group_by(&:class).each do |klass, owners|
+          expand(klass, owners) do |child, owner, via|
+            next if skipped?(child)
+
+            canonical = add(child, @depths.fetch(key(owner)) + 1, frontier)
+            canonical.destroyed_by_association = via if via
+          end
+        end
+      end
+
+      by_depth = Hash.new { |hash, depth| hash[depth] = [] }
+      @records.each { |k, record| by_depth[@depths.fetch(k)] << record }
+      by_depth.sort.map(&:last)
+    end
+
+    private
+
+    def key(record)
+      self.class.key_for(record)
+    end
+
+    def skipped?(record)
+      k = key(record)
+      !@records.key?(k) && @exclude.include?(k)
+    end
+
+    def add(record, depth, frontier)
+      k = key(record)
+      if (existing = @records[k])
+        return existing if @depths.fetch(k) >= depth
+
+        raise CycleDetected, "dependent: :destroy cycle detected at #{record.class.name}##{record.id}" if depth > @records.size
+
+        @depths[k] = depth
+        frontier << existing
+        existing
+      else
+        @records[k] = record
+        @depths[k] = depth
+        frontier << record
+        record
+      end
+    end
+
+    def expand(klass, owners)
+      plans = Dependents.plans_for(klass).select { |p| p.kind == :destroy || p.kind == :through_destroy }
+      return if plans.empty?
+
+      names = plans.map { |p| p.kind == :destroy ? p.reflection.name : p.reflection.through_reflection.name }.uniq
+      ActiveRecord::Associations::Preloader.new(records: owners, associations: names).call
+
+      plans.each do |plan|
+        direct = plan.kind == :destroy
+        name = direct ? plan.reflection.name : plan.reflection.through_reflection.name
+        owners.each do |owner|
+          Array(owner.association(name).target).each do |child|
+            yield child, owner, (plan.reflection if direct)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/bulk_destroyer/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module BulkDestroyer
+  VERSION = "0.1.0"
+end

data/lib/bulk_destroyer.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "set"
+require "active_support"
+require "active_record"
+
+require_relative "bulk_destroyer/version"
+require_relative "bulk_destroyer/errors"
+require_relative "bulk_destroyer/cascade_guard"
+require_relative "bulk_destroyer/dependents"
+require_relative "bulk_destroyer/tree"
+require_relative "bulk_destroyer/hook_runner"
+require_relative "bulk_destroyer/counter_caches"
+require_relative "bulk_destroyer/batch"
+require_relative "bulk_destroyer/destroyer"
+require_relative "bulk_destroyer/api"
+
+module BulkDestroyer
+  # Hard ceilings for IN (...) lists by adapter; the effective size is min(in_list_size, ceiling).
+  ADAPTER_IN_LIMITS = {
+    "oracleenhanced" => 1_000,
+    "sqlserver" => 2_000,
+    "sqlite" => 32_766
+  }.freeze
+  DEFAULT_IN_LIMIT = 65_000
+
+  class << self
+    # Parents loaded per transaction.
+    attr_accessor :batch_size
+    # Max values per `WHERE id IN (...)` chunk.
+    attr_accessor :in_list_size
+    # :fiber (default; after_destroy runs after the DELETE) or :inline (see HookRunner).
+    attr_accessor :hook_mode
+    # Most records (with destroy hooks) one batch may hold. :fiber mode keeps one paused Fiber per record,
+    # and Ruby on Linux fails (FiberError) at roughly 31,000 live Fibers with the default vm.max_map_count.
+    # A batch whose tree is larger is split in half until it fits; keep this well below that ceiling,
+    # because nested belongs_to target batches are counted separately.
+    attr_accessor :max_batch_records
+    # What to do when ONE root's tree alone exceeds max_batch_records: :raise (default, TreeTooLarge)
+    # or :inline (run that batch's hooks without Fibers, so its after_destroy hooks run before the DELETE).
+    attr_accessor :oversized_tree
+
+    def in_list_size_for(model)
+      # Model.with_connection arrived in Rails 7.2; 7.1 only has Model.connection.
+      name = model.respond_to?(:with_connection) ? model.with_connection(&:adapter_name) : model.connection.adapter_name
+      adapter = name.to_s.downcase.delete("_ ")
+      ceiling = ADAPTER_IN_LIMITS.find { |name, _| adapter.include?(name) }&.last || DEFAULT_IN_LIMIT
+      [in_list_size, ceiling].min
+    end
+  end
+
+  self.batch_size = 1_000
+  self.in_list_size = 500
+  self.hook_mode = :fiber
+  self.max_batch_records = 10_000
+  self.oversized_tree = :raise
+end
+
+ActiveSupport.on_load(:active_record) do
+  ActiveRecord::Relation.include BulkDestroyer::RelationMethods
+  ActiveRecord::Base.extend BulkDestroyer::ClassMethods
+  ActiveRecord::Base.include BulkDestroyer::RecordMethods
+
+  [ActiveRecord::Associations::HasManyAssociation,
+   ActiveRecord::Associations::HasOneAssociation,
+   ActiveRecord::Associations::BelongsToAssociation].each do |association|
+    association.prepend BulkDestroyer::CascadeGuard
+  end
+end

metadata

@@ -0,0 +1,82 @@
+--- !ruby/object:Gem::Specification
+name: bulk_destroyer
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ramanan Neelakantan
+bindir: bin
+cert_chain: []
+date: 2026-10-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.3'
+description: |
+  BulkDestroyer destroys a relation (and its dependent: :destroy tree) while firing every
+  destroy callback on every record, but issues one SELECT per association per level and one
+  DELETE per table per level instead of one DELETE per row. Works on any ActiveRecord adapter.
+email:
+- ramanan.i.neelakantan@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/bulk_destroyer.rb
+- lib/bulk_destroyer/api.rb
+- lib/bulk_destroyer/batch.rb
+- lib/bulk_destroyer/cascade_guard.rb
+- lib/bulk_destroyer/counter_caches.rb
+- lib/bulk_destroyer/dependents.rb
+- lib/bulk_destroyer/destroyer.rb
+- lib/bulk_destroyer/errors.rb
+- lib/bulk_destroyer/hook_runner.rb
+- lib/bulk_destroyer/tree.rb
+- lib/bulk_destroyer/version.rb
+homepage: https://github.com/rneelakantan/bulk_destroyer
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/rneelakantan/bulk_destroyer
+  changelog_uri: https://github.com/rneelakantan/bulk_destroyer/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/rneelakantan/bulk_destroyer/issues
+  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: 3.6.2
+specification_version: 4
+summary: 'destroy_all in bulk: every destroy callback fires, rows are deleted with
+  set-based SQL.'
+test_files: []