activerecord-duplicator 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 017f95574ff90a7fdae2b54b38fd5be60fd6afa33b53a3a59486e159031c9bd1
-  data.tar.gz: a06425a620bae40393fc97b555f0616a8b5bfc87d6e90806089480f4506d3bdf
+  metadata.gz: 0e0c02f84a340928dc7b42bf07eec278113241d6e710c73fed7e2d60c5623617
+  data.tar.gz: 3f9a0fad4af18f5d107358c9b17fc757bada05d0ce432b765820db2e39841dff
 SHA512:
-  metadata.gz: 6dd54a10072d5521a176d1d5957246e033a42a2671e220ffc718f53f6442c4d6329241d0ab41aa1cc852585c697a36666d629d9c5f60c03d5b7dede47f986a97
-  data.tar.gz: afc907dc6fb3026b820eb1273500c53f7d51f0bd8ea960092956f81108253faa3d4795473f1a137133cade12f24365a4f8fb8136ff5831a0196e1cc3526f4bad
+  metadata.gz: 9271005195b8291621f9e86cb61e79ffabcc67de31519af7167b4538600b5cd7551812079b358def18f399d68b63470ae26345a4981a27be64c340c50ed186c0
+  data.tar.gz: 7ad05e575e643f43dba00993b2d835f5e9d3fa00e421da285b0c90617d835efc8a8c4eb271614d71300d228cb6f7fbc2161fbe8f322bdf5dc7204ce494c3637e

data/CHANGELOG.md

@@ -1,12 +1,51 @@
 ## [Unreleased]
 
+## [0.6.0] - 2026-07-08
+
+### Changed (breaking)
+
+- Dropped the hard `pg` runtime dependency. The gem is now
+  adapter-agnostic: any adapter whose connection reports
+  `supports_insert_returning? == true` is supported (PostgreSQL and
+  SQLite >= 3.35 today). Applications add the adapter gem they use
+  (`pg`, `sqlite3`, ...) to their own Gemfile.
+- `Session#bulk_insert` now raises the new
+  `ActiveRecord::Duplicator::UnsupportedAdapterError` when the target
+  connection does not implement `supports_insert_returning?`. Previously the
+  bulk insert silently returned no rows and left the id map incomplete on
+  mysql2 / trilogy. Handlers registered via `Duplicator#on` / `Session#on`
+  are unaffected as long as they do not delegate to `bulk_insert`.
+
+### Added
+
+- `ActiveRecord::Duplicator::UnsupportedAdapterError`: signals that the
+  default duplication path was invoked against a RETURNING-less adapter.
+- The spec suite now runs against SQLite as well as PostgreSQL, driven by an
+  `ARCONN` environment variable (`ARCONN=sqlite3 bundle exec rspec`). CI
+  exercises both adapters on every push and pull request.
+
+### Renamed (breaking)
+
+Public API methods have been renamed to use `duplicate`-prefixed vocabulary
+that matches the gem name and makes the intent clearer:
+
+| Old name | New name |
+|---|---|
+| `mark_skip(record)` | `no_duplicate(record)` |
+| `mark_skip_id(klass, *ids)` | `no_duplicate_id(klass, *ids)` |
+| `mark_skip_class(*klasses)` | `no_duplicate_class(*klasses)` |
+| `store_new_id(klass, old_id:, new_id:)` | `store_duplicate_id(klass, old_id:, new_id:)` |
+| `fetch_new_id(klass, old_id:)` | `fetch_duplicate_id(klass, old_id:)` |
+
+Applies to `Session`, `HandlerApi`, and `Duplicator` (for `no_duplicate_class`).
+
 ## [0.5.0] - 2026-07-07
 
 ### Added
 
-- `Session#mark_skip_id(klass, *ids)` and `HandlerApi#mark_skip_id` —
-  register specific ids as skipped without loading records. Equivalent to
-  calling `mark_skip` on each record but avoids the database round-trip
+- `Session#no_duplicate_id(klass, *ids)` and `HandlerApi#no_duplicate_id`:
+  exclude specific ids from duplication without loading records. Equivalent to
+  calling `no_duplicate` on each record but avoids the database round-trip
   when the ids are already known. Composite primary key ids are passed as
   Arrays.
 
@@ -32,12 +71,12 @@
 
 ### Added
 
