activerecord-duplicator 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4bf58194f42894cf69c9ff83e02cd0f9f76fe38565e671e24ebb232221e8fa31
+  data.tar.gz: 1d20e02d28ef2bffcf831654d2b71fe73461d3eee0fa3b11ce5e95a15bac259a
+SHA512:
+  metadata.gz: ba02707cbdfdf479e2663bfcbf9b7d4012e1b1d43a9a483a041b76debff00d013e8b4f36efd7e81cb8e2e09d30a60b374a87345f625216dad0c75fee6898f1f0
+  data.tar.gz: 6871e902554ea9fc435b17bfa83e978a1034898bae00cf744edb61b191a89dc05bc479d316c6785a172a722f7d87b794114e173b819ed8176ccdffca380bd430

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+## [Unreleased]
+
+- Drop support for Ruby 3.2 (EOL)
+- Drop support for Rails 7.2; assume ActiveRecord >= 8.0 so `in_batches(cursor:)` is always available
+
+## [0.1.0] - 2026-07-02
+
+- Add `ActiveRecord::Duplicator::AssociationTraversal` — breadth-first traversal of preload-style association specifications
+- Add `ActiveRecord::Duplicator::Session` — coordinates one duplication run: record id map, handler registry, `duplicate` / `bulk_insert` / `attributes_for`
+- Add `ActiveRecord::Duplicator::HandlerApi` — facade passed to `Session#on` handler blocks
+- Add error types under `ActiveRecord::Duplicator::Error`: `InvalidRecordIdError` / `MissingNewIdError` / `DuplicateHandlerError`
+- Support composite primary keys (Rails 7.1+)

data/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2026 SmartHR, Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

data/README.md