-- `Duplicator#mark_skip_class(*klasses)` / `Session#mark_skip_class` /
-  `HandlerApi#mark_skip_class` — class-wide shorthand for `mark_skip`.
+- `Duplicator#no_duplicate_class(*klasses)` / `Session#no_duplicate_class` /
+  `HandlerApi#no_duplicate_class`: class-wide shorthand for `no_duplicate`.
   Behaviour is exactly as if every record of the class had been passed
-  to `mark_skip` beforehand: handlers registered for the class still
+  to `no_duplicate` beforehand: handlers registered for the class still
   fire, the default `bulk_insert` path becomes a no-op, and
-  `fetch_new_id(klass, old_id: ...)` echoes `old_id` back unchanged.
+  `fetch_duplicate_id(klass, old_id: ...)` echoes `old_id` back unchanged.
   The Duplicator-level registration is inherited by every subsequent
   `duplicate` run; Session-level additions apply only to the current run.
 
@@ -72,8 +111,8 @@
 
 ## [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 `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/README.md

@@ -23,8 +23,20 @@ gem install activerecord-duplicator
 
 - 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.
+- A database adapter whose connection reports
+  `supports_insert_returning? == true`. The default duplication path uses
+  `insert_all!` and needs the adapter to echo inserted primary keys back so
+  the id map can be populated in a single round trip.
+  - PostgreSQL (via `pg`): always supported.
+  - SQLite (via `sqlite3`): SQLite >= 3.35 is required; the modern
+    `sqlite3` gem ships a compatible native binary.
+  - MySQL / Trilogy: not supported by the default path because those
+    adapters do not implement RETURNING. Duplication of specific models can
+    still be done through a custom handler registered with `Duplicator#on`
+    (see below).
+
+The gem does not depend on a specific adapter gem; applications add whichever
+one they use (`pg`, `sqlite3`, ...) to their own Gemfile.
 
 ## Non-goals
 
@@ -54,16 +66,16 @@ new_post = duplicator.duplicate(
 `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`)
+### Keeping records referenced but not copied (`no_duplicate`)
 
 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`:
+call no_duplicate on that record before calling `duplicate`:
 
 ```ruby
 duplicator = ActiveRecord::Duplicator.new
-duplicator.mark_skip(tenant)
-duplicator.mark_skip(current_user)
+duplicator.no_duplicate(tenant)
+duplicator.no_duplicate(current_user)
 
 duplicator.duplicate(old_project, associations: [tasks: :attachments])
 ```
@@ -71,55 +83,55 @@ 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.
 
-### Skipping a whole model (`mark_skip_class`)
+### Skipping a whole model (`no_duplicate_class`)
 
 When every row of a model should be reused by id (a shared lookup table,
-a tenant-wide catalog, an enum-backed table with dozens of entries), skip
-the class itself instead of enumerating rows. `mark_skip_class` exists at
+a tenant-wide catalog, an enum-backed table with dozens of entries), call no_duplicate_class
+the class itself instead of enumerating rows. `no_duplicate_class` exists at
 both scopes and mirrors `on`: register once on the Duplicator to inherit
 across every run, or add it in the Session block for a single run.
 
 ```ruby
 duplicator = ActiveRecord::Duplicator.new
-duplicator.mark_skip_class(Tag)           # applies to every subsequent run
+duplicator.no_duplicate_class(Tag)           # applies to every subsequent run
 
 duplicator.duplicate(old_post, associations: [:taggings])
 
 duplicator.duplicate(other_post, associations: [:taggings]) do |session|
-  session.mark_skip_class(Currency)       # extra skip, this run only
+  session.no_duplicate_class(Currency)       # extra exclusion, this run only
 end
 ```
 
-Behaviour is exactly as if you had passed every row to `mark_skip` up front:
+Behaviour is exactly as if you had passed every row to `no_duplicate` up front:
 handlers registered for the class still fire (so custom copy logic keeps
 working), but the default `bulk_insert` path becomes a no-op and any
-`fetch_new_id(klass, old_id: ...)` from a child's foreign-key reassignment
-echoes the old id back unchanged. `mark_skip_class` only differs from
-per-record `mark_skip` in cost: no enumeration is needed to opt each row in.
+`fetch_duplicate_id(klass, old_id: ...)` from a child's foreign-key reassignment
+echoes the old id back unchanged. `no_duplicate_class` only differs from
+per-record `no_duplicate` in cost: no enumeration is needed to opt each row in.
 
-### Skipping by id without loading records (`mark_skip_id`)
+### Skipping by id without loading records (`no_duplicate_id`)
 
-When the ids to skip are already known (a foreign key column, a prior
-pluck, a config constant), use `mark_skip_id` to register them directly
+When the ids are already known (a foreign key column, a prior
+pluck, a config constant), use `no_duplicate_id` to register them directly
 without issuing a `SELECT`:
 
 ```ruby
 duplicator.duplicate(old_post, associations: [:taggings]) do |session|
-  session.mark_skip_id(Tag, 1, 2, 3)
+  session.no_duplicate_id(Tag, 1, 2, 3)
 end
 ```
 
 For composite primary keys pass each id as an Array:
 
 ```ruby
-session.mark_skip_id(Item, [tenant_id, 10], [tenant_id, 11])
+session.no_duplicate_id(Item, [tenant_id, 10], [tenant_id, 11])
 ```
 
-`mark_skip_id` has the same effect as calling `mark_skip` on the
-corresponding records: `fetch_new_id` returns the old id unchanged for
+`no_duplicate_id` has the same effect as calling `no_duplicate` on the
+corresponding records: `fetch_duplicate_id` returns the old id unchanged for
 each registered id.
 
-### Registering an id from outside (`store_new_id` / `fetch_new_id`)
+### Registering an id from outside (`store_duplicate_id` / `fetch_duplicate_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
@@ -131,11 +143,11 @@ 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.store_duplicate_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
+`fetch_duplicate_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.
 
@@ -150,16 +162,16 @@ called instead of the default duplication path for that class:
 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),
+      post_id: api.fetch_duplicate_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)
+    api.store_duplicate_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` /
+`no_duplicate` / `store_duplicate_id` / `fetch_duplicate_id` / `bulk_insert` /
 `attributes_for`. Registering two handlers for the same class raises
 `DuplicateHandlerError`.
 
@@ -175,11 +187,16 @@ tuple `WHERE (a, b) IN ((v1, v2), ...)` syntax.
 
 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
+- `InvalidRecordIdError`: the same `old_id` was registered with a different `new_id`.
+- `MissingNewIdError`: `fetch_duplicate_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.
+  associations tree, or call no_duplicate / no_duplicate_id on it.
+- `DuplicateHandlerError`: `on(klass)` was called twice for the same class.
+- `UnsupportedAdapterError`: the default `bulk_insert` was invoked against a
+  connection whose adapter does not implement `supports_insert_returning?`
+  (for example mysql2 or trilogy). Register a handler with
+  `Duplicator#on` / `Session#on` that uses `create!` (or another
+  RETURNING-free path) for that model.
 
 Because they share a common ancestor, one `rescue` clause catches any
 duplication-specific failure:
@@ -202,8 +219,8 @@ 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:
+The gem tests against a real database. `compose.yml` at the repo root starts a
+PostgreSQL instance for you on port 55432:
 
 ```bash
 docker compose up -d
@@ -213,12 +230,22 @@ bundle exec rake       # rspec + rubocop
 bundle exec rspec      # spec only
 ```
 
-Override the connection with `DATABASE_URL` (used by CI):
+Switch adapters with `ARCONN`; SQLite runs against an in-memory database and
+needs no external service:
+
+```bash
+ARCONN=postgresql bundle exec rspec   # default (uses DATABASE_URL)
+ARCONN=sqlite3    bundle exec rspec
+```
+
+Override the PostgreSQL connection with `DATABASE_URL` (used by CI):
 
 ```bash
 DATABASE_URL=postgres://user:pass@host:port/db bundle exec rspec
 ```
 
+Both adapters are exercised in CI on every push and pull request.
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at

data/lib/active_record/duplicator/errors.rb

@@ -4,18 +4,28 @@ 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.
+    # Raised when store_duplicate_id (or no_duplicate) 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.
+    # Raised when fetch_duplicate_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.
+    # place the parent earlier in the associations tree, or call no_duplicate /
+    # no_duplicate_id on it explicitly.
     class MissingNewIdError < Error; end
 
     # Raised when Session#on is called twice for the same model class.
     class DuplicateHandlerError < Error; end
+
+    # Raised when a bulk_insert is attempted against a connection whose adapter
+    # does not implement `supports_insert_returning?`. The default duplication
+    # path relies on `insert_all!` returning the inserted primary keys so the
+    # id map can be populated in one round trip; adapters that do not support
+    # RETURNING (e.g. mysql2, trilogy) cannot participate in this flow.
+    #
+    # Register a handler with `Duplicator#on` / `Session#on` that uses
+    # `create!` (or similar) if you need to duplicate rows on such an adapter.
+    class UnsupportedAdapterError < Error; end
   end
 end