@@ -0,0 +1,172 @@
+# activerecord-duplicator
+
+Duplicate an ActiveRecord record together with its associated rows (has_many,
+has_one, belongs_to, has_many :through) in one call. Foreign keys are rewired
+through an internal id map; callbacks are bypassed via `insert_all!` so
+duplication does not fire `after_create` and friends. Per-model handlers let
+you plug in custom logic when a plain copy is not enough. Composite primary
+keys (Rails 7.1+) are supported.
+
+## Installation
+
+```bash
+bundle add activerecord-duplicator
+```
+
+Or without Bundler:
+
+```bash
+gem install activerecord-duplicator
+```
+
+## Requirements
+
+- Ruby >= 3.3
+- ActiveRecord >= 8.0 (tested against 8.0, 8.1)
+- PostgreSQL (via `pg` gem). The gem relies on `insert_all!` returning inserted
+  primary keys.
+
+## Usage
+
+### Basic duplication
+
+```ruby
+duplicator = ActiveRecord::Duplicator.new
+
+new_post = duplicator.duplicate(
+  old_post,
+  associations: [:comments, tags: :taggings],
+)
+```
+
+`duplicate` creates a new `Post` (and all rows reachable via the given
+`associations`), rewires every foreign key to point at the freshly created
+parents, and returns the new root record.
+
+### Keeping records referenced but not copied (`mark_skip`)
+
+When you want the duplicated rows to keep pointing at an existing record
+(for example the current tenant, current user, or a shared lookup table),
+mark that record as skipped before calling `duplicate`:
+
+```ruby
+duplicator = ActiveRecord::Duplicator.new
+duplicator.mark_skip(tenant)
+duplicator.mark_skip(current_user)
+
+duplicator.duplicate(old_project, associations: [tasks: :attachments])
+```
+
+Skipped records get `new_id == old_id` in the internal map, so children that
+reference them are inserted with the original id unchanged.
+
+### Registering an id from outside (`store_new_id` / `fetch_new_id`)
+
+If you produce a duplicate yourself (for example a model with a uniqueness
+constraint that has to be reshaped before insert), tell the session about the
+mapping so downstream children can find the new parent id:
+
+```ruby
+new_project = old_project.dup
+new_project.slug = "#{old_project.slug}-copy"
+new_project.save!
+
+duplicator = ActiveRecord::Duplicator.new
+duplicator.store_new_id(Project, old_id: old_project.id, new_id: new_project.id)
+duplicator.duplicate(old_project, associations: [:tasks])
+```
+
+`fetch_new_id(klass, old_id:)` returns the mapping (scalar for a single-column
+primary key, Array for a composite one) and raises `MissingNewIdError` if the
+parent has not been duplicated yet.
+
+### Per-model handlers (`on`)
+
+Some models need custom logic that the default `insert_all!` path cannot
+express: ActiveStorage attachments, unique constraint rewrites, values that
+depend on the target tenant, and so on. Register a handler and it will be
+called instead of the default duplication path for that class:
+
+```ruby
+duplicator.on(Attachment) do |api, klass, records|
+  records.find_each do |record|
+    new_record = klass.create!(
+      post_id: api.fetch_new_id(Post, old_id: record.post_id),
+    )
+    new_record.file.attach(record.file.blob)
+    api.store_new_id(klass, old_id: record.id, new_id: new_record.id)
+  end
+end
+```
+
+`api` is a `HandlerApi` facade over the session that exposes
+`mark_skip` / `store_new_id` / `fetch_new_id` / `bulk_insert` /
+`attributes_for`. Registering two handlers for the same class raises
+`DuplicateHandlerError`.
+
+### Composite primary keys
+
+`self.primary_key = [:tenant_id, :id]` classes are handled the same way.
+Non-auto columns of the composite pk (e.g. `tenant_id`) are carried over from
+the source record; only DB-populated columns (e.g. a `bigserial id`) get fresh
+values. `foreign_key: [:tenant_id, :owner_id]` associations are traversed with
+tuple `WHERE (a, b) IN ((v1, v2), ...)` syntax.
+
+### Errors
+
+All errors inherit from `ActiveRecord::Duplicator::Error`:
+
+- `InvalidRecordIdError` — the same `old_id` was registered with a different `new_id`.
+- `MissingNewIdError` — `fetch_new_id` had no mapping. Usually means a
+  belongs_to parent was not duplicated yet; place it earlier in the
+  associations tree or mark it skipped.
+- `DuplicateHandlerError` — `on(klass)` was called twice for the same class.
+
+Because they share a common ancestor, one `rescue` clause catches any
+duplication-specific failure:
+
+```ruby
+begin
+  duplicator.duplicate(old_post, associations: [:comments])
+rescue ActiveRecord::Duplicator::Error => e
+  Rails.logger.error("duplication failed: #{e.class.name} #{e.message}")
+  raise
+end
+```
+
+### Performance notes
+
+`AssociationTraversal` currently pluck-collects parent ids and emits
+`WHERE fk IN (id1, ..., idN)`. Very large N (tens of thousands) may hit
+PostgreSQL planner degradation; if you run into this, split your work into
+smaller root records or file an issue.
+
+## Development
+
+The gem tests against a real PostgreSQL instance. `compose.yml` at the repo
+root starts one for you on port 55432:
+
+```bash
+docker compose up -d
+
+bundle install
+bundle exec rake       # rspec + rubocop
+bundle exec rspec      # spec only
+```
+
+Override the connection with `DATABASE_URL` (used by CI):
+
+```bash
+DATABASE_URL=postgres://user:pass@host:port/db bundle exec rspec
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at
+<https://github.com/kufu/activerecord-duplicator>. This project is
+intended to be a safe, welcoming space for collaboration; contributors are
+expected to adhere to the [code of conduct](CODE_OF_CONDUCT.md).
+
+## License
+
+Released under the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0).

data/lib/active_record/duplicator/association_traversal.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  class Duplicator
+    # Breadth-first traversal of associations declared with preload-style syntax.
+    # Yields ActiveRecord::Relation objects in the order they would be needed to
+    # duplicate records level by level.
+    #
+    # Example:
+    #   traversal = ActiveRecord::Duplicator::AssociationTraversal.new(
+    #     owner,
+    #     [items: :taggings],
+    #   )
+    #   traversal.each do |relation|
+    #     # 1st: Relation of items belonging to owner
+    #     # 2nd: Relation of taggings belonging to those items
+    #   end
+    class AssociationTraversal
+      include Enumerable
+
+      # @rbs @record: untyped
+      # @rbs @associations: untyped
+
+      #: (untyped record, untyped associations) -> void
+      def initialize(record, associations)
+        @record = record
+        @associations = associations
+      end
+
+      #: () { (ActiveRecord::Relation) -> void } -> self
+      #: () -> Enumerator[ActiveRecord::Relation, self]
+      def each(&)
+        return enum_for(:each) unless block_given?
+
+        Array.wrap(@associations).each do |association|
+          traverse(@record.class, association, Array.wrap(@record), &)
+        end
+        self
+      end
+
+      private
+
+      #: (Class, untyped, untyped) { (ActiveRecord::Relation) -> void } -> void
+      def traverse(klass, association, records, &)
+        case association
+        when Hash
+          traverse_hash(klass, association, records, &)
+        when Symbol, String
+          traverse_leaf(klass, association, records, &)
+        else
+          raise ArgumentError, "#{association.inspect} is not a valid association form"
+        end
+      end
+
+      #: (Class, Symbol | String, untyped) { (ActiveRecord::Relation) -> void } -> void
+      def traverse_leaf(klass, association, records)
+        reflection = find_reflection(klass, association)
+        yield build_relation(reflection.klass, reflection, records)
+      end
+
+      #: (Class, Hash[Symbol | String, untyped], untyped) { (ActiveRecord::Relation) -> void } -> void
+      def traverse_hash(klass, association, records, &)
+        association.each do |parent, children|
+          reflection = find_reflection(klass, parent)
+          relation = build_relation(reflection.klass, reflection, records)
+          yield relation
+
+          Array.wrap(children).each do |child|
+            traverse(relation.klass, child, relation, &)
+          end
+        end
+      end
+
+      # Resolves the intermediate through_reflection first, then replaces it with the
+      # source_reflection. For has_many/has_one it looks up children by matching the
+      # parent's primary key against the child's foreign key. For belongs_to it looks
+      # up the parent by matching the child's foreign key against the parent's primary key.
+      #
+      # For composite primary keys the foreign_key / active_record_primary_key of a
+      # reflection is an Array of column names; the corresponding WHERE clause uses
+      # tuple syntax like `where([:a, :b] => [[v1, v2], [v3, v4]])`.
+      #: (Class, untyped, untyped) -> ActiveRecord::Relation
+      def build_relation(klass, reflection, records)
+        if reflection.through_reflection?
+          records = build_relation(reflection.through_reflection.klass, reflection.through_reflection, records)
+          reflection = reflection.source_reflection
+        end
+
+        if reflection.collection? || reflection.has_one?
+          lookup_columns = Array.wrap(reflection.active_record_primary_key)
+          filter_columns = Array.wrap(reflection.foreign_key)
+        elsif reflection.belongs_to?
+          lookup_columns = Array.wrap(reflection.foreign_key)
+          filter_columns = Array.wrap(reflection.active_record_primary_key)
+        else
+          raise NotImplementedError, "reflection kind #{reflection.class.name} is not supported"
+        end
+
+        ids = collect_ids(records, lookup_columns)
+        klass.where(where_key(filter_columns) => ids)
+      end
+
+      #: (Class, Symbol | String) -> untyped
+      def find_reflection(klass, association)
+        reflection = klass.reflect_on_association(association)
+        raise ArgumentError, "#{klass.name} has no association #{association}" if reflection.nil?
+
+        reflection
+      end
+
+      # Rails accepts either a scalar column name or an Array of column names
+      # as the LHS of a WHERE clause. For single-column pk we hand it a scalar
+      # so the generated SQL stays as `WHERE col IN (...)`.
+      #: (Array[Symbol | String]) -> (Symbol | String | Array[Symbol | String])
+      def where_key(columns)
+        columns.length == 1 ? columns.first : columns
+      end
+
+      # Avoid instantiating ActiveRecord objects just to read ids:
+      # use pluck for Relations and map for plain arrays. For composite pk
+      # returns an Array of Arrays (`[[v1, v2], ...]`); for single-column pk
+      # returns a flat Array (`[v1, v2, ...]`).
+      #: (untyped, Array[Symbol | String]) -> Array[untyped]
+      def collect_ids(records, columns)
+        if records.is_a?(ActiveRecord::Relation)
+          if columns.length == 1
+            records.pluck(columns.first)
+          else
+            records.pluck(*columns)
+          end
+        else
+          records.map do |r|
+            if columns.length == 1
+              r.public_send(columns.first)
+            else
+              columns.map { |c| r.public_send(c) }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_record/duplicator/errors.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  class Duplicator
+    class Error < StandardError; end
+
+    # Raised when store_new_id (or mark_skip) tries to overwrite an existing
+    # mapping with a different new_id. This typically indicates a bug in the
+    # calling code or a handler.
+    class InvalidRecordIdError < Error; end
+
+    # Raised when fetch_new_id cannot find a mapping for the given old_id.
+    # This usually means a belongs_to parent has not been duplicated yet;
+    # place the parent earlier in the associations tree, or register/skip it
+    # explicitly.
+    class MissingNewIdError < Error; end
+
+    # Raised when Session#on is called twice for the same model class.
+    class DuplicateHandlerError < Error; end
+  end
+end

data/lib/active_record/duplicator/handler_api.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  class Duplicator
+    # The public API surface handed to blocks registered via Session#on.
+    # Wraps the current Session and exposes only the subset of methods a
+    # handler should call. Session-level methods such as on and duplicate are
+    # intentionally not surfaced here.
+    class HandlerApi
+      # @rbs @session: Session
+
+      #: (Session) -> void
+      def initialize(session)
+        @session = session
+      end
+
+      #: (*ActiveRecord::Base) -> void
+      def mark_skip(...)
+        @session.mark_skip(...)
+      end
+
+      #: (Class, old_id: untyped, new_id: untyped) -> void
+      def store_new_id(...)
+        @session.store_new_id(...)
+      end
+
+      #: (Class, old_id: untyped) -> untyped
+      def fetch_new_id(...)
+        @session.fetch_new_id(...)
+      end
+
+      #: (Class, untyped, ?batch_size: Integer, ?cursor: untyped) -> void
+      def bulk_insert(...)
+        @session.bulk_insert(...)
+      end
+
+      #: (Class, ActiveRecord::Base) -> Hash[String, untyped]
+      def attributes_for(...)
+        @session.attributes_for(...)
+      end
+    end
+  end
+end

data/lib/active_record/duplicator/session.rb

@@ -0,0 +1,268 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  class Duplicator
+    # One-shot execution context for a duplication run.
+    #
+    # A Session owns the record id map (old_id -> new_id, per class) and
+    # exposes the API a handler needs: mark_skip / store_new_id / fetch_new_id
+    # / bulk_insert / attributes_for.
+    #
+    # Users normally do not instantiate Session directly; a fresh Session is
+    # created by Duplicator#duplicate for every run, so state does not leak
+    # across runs. Duplicator#duplicate yields the Session to its block so
+    # callers can mark_skip / store_new_id before the run starts.
+    #
+    # Composite primary keys (Rails 7.1+ `self.primary_key = [:a, :b]`) are
+    # supported. An id is a scalar for a single-column primary key and an
+    # Array for a composite one; the shape simply mirrors what
+    # `record.class.primary_key` reports.
+    class Session
+      DEFAULT_BATCH_SIZE = 1000
+      private_constant :DEFAULT_BATCH_SIZE
+
+      # @rbs @record_id_map: Hash[Class, Hash[untyped, untyped]]
+      # @rbs @handlers: Hash[Class, Proc]
+      # @rbs @user_handlers: Hash[Class, Proc]
+
+      #: (?handlers: Hash[Class, Proc]) -> void
+      def initialize(handlers: {})
+        @record_id_map = Hash.new { |hash, klass| hash[klass] = {} }
+        @handlers = handlers
+        @user_handlers = {}
+        @handlers_cache = {}
+      end
+
+      # Register a handler that overrides Duplicator#on for the current session
+      # only. Useful when a single duplication run needs a special copy of a
+      # model that the shared Duplicator config should not know about.
+      #
+      # Raises DuplicateHandlerError when the same class is registered twice
+      # via Session#on in the same session. Overriding a class that also has a
+      # Duplicator-level handler is intentional and does not raise.
+      #: (Class) { (HandlerApi, Class, untyped) -> void } -> void
+      def on(klass, &block)
+        @handlers_cache.clear
+
+        if @user_handlers.key?(klass)
+          raise DuplicateHandlerError, "handler for #{klass} is already overridden in this session"
+        end
+
+        @user_handlers[klass] = block
+      end
+
+      # Declare that the given records must not be duplicated: their new_id
+      # is set equal to their old_id, so any record duplicated later that
+      # references them will keep pointing at the same rows.
+      #: (*ActiveRecord::Base) -> void
+      def mark_skip(*records)
+        records.each do |record|
+          id = current_id(record)
+          store_new_id(record.class, old_id: id, new_id: id)
+        end
+      end
+
+      # Record a mapping from an old_id to a new_id. Called automatically from
+      # bulk_insert; called explicitly by user code (or a handler) when new
+      # records are produced outside of the default duplication path.
+      #
+      # For a single-column primary key pass a scalar; for a composite primary
+      # key pass an Array matching the shape of the class's primary_key.
+      #
+      # Raises InvalidRecordIdError when the same old_id is already mapped to
+      # a different new_id.
+      #: (Class, old_id: untyped, new_id: untyped) -> void
+      def store_new_id(klass, old_id:, new_id:)
+        map = @record_id_map[klass]
+
+        if !map.key?(old_id)
+          map[old_id] = new_id
+        elsif map[old_id] != new_id
+          raise InvalidRecordIdError,
+            "#{klass} old_id=#{old_id.inspect} is already mapped to " \
+            "#{map[old_id].inspect}, cannot overwrite with #{new_id.inspect}"
+        end
+      end
+
+      # Look up a new_id by (klass, old_id). Returns a scalar for a
+      # single-column pk and an Array for a composite pk.
+      #
+      # Raises MissingNewIdError when no mapping exists. This usually means a
+      # belongs_to parent has not been duplicated yet; place it earlier in the
+      # associations tree or register/skip it explicitly.
+      #: (Class, old_id: untyped) -> untyped
+      def fetch_new_id(klass, old_id:)
+        @record_id_map[klass].fetch(old_id) do
+          raise MissingNewIdError, "no new_id registered for #{klass}##{old_id.inspect}"
+        end
+      end
+
+      # Bulk-insert copies of the given records into klass, skipping any that
+      # are already present in the id map. Handlers can reuse this via HandlerApi
+      # to defer a subset of records to the default duplication path.
+      #: (Class, untyped, ?batch_size: Integer, ?cursor: untyped) -> void
+      def bulk_insert(klass, records, batch_size: DEFAULT_BATCH_SIZE, cursor: nil)
+        batches = enumerate_batches(records, batch_size:, cursor:)
+
+        batches.each do |batch|
+          old_records = batch.to_a
+          old_records.reject! { |r| @record_id_map[klass].key?(current_id(r)) }
+          next if old_records.empty?
+
+          rows = old_records.map { |r| attributes_for(klass, r) }
+          inserted = klass.insert_all!(rows)
+
+          inserted.to_a.each.with_index do |returned_row, i|
+            new_id = extract_id_from_row(klass, returned_row)
+            old_id = current_id(old_records[i])
+            store_new_id(klass, old_id:, new_id:)
+          end
+        end
+      end
+
+      # Build the attribute Hash for a single record, ready to be handed to
+      # insert_all!. Timestamps (as reported by
+      # klass.all_timestamp_attributes_in_model, which covers created_at /
+      # updated_at / created_on / updated_on), auto-generated primary key
+      # columns, and every belongs_to foreign key column are stripped; each
+      # belongs_to foreign key is then re-populated from the id map so it
+      # points to the new parent. Non-auto columns of a composite primary key
+      # (e.g. tenant_id) are carried over from the source record unchanged.
+      #: (Class, ActiveRecord::Base) -> Hash[String, untyped]
+      def attributes_for(klass, old_record)
+        belongs_to = klass.reflect_on_all_associations(:belongs_to)
+        fk_columns = belongs_to.flat_map { |r| Array.wrap(r.foreign_key) }
+        ignored = auto_generated_pk_columns(klass) + klass.all_timestamp_attributes_in_model + fk_columns
+        attrs = old_record.attributes.except(*ignored)
+
+        belongs_to.each { |reflection| assign_foreign_key(attrs, reflection, old_record) }
+
+        attrs
+      end
+
+      # Run the duplication inside a new, non-joinable transaction and return
+      # the freshly loaded root record. Normally invoked by Duplicator#duplicate.
+      #: (ActiveRecord::Base, ?associations: untyped) -> ActiveRecord::Base
+      def run(root_record, associations: [])
+        root_record.transaction(requires_new: true, joinable: false) do
+          duplicate_records([root_record])
+
+          AssociationTraversal.new(root_record, associations).each do |relation|
+            duplicate_records(relation)
+          end
+
+          new_id = fetch_new_id(root_record.class, old_id: current_id(root_record))
+          root_record.class.find(new_id)
+        end
+      end
+
+      private
+
+      #: (untyped) -> void
+      def duplicate_records(relation_or_records)
+        # Group by the real class of each record so a handler registered on an
+        # STI subclass fires only for records of that subclass. For non-STI
+        # models every record shares the given `klass`, so a single group is
+        # produced.
+        relation_or_records.group_by(&:class).each do |real_class, records|
+          handler = cache_or_resolve_handler(real_class)
+
+          if handler
+            handler.call(HandlerApi.new(self), real_class, records)
+          else
+            bulk_insert(real_class, records)
+          end
+        end
+      end
+
+      #: (Class) -> Proc?
+      def cache_or_resolve_handler(klass)
+        @handlers_cache[klass] = resolve_handler(klass) unless @handlers_cache.key?(klass)
+
+        @handlers_cache[klass]
+      end
+
+      # Look up a handler for `klass` by walking its ancestor chain. Session
+      # -local handlers (Session#on) take precedence over any Duplicator-level
+      # handler, even one registered closer in the ancestor chain: the two
+      # passes below are deliberate, not a refactor opportunity.
+      #: (Class) -> Proc?
+      def resolve_handler(klass)
+        # rubocop:disable Style/CombinableLoops
+        klass.ancestors.each do |ancestor|
+          return @user_handlers[ancestor] if @user_handlers.key?(ancestor)
+        end
+        klass.ancestors.each do |ancestor|
+          return @handlers[ancestor] if @handlers.key?(ancestor)
+        end
+        # rubocop:enable Style/CombinableLoops
+        nil
+      end
+
+      #: (untyped, batch_size: Integer, cursor: untyped) -> untyped
+      def enumerate_batches(records, batch_size:, cursor:)
+        if records.respond_to?(:in_batches) && cursor
+          records.in_batches(of: batch_size, cursor:)
+        elsif records.respond_to?(:find_in_batches)
+          records.find_in_batches(batch_size:)
+        else
+          records.each_slice(batch_size)
+        end
+      end
+
+      # Return the id of the given record shaped like the class's primary_key:
+      # a scalar for a single-column pk, an Array for a composite pk.
+      #: (ActiveRecord::Base) -> untyped
+      def current_id(record)
+        pk = record.class.primary_key
+        if pk.is_a?(Array)
+          pk.map { |c| record[c] }
+        else
+          record[pk]
+        end
+      end
+
+      # Extract the primary key value from a row returned by insert_all!.
+      # Scalar for single-column pk, Array for composite pk.
+      #: (Class, Hash[String, untyped]) -> untyped
+      def extract_id_from_row(klass, row)
+        pk = klass.primary_key
+        if pk.is_a?(Array)
+          pk.map { |c| row[c.to_s] }
+        else
+          row[pk.to_s]
+        end
+      end
+
+      #: (Hash[String, untyped], untyped, ActiveRecord::Base) -> void
+      def assign_foreign_key(attrs, reflection, old_record)
+        fk = reflection.foreign_key
+
+        if fk.is_a?(Array)
+          old_values = fk.map { |c| old_record[c] }
+          if old_values.all?(&:nil?)
+            fk.each { |c| attrs[c] = nil }
+          else
+            new_values = fetch_new_id(reflection.klass, old_id: old_values)
+            fk.zip(new_values).each { |c, v| attrs[c] = v }
+          end
+        else
+          old_value = old_record[fk]
+          attrs[fk] = old_value.nil? ? nil : fetch_new_id(reflection.klass, old_id: old_value)
+        end
+      end
+
+      # Primary key columns whose values are filled in by the database (e.g. a
+      # bigserial `id`). These must be stripped from the attributes before
+      # calling insert_all! so the DB can assign fresh values. Composite pk
+      # columns without a default_function (e.g. tenant_id) are kept.
+      #: (Class) -> Array[String]
+      def auto_generated_pk_columns(klass)
+        Array.wrap(klass.primary_key).select do |key|
+          column = klass.column_for_attribute(key)
+          column.default_function.present?
+        end
+      end
+    end
+  end
+end

data/lib/active_record/duplicator/version.rb

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

data/lib/active_record/duplicator.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "active_record"
+
+module ActiveRecord
+  # Reusable duplication configuration and entrypoint.
+  #
+  # A Duplicator holds only per-model handler registrations; it does not hold
+  # any per-run state (the id map lives on Session). Freeze after registering
+  # handlers to enforce immutability across many duplication runs.
+  #
+  # Example:
+  #   duplicator = ActiveRecord::Duplicator.new
+  #   duplicator.on(Attachment) { |api, klass, records| ... }
+  #   duplicator.freeze
+  #
+  #   new_root = duplicator.duplicate(old_root, associations: [...]) do |session|
+  #     session.mark_skip(tenant)
+  #   end
+  class Duplicator
+    # @rbs @handlers: Hash[Class, Proc]
+
+    #: () -> void
+    def initialize
+      @handlers = {}
+    end
+
+    # Register a custom handler for the given model class. See HandlerApi for
+    # the API the block receives.
+    #
+    # Raises DuplicateHandlerError when the same class is registered twice.
+    #: (Class) { (HandlerApi, Class, untyped) -> void } -> void
+    def on(klass, &block)
+      raise DuplicateHandlerError, "handler for #{klass} is already registered" if @handlers.key?(klass)
+
+      @handlers[klass] = block
+    end
+
+    # Prevent further registrations. Also freezes the internal handler map so
+    # accidental mutation later fails loudly.
+    #: () -> self
+    def freeze
+      @handlers.freeze
+      super
+    end
+
+    # Run one duplication. A fresh Session (with a fresh record id map) is
+    # created for every invocation, so state does not leak between runs.
+    #
+    # If a block is given it is called with the new Session before duplication
+    # starts, letting the caller mark_skip or store_new_id for records that
+    # were duplicated elsewhere.
+    #: (ActiveRecord::Base, ?associations: untyped) ?{ (Session) -> void } -> ActiveRecord::Base
+    def duplicate(root_record, associations: [], &block)
+      session = Session.new(handlers: @handlers)
+      block&.call(session)
+      session.run(root_record, associations:)
+    end
+  end
+end
+
+require_relative "duplicator/version"
+require_relative "duplicator/errors"
+require_relative "duplicator/association_traversal"
+require_relative "duplicator/handler_api"
+require_relative "duplicator/session"

data/lib/activerecord-duplicator.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "active_record/duplicator"

data/sig/generated/active_record/duplicator/association_traversal.rbs

@@ -0,0 +1,72 @@
+# Generated from lib/active_record/duplicator/association_traversal.rb with RBS::Inline
+
+module ActiveRecord
+  class Duplicator
+    # Breadth-first traversal of associations declared with preload-style syntax.
+    # Yields ActiveRecord::Relation objects in the order they would be needed to
+    # duplicate records level by level.
+    #
+    # Example:
+    #   traversal = ActiveRecord::Duplicator::AssociationTraversal.new(
+    #     owner,
+    #     [items: :taggings],
+    #   )
+    #   traversal.each do |relation|
+    #     # 1st: Relation of items belonging to owner
+    #     # 2nd: Relation of taggings belonging to those items
+    #   end
+    class AssociationTraversal
+      include Enumerable
+
+      @record: untyped
+
+      @associations: untyped
+
+      # : (untyped record, untyped associations) -> void
+      def initialize: (untyped record, untyped associations) -> void
+
+      # : () { (ActiveRecord::Relation) -> void } -> self
+      # : () -> Enumerator[ActiveRecord::Relation, self]
+      def each: () { (ActiveRecord::Relation) -> void } -> self
+              | () -> Enumerator[ActiveRecord::Relation, self]
+
+      private
+
+      # : (Class, untyped, untyped) { (ActiveRecord::Relation) -> void } -> void
+      def traverse: (Class, untyped, untyped) { (ActiveRecord::Relation) -> void } -> void
+
+      # : (Class, Symbol | String, untyped) { (ActiveRecord::Relation) -> void } -> void
+      def traverse_leaf: (Class, Symbol | String, untyped) { (ActiveRecord::Relation) -> void } -> void
+
+      # : (Class, Hash[Symbol | String, untyped], untyped) { (ActiveRecord::Relation) -> void } -> void
+      def traverse_hash: (Class, Hash[Symbol | String, untyped], untyped) { (ActiveRecord::Relation) -> void } -> void
+
+      # Resolves the intermediate through_reflection first, then replaces it with the
+      # source_reflection. For has_many/has_one it looks up children by matching the
+      # parent's primary key against the child's foreign key. For belongs_to it looks
+      # up the parent by matching the child's foreign key against the parent's primary key.
+      #
+      # For composite primary keys the foreign_key / active_record_primary_key of a
+      # reflection is an Array of column names; the corresponding WHERE clause uses
+      # tuple syntax like `where([:a, :b] => [[v1, v2], [v3, v4]])`.
+      # : (Class, untyped, untyped) -> ActiveRecord::Relation
+      def build_relation: (Class, untyped, untyped) -> ActiveRecord::Relation
+
+      # : (Class, Symbol | String) -> untyped
+      def find_reflection: (Class, Symbol | String) -> untyped
+
+      # Rails accepts either a scalar column name or an Array of column names
+      # as the LHS of a WHERE clause. For single-column pk we hand it a scalar
+      # so the generated SQL stays as `WHERE col IN (...)`.
+      # : (Array[Symbol | String]) -> (Symbol | String | Array[Symbol | String])
+      def where_key: (Array[Symbol | String]) -> (Symbol | String | Array[Symbol | String])
+
+      # Avoid instantiating ActiveRecord objects just to read ids:
+      # use pluck for Relations and map for plain arrays. For composite pk
+      # returns an Array of Arrays (`[[v1, v2], ...]`); for single-column pk
+      # returns a flat Array (`[v1, v2, ...]`).
+      # : (untyped, Array[Symbol | String]) -> Array[untyped]
+      def collect_ids: (untyped, Array[Symbol | String]) -> Array[untyped]
+    end
+  end
+end

data/sig/generated/active_record/duplicator/errors.rbs

@@ -0,0 +1,25 @@
+# Generated from lib/active_record/duplicator/errors.rb with RBS::Inline
+
+module ActiveRecord
+  class Duplicator
+    class Error < StandardError
+    end
+
+    # Raised when store_new_id (or mark_skip) tries to overwrite an existing
+    # mapping with a different new_id. This typically indicates a bug in the
+    # calling code or a handler.
+    class InvalidRecordIdError < Error
+    end
+
+    # Raised when fetch_new_id cannot find a mapping for the given old_id.
+    # This usually means a belongs_to parent has not been duplicated yet;
+    # place the parent earlier in the associations tree, or register/skip it
+    # explicitly.
+    class MissingNewIdError < Error
+    end
+
+    # Raised when Session#on is called twice for the same model class.
+    class DuplicateHandlerError < Error
+    end
+  end
+end

data/sig/generated/active_record/duplicator/handler_api.rbs

@@ -0,0 +1,31 @@
+# Generated from lib/active_record/duplicator/handler_api.rb with RBS::Inline
+
+module ActiveRecord
+  class Duplicator
+    # The public API surface handed to blocks registered via Session#on.
+    # Wraps the current Session and exposes only the subset of methods a
+    # handler should call. Session-level methods such as on and duplicate are
+    # intentionally not surfaced here.
+    class HandlerApi
+      @session: Session
+
+      # : (Session) -> void
+      def initialize: (Session) -> void
+
+      # : (*ActiveRecord::Base) -> void
+      def mark_skip: (*ActiveRecord::Base) -> void
+
+      # : (Class, old_id: untyped, new_id: untyped) -> void
+      def store_new_id: (Class, old_id: untyped, new_id: untyped) -> void
+
+      # : (Class, old_id: untyped) -> untyped
+      def fetch_new_id: (Class, old_id: untyped) -> untyped
+
+      # : (Class, untyped, ?batch_size: Integer, ?cursor: untyped) -> void
+      def bulk_insert: (Class, untyped, ?batch_size: Integer, ?cursor: untyped) -> void
+
+      # : (Class, ActiveRecord::Base) -> Hash[String, untyped]
+      def attributes_for: (Class, ActiveRecord::Base) -> Hash[String, untyped]
+    end
+  end
+end

data/sig/generated/active_record/duplicator/session.rbs

@@ -0,0 +1,130 @@
+# Generated from lib/active_record/duplicator/session.rb with RBS::Inline
+
+module ActiveRecord
+  class Duplicator
+    # One-shot execution context for a duplication run.
+    #
+    # A Session owns the record id map (old_id -> new_id, per class) and
+    # exposes the API a handler needs: mark_skip / store_new_id / fetch_new_id
+    # / bulk_insert / attributes_for.
+    #
+    # Users normally do not instantiate Session directly; a fresh Session is
+    # created by Duplicator#duplicate for every run, so state does not leak
+    # across runs. Duplicator#duplicate yields the Session to its block so
+    # callers can mark_skip / store_new_id before the run starts.
+    #
+    # Composite primary keys (Rails 7.1+ `self.primary_key = [:a, :b]`) are
+    # supported. An id is a scalar for a single-column primary key and an
+    # Array for a composite one; the shape simply mirrors what
+    # `record.class.primary_key` reports.
+    class Session
+      DEFAULT_BATCH_SIZE: ::Integer
+
+      @user_handlers: Hash[Class, Proc]
+
+      @handlers: Hash[Class, Proc]
+
+      @record_id_map: Hash[Class, Hash[untyped, untyped]]
+
+      # : (?handlers: Hash[Class, Proc]) -> void
+      def initialize: (?handlers: Hash[Class, Proc]) -> void
+
+      # Register a handler that overrides Duplicator#on for the current session
+      # only. Useful when a single duplication run needs a special copy of a
+      # model that the shared Duplicator config should not know about.
+      #
+      # Raises DuplicateHandlerError when the same class is registered twice
+      # via Session#on in the same session. Overriding a class that also has a
+      # Duplicator-level handler is intentional and does not raise.
+      # : (Class) { (HandlerApi, Class, untyped) -> void } -> void
+      def on: (Class) { (HandlerApi, Class, untyped) -> void } -> void
+
+      # Declare that the given records must not be duplicated: their new_id
+      # is set equal to their old_id, so any record duplicated later that
+      # references them will keep pointing at the same rows.
+      # : (*ActiveRecord::Base) -> void
+      def mark_skip: (*ActiveRecord::Base) -> void
+
+      # Record a mapping from an old_id to a new_id. Called automatically from
+      # bulk_insert; called explicitly by user code (or a handler) when new
+      # records are produced outside of the default duplication path.
+      #
+      # For a single-column primary key pass a scalar; for a composite primary
+      # key pass an Array matching the shape of the class's primary_key.
+      #
+      # Raises InvalidRecordIdError when the same old_id is already mapped to
+      # a different new_id.
+      # : (Class, old_id: untyped, new_id: untyped) -> void
+      def store_new_id: (Class, old_id: untyped, new_id: untyped) -> void
+
+      # Look up a new_id by (klass, old_id). Returns a scalar for a
+      # single-column pk and an Array for a composite pk.
+      #
+      # Raises MissingNewIdError when no mapping exists. This usually means a
+      # belongs_to parent has not been duplicated yet; place it earlier in the
+      # associations tree or register/skip it explicitly.
+      # : (Class, old_id: untyped) -> untyped
+      def fetch_new_id: (Class, old_id: untyped) -> untyped
+
+      # Bulk-insert copies of the given records into klass, skipping any that
+      # are already present in the id map. Handlers can reuse this via HandlerApi
+      # to defer a subset of records to the default duplication path.
+      # : (Class, untyped, ?batch_size: Integer, ?cursor: untyped) -> void
+      def bulk_insert: (Class, untyped, ?batch_size: Integer, ?cursor: untyped) -> void
+
+      # Build the attribute Hash for a single record, ready to be handed to
+      # insert_all!. Timestamps (as reported by
+      # klass.all_timestamp_attributes_in_model, which covers created_at /
+      # updated_at / created_on / updated_on), auto-generated primary key
+      # columns, and every belongs_to foreign key column are stripped; each
+      # belongs_to foreign key is then re-populated from the id map so it
+      # points to the new parent. Non-auto columns of a composite primary key
+      # (e.g. tenant_id) are carried over from the source record unchanged.
+      # : (Class, ActiveRecord::Base) -> Hash[String, untyped]
+      def attributes_for: (Class, ActiveRecord::Base) -> Hash[String, untyped]
+
+      # Run the duplication inside a new, non-joinable transaction and return
+      # the freshly loaded root record. Normally invoked by Duplicator#duplicate.
+      # : (ActiveRecord::Base, ?associations: untyped) -> ActiveRecord::Base
+      def run: (ActiveRecord::Base, ?associations: untyped) -> ActiveRecord::Base
+
+      private
+
+      # : (untyped) -> void
+      def duplicate_records: (untyped) -> void
+
+      # : (Class) -> Proc?
+      def cache_or_resolve_handler: (Class) -> Proc?
+
+      # Look up a handler for `klass` by walking its ancestor chain. Session
+      # -local handlers (Session#on) take precedence over any Duplicator-level
+      # handler, even one registered closer in the ancestor chain: the two
+      # passes below are deliberate, not a refactor opportunity.
+      # : (Class) -> Proc?
+      def resolve_handler: (Class) -> Proc?
+
+      # : (untyped, batch_size: Integer, cursor: untyped) -> untyped
+      def enumerate_batches: (untyped, batch_size: Integer, cursor: untyped) -> untyped
+
+      # Return the id of the given record shaped like the class's primary_key:
+      # a scalar for a single-column pk, an Array for a composite pk.
+      # : (ActiveRecord::Base) -> untyped
+      def current_id: (ActiveRecord::Base) -> untyped
+
+      # Extract the primary key value from a row returned by insert_all!.
+      # Scalar for single-column pk, Array for composite pk.
+      # : (Class, Hash[String, untyped]) -> untyped
+      def extract_id_from_row: (Class, Hash[String, untyped]) -> untyped
+
+      # : (Hash[String, untyped], untyped, ActiveRecord::Base) -> void
+      def assign_foreign_key: (Hash[String, untyped], untyped, ActiveRecord::Base) -> void
+
+      # Primary key columns whose values are filled in by the database (e.g. a
+      # bigserial `id`). These must be stripped from the attributes before
+      # calling insert_all! so the DB can assign fresh values. Composite pk
+      # columns without a default_function (e.g. tenant_id) are kept.
+      # : (Class) -> Array[String]
+      def auto_generated_pk_columns: (Class) -> Array[String]
+    end
+  end
+end

data/sig/generated/active_record/duplicator/version.rbs

@@ -0,0 +1,7 @@
+# Generated from lib/active_record/duplicator/version.rb with RBS::Inline
+
+module ActiveRecord
+  class Duplicator
+    VERSION: ::String
+  end
+end

data/sig/generated/active_record/duplicator.rbs

@@ -0,0 +1,45 @@
+# Generated from lib/active_record/duplicator.rb with RBS::Inline
+
+module ActiveRecord
+  # Reusable duplication configuration and entrypoint.
+  #
+  # A Duplicator holds only per-model handler registrations; it does not hold
+  # any per-run state (the id map lives on Session). Freeze after registering
+  # handlers to enforce immutability across many duplication runs.
+  #
+  # Example:
+  #   duplicator = ActiveRecord::Duplicator.new
+  #   duplicator.on(Attachment) { |api, klass, records| ... }
+  #   duplicator.freeze
+  #
+  #   new_root = duplicator.duplicate(old_root, associations: [...]) do |session|
+  #     session.mark_skip(tenant)
+  #   end
+  class Duplicator
+    @handlers: Hash[Class, Proc]
+
+    # : () -> void
+    def initialize: () -> void
+
+    # Register a custom handler for the given model class. See HandlerApi for
+    # the API the block receives.
+    #
+    # Raises DuplicateHandlerError when the same class is registered twice.
+    # : (Class) { (HandlerApi, Class, untyped) -> void } -> void
+    def on: (Class) { (HandlerApi, Class, untyped) -> void } -> void
+
+    # Prevent further registrations. Also freezes the internal handler map so
+    # accidental mutation later fails loudly.
+    # : () -> self
+    def freeze: () -> self
+
+    # Run one duplication. A fresh Session (with a fresh record id map) is
+    # created for every invocation, so state does not leak between runs.
+    #
+    # If a block is given it is called with the new Session before duplication
+    # starts, letting the caller mark_skip or store_new_id for records that
+    # were duplicated elsewhere.
+    # : (ActiveRecord::Base, ?associations: untyped) ?{ (Session) -> void } -> ActiveRecord::Base
+    def duplicate: (ActiveRecord::Base, ?associations: untyped) ?{ (Session) -> void } -> ActiveRecord::Base
+  end
+end

data/sig/generated/activerecord-duplicator.rbs

@@ -0,0 +1,2 @@
+# Generated from lib/activerecord-duplicator.rb with RBS::Inline
+

metadata

@@ -0,0 +1,96 @@
+--- !ruby/object:Gem::Specification
+name: activerecord-duplicator
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- SmartHR
+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: pg
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.5'
+description: |
+  activerecord-duplicator copies an ActiveRecord record and its associated rows
+  (has_many, has_one, belongs_to, has_many :through) in one call. It rewires
+  foreign keys through an internal id map, bypasses callbacks by using
+  insert_all!, and lets you plug in per-model handlers for records that need
+  custom logic. Composite primary keys (Rails 7.1+) are supported.
+email:
+- oss@smarthr.co.jp
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/active_record/duplicator.rb
+- lib/active_record/duplicator/association_traversal.rb
+- lib/active_record/duplicator/errors.rb
+- lib/active_record/duplicator/handler_api.rb
+- lib/active_record/duplicator/session.rb
+- lib/active_record/duplicator/version.rb
+- lib/activerecord-duplicator.rb
+- sig/generated/active_record/duplicator.rbs
+- sig/generated/active_record/duplicator/association_traversal.rbs
+- sig/generated/active_record/duplicator/errors.rbs
+- sig/generated/active_record/duplicator/handler_api.rbs
+- sig/generated/active_record/duplicator/session.rbs
+- sig/generated/active_record/duplicator/version.rbs
+- sig/generated/activerecord-duplicator.rbs
+homepage: https://github.com/kufu/activerecord-duplicator
+licenses:
+- Apache-2.0
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/kufu/activerecord-duplicator
+  source_code_uri: https://github.com/kufu/activerecord-duplicator
+  changelog_uri: https://github.com/kufu/activerecord-duplicator/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.15
+specification_version: 4
+summary: Duplicate ActiveRecord records together with their associations, backed by
+  bulk inserts.
+test_files: []