data/lib/active_record/duplicator/handler_api.rb

@@ -15,28 +15,28 @@ module ActiveRecord
       end
 
       #: (*ActiveRecord::Base) -> void
-      def mark_skip(...)
-        @session.mark_skip(...)
+      def no_duplicate(...)
+        @session.no_duplicate(...)
       end
 
       #: (Class, *untyped) -> void
-      def mark_skip_id(...)
-        @session.mark_skip_id(...)
+      def no_duplicate_id(...)
+        @session.no_duplicate_id(...)
       end
 
       #: (*Class) -> void
-      def mark_skip_class(...)
-        @session.mark_skip_class(...)
+      def no_duplicate_class(...)
+        @session.no_duplicate_class(...)
       end
 
       #: (Class, old_id: untyped, new_id: untyped) -> void
-      def store_new_id(...)
-        @session.store_new_id(...)
+      def store_duplicate_id(...)
+        @session.store_duplicate_id(...)
       end
 
       #: (Class, old_id: untyped) -> untyped
-      def fetch_new_id(...)
-        @session.fetch_new_id(...)
+      def fetch_duplicate_id(...)
+        @session.fetch_duplicate_id(...)
       end
 
       #: (Class, untyped, ?batch_size: Integer, ?cursor: untyped) -> void

data/lib/active_record/duplicator/session.rb

@@ -5,13 +5,13 @@ module ActiveRecord
     # 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.
+    # exposes the API a handler needs: no_duplicate / store_duplicate_id /
+    # fetch_duplicate_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.
+    # callers can no_duplicate / store_duplicate_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
@@ -24,16 +24,16 @@ module ActiveRecord
       # @rbs @record_id_map: Hash[Class, Hash[untyped, untyped]]
       # @rbs @handlers: Hash[Class, Proc]
       # @rbs @user_handlers: Hash[Class, Proc]
-      # @rbs @skipped_classes: Set[Class]
+      # @rbs @no_duplicate_classes: Set[Class]
 
-      #: (?handlers: Hash[Class, Proc], ?skipped_classes: Set[Class]) -> void
-      def initialize(handlers: {}, skipped_classes: Set.new)
+      #: (?handlers: Hash[Class, Proc], ?no_duplicate_classes: Set[Class]) -> void
+      def initialize(handlers: {}, no_duplicate_classes: Set.new)
         @record_id_map = Hash.new { |hash, klass| hash[klass] = {} }
         @handlers = handlers
         @user_handlers = {}
-        # dup so that Session#mark_skip_class additions never leak back to the
+        # dup so that Session#no_duplicate_class additions never leak back to the
         # Duplicator-level set shared across every run.
-        @skipped_classes = skipped_classes.dup
+        @no_duplicate_classes = no_duplicate_classes.dup
       end
 
       # Register a handler that overrides Duplicator#on for the current session
@@ -54,36 +54,36 @@ module ActiveRecord
       # 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)
+      def no_duplicate(*records)
         records.each do |record|
           id = current_id(record)
-          store_new_id(record.class, old_id: id, new_id: id)
+          store_duplicate_id(record.class, old_id: id, new_id: id)
         end
       end
 
       # Declare that the given ids of the given class must not be duplicated,
-      # without loading the records. Equivalent to calling mark_skip on each
+      # without loading the records. Equivalent to calling no_duplicate on each
       # record but avoids the database round-trip when the ids are already
       # known. Each id should have the same shape as the class's primary key
       # (scalar for a single-column pk, Array for a composite pk).
       #: (Class, *untyped) -> void
-      def mark_skip_id(klass, *ids)
-        ids.each { |id| store_new_id(klass, old_id: id, new_id: id) }
+      def no_duplicate_id(klass, *ids)
+        ids.each { |id| store_duplicate_id(klass, old_id: id, new_id: id) }
       end
 
-      # Class-wide equivalent of mark_skip: it is exactly as if every record of
-      # each given class had been passed to mark_skip. Handlers still fire
-      # (matching the mark_skip case where a handler for the class is invoked
-      # with a Relation that happens to contain pre-skipped records); the
-      # default bulk_insert path becomes a no-op, and fetch_new_id echoes the
-      # queried old_id back unchanged.
+      # Class-wide equivalent of no_duplicate: it is exactly as if every record
+      # of each given class had been passed to no_duplicate. Handlers still fire
+      # (matching the no_duplicate case where a handler for the class is invoked
+      # with a Relation that happens to contain no_duplicate records); the
+      # default bulk_insert path becomes a no-op, and fetch_duplicate_id echoes
+      # the queried old_id back unchanged.
       #
       # Use when the target database is expected to already hold every
       # referenced row (shared lookup tables, tenant-wide catalogs, etc.), so
-      # per-record mark_skip would only differ from this in cost, not effect.
+      # per-record no_duplicate would only differ from this in cost, not effect.
       #: (*Class) -> void
-      def mark_skip_class(*klasses)
-        @skipped_classes.merge(klasses)
+      def no_duplicate_class(*klasses)
+        @no_duplicate_classes.merge(klasses)
       end
 
       # Record a mapping from an old_id to a new_id. Called automatically from
@@ -96,7 +96,7 @@ module ActiveRecord
       # 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:)
+      def store_duplicate_id(klass, old_id:, new_id:)
         map = @record_id_map[klass]
 
         if !map.key?(old_id)
@@ -113,26 +113,28 @@ module ActiveRecord
       #
       # 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.
+      # associations tree, or call no_duplicate / no_duplicate_id explicitly.
       #: (Class, old_id: untyped) -> untyped
-      def fetch_new_id(klass, old_id:)
-        return old_id if @skipped_classes.include?(klass)
+      def fetch_duplicate_id(klass, old_id:)
+        return old_id if @no_duplicate_classes.include?(klass)
 
         @record_id_map[klass].fetch(old_id) do
-          raise MissingNewIdError, "no new_id registered for #{klass}##{old_id.inspect}"
+          raise MissingNewIdError, "no duplicate id registered for #{klass}##{old_id.inspect}"
         end
       end
 
-      # Bulk-insert copies of the given records into klass, skipping any that
+      # Bulk-insert copies of the given records into klass, omitting 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.
       #
-      # When klass has been passed to mark_skip_class the call is a no-op that
+      # When klass has been passed to no_duplicate_class the call is a no-op that
       # never touches the DB: it is equivalent to having pre-registered every
-      # incoming record via mark_skip, only without the per-record enumeration.
+      # incoming record via no_duplicate, only without the per-record enumeration.
       #: (Class, untyped, ?batch_size: Integer, ?cursor: untyped) -> void
       def bulk_insert(klass, records, batch_size: DEFAULT_BATCH_SIZE, cursor: nil)
-        return if @skipped_classes.include?(klass)
+        return if @no_duplicate_classes.include?(klass)
+
+        ensure_insert_returning_supported!(klass)
 
         batches = enumerate_batches(records, batch_size:, cursor:)
 
@@ -147,7 +149,7 @@ module ActiveRecord
           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:)
+            store_duplicate_id(klass, old_id:, new_id:)
           end
         end
       end
@@ -189,7 +191,7 @@ module ActiveRecord
             duplicate_records(relation.klass, relation)
           end
 
-          new_id = fetch_new_id(root_record.class, old_id: current_id(root_record))
+          new_id = fetch_duplicate_id(root_record.class, old_id: current_id(root_record))
           root_record.class.find(new_id)
         end
       end
@@ -201,9 +203,9 @@ module ActiveRecord
       # caller is responsible for splitting mixed inputs (e.g. STI subclasses)
       # into per-class Relations and passing the matching class in.
       #
-      # mark_skip_class does NOT short-circuit here: handlers must still fire
-      # (mirroring the per-record mark_skip case), and the class-wide skip is
-      # applied inside bulk_insert instead.
+      # no_duplicate_class does NOT short-circuit here: handlers must still fire
+      # (mirroring the per-record no_duplicate case), and the class-wide exclusion
+      # is applied inside bulk_insert instead.
       #: (Class, untyped) -> void
       def duplicate_records(klass, relation_or_records)
         handler = resolve_handler(klass)
@@ -266,26 +268,46 @@ module ActiveRecord
           if old_values.all?(&:nil?)
             fk.each { |c| attrs[c] = nil }
           else
-            new_values = fetch_new_id(reflection.klass, old_id: old_values)
+            new_values = fetch_duplicate_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)
+          attrs[fk] = old_value.nil? ? nil : fetch_duplicate_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.
+      # bigserial `id`, a SQLite INTEGER PRIMARY KEY / ROWID alias, a column
+      # with a `default_function` such as `gen_random_uuid()`). These must be
+      # stripped from the attributes before calling insert_all! so the DB can
+      # assign fresh values. Composite pk columns without a default (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?
+          column.auto_populated?
         end
       end
+
+      # Guard against adapters that cannot return inserted primary keys.
+      # The default path relies on `insert_all!(...)` echoing back the pk of
+      # every inserted row so the id map can be populated in one round trip;
+      # adapters that do not support RETURNING silently return an empty
+      # inserted-row set and would leave the map incomplete.
+      #: (Class) -> void
+      def ensure_insert_returning_supported!(klass)
+        connection = klass.connection
+        return if connection.supports_insert_returning?
+
+        raise UnsupportedAdapterError,
+          "#{connection.adapter_name} does not support insert with RETURNING. " \
+          "activerecord-duplicator requires an adapter whose " \
+          "`supports_insert_returning?` returns true (e.g. PostgreSQL, or " \
+          "SQLite >= 3.35). Register a custom handler with `on(#{klass})` " \
+          "if you need to duplicate #{klass} on this adapter."
+      end
     end
   end
 end

data/lib/active_record/duplicator/version.rb

@@ -2,6 +2,6 @@
 
 module ActiveRecord
   class Duplicator
-    VERSION = "0.5.0"
+    VERSION = "0.6.0"
   end
 end

data/lib/active_record/duplicator.rb

@@ -15,16 +15,16 @@ module ActiveRecord
   #   duplicator.freeze
   #
   #   new_root = duplicator.duplicate(old_root, associations: [...]) do |session|
-  #     session.mark_skip(tenant)
+  #     session.no_duplicate(tenant)
   #   end
   class Duplicator
     # @rbs @handlers: Hash[Class, Proc]
-    # @rbs @skipped_classes: Set[Class]
+    # @rbs @no_duplicate_classes: Set[Class]
 
     #: () -> void
     def initialize
       @handlers = {}
-      @skipped_classes = Set.new
+      @no_duplicate_classes = Set.new
     end
 
     # Register a custom handler for the given model class. See HandlerApi for
@@ -39,13 +39,13 @@ module ActiveRecord
     end
 
     # Declare that every record of the given classes must not be duplicated in
-    # any subsequent run. See Session#mark_skip_class for the semantics; the
+    # any subsequent run. See Session#no_duplicate_class for the semantics; the
     # Duplicator-level registration is applied to every fresh Session as its
-    # baseline, and Session#mark_skip_class can extend it for a single run.
+    # baseline, and Session#no_duplicate_class can extend it for a single run.
     # Repeated calls with the same class are idempotent.
     #: (*Class) -> void
-    def mark_skip_class(*klasses)
-      @skipped_classes.merge(klasses)
+    def no_duplicate_class(*klasses)
+      @no_duplicate_classes.merge(klasses)
     end
 
     # Prevent further registrations. Also freezes the internal handler map so
@@ -53,7 +53,7 @@ module ActiveRecord
     #: () -> self
     def freeze
       @handlers.freeze
-      @skipped_classes.freeze
+      @no_duplicate_classes.freeze
       super
     end
 
@@ -61,15 +61,15 @@ module ActiveRecord
     # 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.
+    # starts, letting the caller no_duplicate or store_duplicate_id for records
+    # that were duplicated elsewhere.
     #
     # transaction_options is forwarded verbatim to Session#run, which forwards
     # it to `root_record.transaction`. Default is `{}` (plain
     # `transaction do ... end`).
     #: (ActiveRecord::Base, ?associations: untyped, ?transaction_options: Hash[Symbol, untyped]) ?{ (Session) -> void } -> ActiveRecord::Base
     def duplicate(root_record, associations: [], transaction_options: {}, &block)
-      session = Session.new(handlers: @handlers, skipped_classes: @skipped_classes)
+      session = Session.new(handlers: @handlers, no_duplicate_classes: @no_duplicate_classes)
       block&.call(session)
       session.run(root_record, associations:, transaction_options:)
     end

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

@@ -5,21 +5,32 @@ module ActiveRecord
     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.
+    # Raised when store_duplicate_id (or no_duplicate) 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.
+    # Raised when fetch_duplicate_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.
+    # place the parent earlier in the associations tree, or call no_duplicate /
+    # no_duplicate_id on it explicitly.
     class MissingNewIdError < Error
     end
 
     # Raised when Session#on is called twice for the same model class.
     class DuplicateHandlerError < Error
     end
+
+    # Raised when a bulk_insert is attempted against a connection whose adapter
+    # does not implement `supports_insert_returning?`. The default duplication
+    # path relies on `insert_all!` returning the inserted primary keys so the
+    # id map can be populated in one round trip; adapters that do not support
+    # RETURNING (e.g. mysql2, trilogy) cannot participate in this flow.
+    #
+    # Register a handler with `Duplicator#on` / `Session#on` that uses
+    # `create!` (or similar) if you need to duplicate rows on such an adapter.
+    class UnsupportedAdapterError < Error
+    end
   end
 end

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

@@ -13,19 +13,19 @@ module ActiveRecord
       def initialize: (Session) -> void
 
       # : (*ActiveRecord::Base) -> void
-      def mark_skip: (*ActiveRecord::Base) -> void
+      def no_duplicate: (*ActiveRecord::Base) -> void
 
       # : (Class, *untyped) -> void
-      def mark_skip_id: (Class, *untyped) -> void
+      def no_duplicate_id: (Class, *untyped) -> void
 
       # : (*Class) -> void
-      def mark_skip_class: (*Class) -> void
+      def no_duplicate_class: (*Class) -> void
 
       # : (Class, old_id: untyped, new_id: untyped) -> void
-      def store_new_id: (Class, old_id: untyped, new_id: untyped) -> void
+      def store_duplicate_id: (Class, old_id: untyped, new_id: untyped) -> void
 
       # : (Class, old_id: untyped) -> untyped
-      def fetch_new_id: (Class, old_id: untyped) -> untyped
+      def fetch_duplicate_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

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

@@ -5,13 +5,13 @@ module ActiveRecord
     # 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.
+    # exposes the API a handler needs: no_duplicate / store_duplicate_id /
+    # fetch_duplicate_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.
+    # callers can no_duplicate / store_duplicate_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
@@ -20,7 +20,7 @@ module ActiveRecord
     class Session
       DEFAULT_BATCH_SIZE: ::Integer
 
-      @skipped_classes: Set[Class]
+      @no_duplicate_classes: Set[Class]
 
       @user_handlers: Hash[Class, Proc]
 
@@ -28,8 +28,8 @@ module ActiveRecord
 
       @record_id_map: Hash[Class, Hash[untyped, untyped]]
 
-      # : (?handlers: Hash[Class, Proc], ?skipped_classes: Set[Class]) -> void
-      def initialize: (?handlers: Hash[Class, Proc], ?skipped_classes: Set[Class]) -> void
+      # : (?handlers: Hash[Class, Proc], ?no_duplicate_classes: Set[Class]) -> void
+      def initialize: (?handlers: Hash[Class, Proc], ?no_duplicate_classes: Set[Class]) -> 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
@@ -45,28 +45,28 @@ module ActiveRecord
       # 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
+      def no_duplicate: (*ActiveRecord::Base) -> void
 
       # Declare that the given ids of the given class must not be duplicated,
-      # without loading the records. Equivalent to calling mark_skip on each
+      # without loading the records. Equivalent to calling no_duplicate on each
       # record but avoids the database round-trip when the ids are already
       # known. Each id should have the same shape as the class's primary key
       # (scalar for a single-column pk, Array for a composite pk).
       # : (Class, *untyped) -> void
-      def mark_skip_id: (Class, *untyped) -> void
-
-      # Class-wide equivalent of mark_skip: it is exactly as if every record of
-      # each given class had been passed to mark_skip. Handlers still fire
-      # (matching the mark_skip case where a handler for the class is invoked
-      # with a Relation that happens to contain pre-skipped records); the
-      # default bulk_insert path becomes a no-op, and fetch_new_id echoes the
-      # queried old_id back unchanged.
+      def no_duplicate_id: (Class, *untyped) -> void
+
+      # Class-wide equivalent of no_duplicate: it is exactly as if every record
+      # of each given class had been passed to no_duplicate. Handlers still fire
+      # (matching the no_duplicate case where a handler for the class is invoked
+      # with a Relation that happens to contain no_duplicate records); the
+      # default bulk_insert path becomes a no-op, and fetch_duplicate_id echoes
+      # the queried old_id back unchanged.
       #
       # Use when the target database is expected to already hold every
       # referenced row (shared lookup tables, tenant-wide catalogs, etc.), so
-      # per-record mark_skip would only differ from this in cost, not effect.
+      # per-record no_duplicate would only differ from this in cost, not effect.
       # : (*Class) -> void
-      def mark_skip_class: (*Class) -> void
+      def no_duplicate_class: (*Class) -> 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
@@ -78,24 +78,24 @@ module ActiveRecord
       # 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
+      def store_duplicate_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.
+      # associations tree, or call no_duplicate / no_duplicate_id explicitly.
       # : (Class, old_id: untyped) -> untyped
-      def fetch_new_id: (Class, old_id: untyped) -> untyped
+      def fetch_duplicate_id: (Class, old_id: untyped) -> untyped
 
-      # Bulk-insert copies of the given records into klass, skipping any that
+      # Bulk-insert copies of the given records into klass, omitting 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.
       #
-      # When klass has been passed to mark_skip_class the call is a no-op that
+      # When klass has been passed to no_duplicate_class the call is a no-op that
       # never touches the DB: it is equivalent to having pre-registered every
-      # incoming record via mark_skip, only without the per-record enumeration.
+      # incoming record via no_duplicate, only without the per-record enumeration.
       # : (Class, untyped, ?batch_size: Integer, ?cursor: untyped) -> void
       def bulk_insert: (Class, untyped, ?batch_size: Integer, ?cursor: untyped) -> void
 
@@ -128,9 +128,9 @@ module ActiveRecord
       # caller is responsible for splitting mixed inputs (e.g. STI subclasses)
       # into per-class Relations and passing the matching class in.
       #
-      # mark_skip_class does NOT short-circuit here: handlers must still fire
-      # (mirroring the per-record mark_skip case), and the class-wide skip is
-      # applied inside bulk_insert instead.
+      # no_duplicate_class does NOT short-circuit here: handlers must still fire
+      # (mirroring the per-record no_duplicate case), and the class-wide exclusion
+      # is applied inside bulk_insert instead.
       # : (Class, untyped) -> void
       def duplicate_records: (Class, untyped) -> void
 
@@ -156,11 +156,21 @@ module ActiveRecord
       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.
+      # bigserial `id`, a SQLite INTEGER PRIMARY KEY / ROWID alias, a column
+      # with a `default_function` such as `gen_random_uuid()`). These must be
+      # stripped from the attributes before calling insert_all! so the DB can
+      # assign fresh values. Composite pk columns without a default (e.g.
+      # tenant_id) are kept.
       # : (Class) -> Array[String]
       def auto_generated_pk_columns: (Class) -> Array[String]
+
+      # Guard against adapters that cannot return inserted primary keys.
+      # The default path relies on `insert_all!(...)` echoing back the pk of
+      # every inserted row so the id map can be populated in one round trip;
+      # adapters that do not support RETURNING silently return an empty
+      # inserted-row set and would leave the map incomplete.
+      # : (Class) -> void
+      def ensure_insert_returning_supported!: (Class) -> void
     end
   end
 end

data/sig/generated/active_record/duplicator.rbs

@@ -13,12 +13,12 @@ module ActiveRecord
   #   duplicator.freeze
   #
   #   new_root = duplicator.duplicate(old_root, associations: [...]) do |session|
-  #     session.mark_skip(tenant)
+  #     session.no_duplicate(tenant)
   #   end
   class Duplicator
     @handlers: Hash[Class, Proc]
 
-    @skipped_classes: Set[Class]
+    @no_duplicate_classes: Set[Class]
 
     # : () -> void
     def initialize: () -> void
@@ -31,12 +31,12 @@ module ActiveRecord
     def on: (Class) { (HandlerApi, Class, untyped) -> void } -> void
 
     # Declare that every record of the given classes must not be duplicated in
-    # any subsequent run. See Session#mark_skip_class for the semantics; the
+    # any subsequent run. See Session#no_duplicate_class for the semantics; the
     # Duplicator-level registration is applied to every fresh Session as its
-    # baseline, and Session#mark_skip_class can extend it for a single run.
+    # baseline, and Session#no_duplicate_class can extend it for a single run.
     # Repeated calls with the same class are idempotent.
     # : (*Class) -> void
-    def mark_skip_class: (*Class) -> void
+    def no_duplicate_class: (*Class) -> void
 
     # Prevent further registrations. Also freezes the internal handler map so
     # accidental mutation later fails loudly.
@@ -47,8 +47,8 @@ module ActiveRecord
     # 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.
+    # starts, letting the caller no_duplicate or store_duplicate_id for records
+    # that were duplicated elsewhere.
     #
     # transaction_options is forwarded verbatim to Session#run, which forwards
     # it to `root_record.transaction`. Default is `{}` (plain

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: activerecord-duplicator
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - SmartHR
@@ -23,20 +23,6 @@ dependencies:
     - - ">="
       - !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