activerecord-returning 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fc65ae5a23d01e74129297d8c261a737b12a7d0704c3603db5b80c071cc1bb5f
+  data.tar.gz: 4bad36a8d5323405454f44df90390e08d054123f4c8b852cb142a69bfa98b0e5
+SHA512:
+  metadata.gz: 00bd98c430785df957ee8442c02adfa06aa1db3fe53ff7923605b6758d18c76a580f09b143dc9d840bb0dc8d58486d125c0f1d4416634d7352f05978b93b0f64
+  data.tar.gz: f7d0fbfe27e2eb1bff15b72f68442d260fea48792ca66ebf837dbb5839b1f2b6acd72fb55ff783ed8d3708d0cf34ca97d3e20fe9ad9d669b2a9f4eff68a217af

data/CHANGELOG.md

@@ -0,0 +1,70 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Fixed
+
+- A relation with `from` no longer changes every row in the table. The primary key subquery selects
+  `table.id` while `from` renames the table it reads, so the database read `table.id` as a reference to the
+  row being changed and matched all of them — a whole-table `UPDATE`/`DELETE` from a relation that selected
+  a few rows. It raises `ActiveRecord::Returning::Error` now, pointing at `unscope(:from)`.
+
+### Added
+
+- A combination test suite: every relation shape — and combinations of them — run through both
+  `update_all_returning` and `delete_all_returning`, asserting the rows the relation selects are the rows
+  returned, the rows returned are the rows the database changed, and nothing else moved.
+
+### Notes
+
+- Documented that `delete_all_returning` on a `has_many` deletes rows, while `delete_all` on the same
+  association nullifies the foreign key unless it declares `dependent: :delete_all`.
+
+## [0.1.0] - 2026-08-21
+
+Initial release.
+
+### Added
+
+- `ActiveRecord::Relation#update_all_returning(updates, returning: nil)` — runs an `UPDATE ... RETURNING`
+  over the current scope and returns the changed rows as an `ActiveRecord::Result`.
+- `ActiveRecord::Relation#delete_all_returning(returning: nil)` — the same for `DELETE ... RETURNING`.
+- `returning:` accepts a symbol, an array of symbols, `:_all` for `RETURNING *`, or `Arel.sql` for raw SQL.
+  It defaults to the primary key, including composite primary keys on Rails 7.1+. `:all` raises pointing at
+  `:_all` (it could be a real column name), and so does `:_all` combined with other columns.
+- Optimistic locking support: the locking column is incremented exactly as `update_all` does, unless the
+  caller sets it explicitly.
+- Both methods are also delegated onto the model class, like `update_all`, so `User.update_all_returning(...)`
+  works and not only `User.where(...).update_all_returning(...)`.
+- `ActiveRecord::Returning::Error` and `ActiveRecord::Returning::UnsupportedAdapter`, raised on adapters
+  without `RETURNING` support (MySQL, MariaDB, SQLite older than 3.35), on eager-loaded relations, and on
+  models without a primary key.
+
+### Notes
+
+- The query cache is cleared after each statement, both thread-wide (as `update_all` does, so a
+  primary/replica setup does not keep a stale entry) and on the connection written through. Rails 7.0's
+  `exec_query` does not dirty the cache, and its thread-wide clear is itself a no-op under the default
+  `legacy_connection_handling`.
+- A relation with `group` or `having` raises rather than building a subquery the database rejects, and an
+  empty `returning:` list raises instead of emitting a bare `RETURNING`.
+- Adapter support prefers `supports_update_returning?` where it exists, falling back to
+  `supports_insert_returning?` — with the MySQL family excluded explicitly, because MariaDB answers
+  `supports_insert_returning?` with `true` (it has `INSERT ... RETURNING` since 10.5) while having no
+  `UPDATE ... RETURNING` at all. CI has a MariaDB lane.
+- `alias_attribute` names are resolved in both `updates` and `returning:`, as `update_all` and `pluck` do.
+  A returned alias keeps the caller's name: `RETURNING "title" AS "headline"`.
+- Active Record is capped at `< 8.2` because rails/rails#57073 proposes an upstream `update_all_returning`
+  with a different API. If a relation already defines these methods, the gem leaves them alone and warns.
+
+- PostgreSQL and SQLite 3.35+ only. `ActiveRecord::Returning.supported?` decides, and the notes below
+  describe exactly how.
+- Both methods are additive: nothing in Active Record is overridden or prepended.
+- Callbacks, validations and timestamps are skipped, exactly as with `update_all`/`delete_all`.
+
+[Unreleased]: https://github.com/igorkasyanchuk/activerecord-returning/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/igorkasyanchuk/activerecord-returning/releases/tag/v0.1.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Igor Kasyanchuk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,357 @@
+# activerecord-returning
+
+[![Gem Version](https://badge.fury.io/rb/activerecord-returning.svg)](https://rubygems.org/gems/activerecord-returning)
+[![CI](https://github.com/igorkasyanchuk/activerecord-returning/actions/workflows/ci.yml/badge.svg)](https://github.com/igorkasyanchuk/activerecord-returning/actions/workflows/ci.yml)
+
+**`update_all` tells you how many rows changed. This gem tells you which ones.**
+
+![update_all returns a count; update_all_returning returns the rows](docs/demo.gif)
+
+```ruby
+User.where(role: :admin).update_all(role: :member)
+# => 2                                    ...which two?
+
+User.where(role: :admin).update_all_returning({ role: :member }, returning: %i[id email])
+# => #<ActiveRecord::Result [[1, "ada@example.com"], [2, "grace@example.com"]]>
+```
+
+One statement. No `pluck` first, no `FOR UPDATE`, no window where another process can change the set
+underneath you.
+
+## TL;DR
+
+```ruby
+gem "activerecord-returning"
+```
+
+```ruby
+# every form of update_all, plus returning:
+User.where(role: :admin).update_all_returning(role: :member)                    # => primary keys
+User.where(role: :admin).update_all_returning({ role: :member }, returning: :email)
+User.where(role: :admin).update_all_returning({ role: :member }, returning: %i[id email])
+User.where(role: :admin).update_all_returning({ role: :member }, returning: :_all)     # RETURNING *
+User.update_all_returning(role: :member)                                        # on the model, too
+
+Session.where(expires_at: ..1.week.ago).delete_all_returning(returning: :user_id)
+```
+
+Always returns an `ActiveRecord::Result`. PostgreSQL and SQLite 3.35+. Rails 7.0–8.1. Nothing is
+overridden — `update_all` and `delete_all` behave exactly as before.
+
+## Why
+
+Every bulk change ends with the same question: *and then what?* Enqueue jobs for the rows you touched,
+write an audit entry, send the mail, invalidate the cache. `update_all` hands back an Integer, so people
+reach for one of these:
+
+```ruby
+# Racy. Another process can change the set between the two statements.
+ids = Session.where(expires_at: ..1.week.ago).pluck(:id)
+Session.where(id: ids).delete_all
+
+# Correct, but three statements, a transaction and a lock you have to remember.
+Session.transaction do
+  ids = Session.where(expires_at: ..1.week.ago).lock.pluck(:id)
+  Session.where(id: ids).delete_all
+  ids
+end
+```
+
+Databases have solved this for years with `RETURNING`. Rails exposes it on `insert_all`/`upsert_all` via a
+`returning:` kwarg — but not on `update_all`/`delete_all`. Proposed upstream more than once, still not
+merged as of Rails 8.1. This gem adds the two methods, using only public Active Record API.
+
+## Examples
+
+**Expire sessions, notify their owners**
+
+```ruby
+expired = Session.where(expires_at: ..Time.current).delete_all_returning(returning: :user_id)
+
+expired.rows.flatten.uniq.each { |user_id| SessionExpiredMailer.notify(user_id).deliver_later }
+```
+
+**Claim work without a race**
+
+```ruby
+claimed = Job.pending.order(:created_at).limit(1)
+             .update_all_returning({ status: :claimed, worker: worker_id }, returning: :_all)
+
+job = Job.instantiate(claimed.to_a.first) if claimed.length.positive?
+```
+
+Two workers running that at once cannot claim the same row: the `UPDATE` picks it, and only one wins.
+
+**Audit a bulk change**
+
+```ruby
+changed = Invoice.where(status: :draft).update_all_returning(
+  { status: :issued, issued_at: Time.current },
+  returning: %i[id number]
+)
+
+AuditLog.insert_all(changed.to_a.map { |row| { subject: "Invoice##{row["id"]}", action: "issued" } })
+```
+
+**Cancel and report in one pass**
+
+```ruby
+result = Subscription.where(trial_ends_at: ..Date.current)
+                     .update_all_returning({ state: "expired" }, returning: %i[id user_id plan])
+
+Rails.logger.info("expired #{result.length} trials: #{result.rows.inspect}")
+```
+
+**Get models back**
+
+```ruby
+users = User.where(role: :admin)
+            .update_all_returning({ role: :member }, returning: :_all)
+            .map { |attributes| User.instantiate(attributes) }
+
+users.first.email        # => "ada@example.com"
+users.first.new_record?  # => false
+```
+
+**Timestamps, if you want them** — like `update_all`, nothing is touched for you:
+
+```ruby
+User.where(role: :admin).update_all_returning(role: :member, updated_at: Time.current)
+```
+
+## `returning:`
+
+| Value | Clause |
+| --- | --- |
+| omitted / `nil` | the primary key (all of them, for a composite primary key) |
+| `:email` | `RETURNING "email"` |
+| `%i[id email]` | `RETURNING "id", "email"` |
+| `:_all` (bare or as `[:_all]`) | `RETURNING *` |
+| `Arel.sql("id, now() AS at")` | that SQL, verbatim |
+
+Rejected on purpose, each with a message saying what to do instead: a bare `String` (pass symbols, or wrap
+SQL in `Arel.sql`), an empty list, `returning: false` (use plain `update_all`), `:all` (use `:_all`), and
+`:_all` mixed with other columns (`RETURNING *` already includes them). A column literally named `all` or
+`_all` is reachable with `Arel.sql`.
+
+`updates` takes every shape `update_all` accepts:
+
+```ruby
+users.update_all_returning(role: :member)                     # Hash
+users.update_all_returning("role = 0")                        # String
+users.update_all_returning(["email = ?", "x@example.com"])    # Array
+users.update_all_returning(role: :member, returning: :email)  # braceless — returning: is pulled out
+```
+
+Hash values go through the attribute's type, so enums, booleans, JSON and `alias_attribute` cast exactly as
+`update_all` does.
+
+## The return value
+
+Always an `ActiveRecord::Result` — the same class `insert_all` returns, no wrapper, no subclass.
+
+```ruby
+result.columns  # => ["id", "email"]
+result.rows     # => [[1, "ada@example.com"], [2, "grace@example.com"]]
+result.to_a     # => [{"id" => 1, "email" => "ada@example.com"}, ...]
+result.length   # => 2
+result.each { |row| … }
+```
+
+Casting is the **adapter's**, not your model's: PostgreSQL types by OID and gives you a `Time` for a
+`timestamp`; SQLite hands back the raw String. For model types:
+
+```ruby
+result.cast_values(Session.attribute_types)   # => [[7, 1, 2026-08-14 09:00:00 UTC], ...]
+```
+
+## Database support
+
+| Database | Supported |
+| --- | --- |
+| PostgreSQL | yes |
+| SQLite 3.35+ | yes |
+| MySQL | no — raises `UnsupportedAdapter` |
+| MariaDB | no — raises `UnsupportedAdapter` |
+
+Read from `supports_update_returning?` where it exists, `supports_insert_returning?` otherwise. Two
+deliberate exceptions:
+
+- **MariaDB** answers `supports_insert_returning?` with `true` (it has `INSERT ... RETURNING` since 10.5)
+  while having no `UPDATE ... RETURNING` at all — so the MySQL family is excluded explicitly, and CI runs a
+  MariaDB lane to keep it that way.
+- **Rails 7.0's SQLite3 adapter** predates those capability methods, so the SQLite version is checked
+  directly.
+
+MySQL has no `RETURNING` on any statement. There is nothing to generate, so it raises rather than guessing:
+
+```ruby
+User.where(role: :admin).update_all_returning(role: :member)
+# ActiveRecord::Returning::UnsupportedAdapter:
+#   the Trilogy adapter does not support RETURNING on UPDATE/DELETE
+```
+
+On MySQL, do it in two statements with a lock, inside a transaction:
+
+```ruby
+User.transaction do
+  ids = User.where(role: :admin).lock.pluck(:id)
+  User.where(id: ids).update_all(role: :member)
+  User.where(id: ids)
+end
+```
+
+The gem won't do that for you: it's only correct inside a transaction with a lock, and hiding that behind a
+method that looks atomic hands a race to everyone who forgets.
+
+## How it works
+
+Your relation is reduced to a primary-key `SELECT` and used as a subquery:
+
+```sql
+UPDATE "users" SET "role" = 0, "lock_version" = COALESCE("lock_version", 0) + 1
+WHERE "users"."id" IN (
+  SELECT "users"."id" FROM "users" WHERE "users"."role" = 1 ORDER BY "users"."email" ASC LIMIT 2
+)
+RETURNING "id", "email"
+```
+
+Active Record builds that inner `SELECT`, so everything you already know keeps working:
+
+```ruby
+User.joins(:posts).where(posts: { published: true }).update_all_returning(role: :member)
+User.order(:created_at).limit(100).update_all_returning({ role: :member }, returning: :id)
+User.where(role: :admin).lock.update_all_returning(role: :member)   # FOR UPDATE in the subquery
+user.posts.update_all_returning({ published: true }, returning: :id)
+Memo.update_all_returning(title: "edited")                          # STI: this subclass only
+Note.where(shop_id: 1).delete_all_returning   # WHERE ("shop_id", "note_id") IN (SELECT ...)
+```
+
+Default scopes, `merge`, `none`, `distinct` and composite primary keys are covered too. No
+`Arel::UpdateManager`, no `_substitute_values`, no `build_arel` — nothing private, which is why one code
+path spans Rails 7.0 to 8.1.
+
+**Optimistic locking** works like `update_all`: the locking column is incremented unless you set it
+yourself.
+
+## Caveats
+
+**Callbacks, validations and timestamps are skipped**, exactly as with `update_all`/`delete_all`. Nothing
+is instantiated.
+
+**Isolation.** The subquery runs inside the same statement, so there is no separate read. But under `READ
+COMMITTED` (PostgreSQL's default) a row whose value changed after the statement's snapshot can still be
+picked up. Where that matters, lock explicitly or raise the isolation level.
+
+**Rejected relations**, each with a message pointing at the fix:
+
+| | why |
+| --- | --- |
+| `includes` that eager-loads | a join can't be reduced to a primary-key subquery — use `joins` |
+| `group` / `having` | the subquery would select an ungrouped column — use `where(id: grouped.select(:id))` |
+| `from` | it renames the table the subquery reads, so the primary key would resolve to the row being changed and every row would match — use `unscope(:from)` |
+| model without a primary key | nothing to match rows on |
+
+**`delete_all_returning` on a `has_many` deletes.** `user.posts.delete_all` nullifies `posts.user_id`
+unless the association declares `dependent: :delete_all`. `delete_all_returning` always issues a `DELETE`,
+because returning rows that still exist would be a lie. Renaming one call to the other on an association
+without `dependent: :delete_all` therefore removes rows where the old code only unset a foreign key.
+
+**`returning: :_all` on a joined relation** returns the updated table's columns only — `RETURNING *` refers
+to the updated row, not the join.
+
+**Performance.** The subquery is always there, even for a plain `where`, while `update_all` writes a direct
+`UPDATE ... WHERE` unless a join or limit forces otherwise. PostgreSQL usually turns it into a semi-join on
+the same index; on a large hot-path table, `EXPLAIN` first.
+
+## Active Record may grow its own
+
+[rails/rails#57073](https://github.com/rails/rails/pull/57073) proposes an `update_all_returning` upstream.
+Still open, and its API differs:
+
+| | rails/rails#57073 | this gem |
+| --- | --- | --- |
+| columns | `select(...)` on the relation | `returning:` keyword |
+| default | all columns | the primary key |
+
+So the gemspec caps Active Record at `< 8.2`, and if `ActiveRecord::Relation` already defines either
+method, the gem leaves that one alone and warns at boot instead of silently doing nothing.
+
+Compared to `insert_all`/`upsert_all`, which already have `returning:`: same return type, same default.
+
+The difference that matters is not the keyword — **`upsert_all` creates rows, these methods never do.**
+It takes a list of attributes rather than a scope, so it cannot express `where(...)`, and any key that
+isn't in the table yet becomes a new row:
+
+```ruby
+User.upsert_all([{ id: 999, email: "ghost@example.com" }], returning: %i[id email])
+# => #<ActiveRecord::Result [[999, "ghost@example.com"]]>   looks like a row you changed
+User.count # => 4                                           it was inserted
+```
+
+A stale id, a typo, a half-built payload — inserted, and handed back as though it had been updated.
+`update_all_returning` can only touch rows the relation already matched.
+
+Smaller differences: `:_all` is an addition here, `returning: false` raises instead of returning an empty
+Result, and MySQL raises instead of quietly returning an empty Result.
+
+## Why methods, not a chainable `.returning`
+
+`User.returning(:id).where(...).update_all(...)` was considered and rejected:
+
+1. `update_all` would return an Integer *or* a Result depending on state set somewhere else. The call site
+   stops being readable.
+2. It needs `prepend` over `update_all`. Removing the gem would then silently change working code instead
+   of raising `NoMethodError` at the one place that used it.
+3. Rails put `returning:` on `insert_all`/`upsert_all` as a keyword, not a query method.
+
+The trade-off: you can't bake it into a scope. That's the intended cost.
+
+## Errors
+
+| Error | When |
+| --- | --- |
+| `ActiveRecord::Returning::UnsupportedAdapter` | MySQL, MariaDB, SQLite < 3.35 |
+| `ActiveRecord::Returning::Error` | eager loading, `group`/`having`, `from`, no primary key |
+| `ArgumentError` | empty updates, bare String / empty list / `false` in `returning:` |
+
+`UnsupportedAdapter < Error < StandardError`.
+
+## Requirements
+
+Ruby 3.1+ · Active Record 7.0–8.1 · PostgreSQL or SQLite 3.35+
+
+CI covers Ruby 3.1–3.4 × Rails 7.0, 7.1, 7.2, 8.0, 8.1 on SQLite, PostgreSQL on every one of those Rails
+versions, and MySQL 8 and MariaDB 11 for the unsupported-adapter path.
+
+## Development
+
+```bash
+bin/setup                 # create the dev database, load the schema, seed it
+bin/console               # IRB with User, Post, Session, Note (composite PK), Memo (STI)
+bundle exec rake test
+```
+
+All three take `DB=sqlite` (default), `DB=postgres`, `DB=mysql` or `DB=mariadb`; databases are created for
+you, connections come from `PGHOST`/`PGUSER`/`PGPASSWORD` and `MYSQL_HOST`/`MYSQL_PORT`/`MYSQL_USER`/
+`MYSQL_PASSWORD`.
+
+```bash
+bundle exec appraisal install && bundle exec appraisal rake test   # every supported Rails
+python3 docs/render_demo.py                                        # re-render the demo GIF
+```
+
+### Releasing
+
+```bash
+# bump lib/activerecord/returning/version.rb, move CHANGELOG entries under the new version
+bundle exec rake release
+```
+
+## Contributing
+
+Bug reports and pull requests: https://github.com/igorkasyanchuk/activerecord-returning
+
+## License
+
+MIT. Copyright (c) 2026 Igor Kasyanchuk.

data/lib/activerecord/returning/errors.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module Returning
+    # Base class for every error this gem raises.
+    class Error < StandardError; end
+
+    # Raised when the connection's adapter cannot run a RETURNING clause
+    # (MySQL, or SQLite older than 3.35).
+    class UnsupportedAdapter < Error; end
+  end
+end

data/lib/activerecord/returning/querying.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# delegate is an Active Support core extension, and this file is loaded before
+# Active Record boots.
+require "active_support/core_ext/module/delegation"
+
+module ActiveRecord
+  module Returning
+    # Extended into ActiveRecord::Base, so the methods can be called on the model
+    # itself and not only on a relation — the same delegation Rails uses to put
+    # update_all and delete_all on the class.
+    #
+    #   User.update_all_returning(role: :member)
+    module Querying
+      delegate :update_all_returning, :delete_all_returning, to: :all
+    end
+  end
+end

data/lib/activerecord/returning/relation_methods.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module Returning
+    # Mixed into ActiveRecord::Relation. Deliberately holds nothing but the two
+    # public methods: every helper lives on Statement so this module can never
+    # collide with Active Record's own internals.
+    module RelationMethods
+      # Runs an UPDATE over the current scope and returns the changed rows.
+      #
+      #   User.where(role: :admin).update_all_returning({ role: :user }, returning: %i[id email])
+      #   # => #<ActiveRecord::Result @columns=["id", "email"], @rows=[[1, "ada@example.com"]]>
+      #
+      # +updates+ takes the same shapes as #update_all (Hash, String, Array). A
+      # braceless hash works too, so `update_all_returning(role: :user, returning: :id)`
+      # is the same call. +returning+ defaults to the primary key.
+      def update_all_returning(updates = nil, returning: nil, **rest)
+        if updates && rest.any?
+          raise ArgumentError, "unknown keywords: #{rest.keys.map(&:inspect).join(", ")}"
+        end
+
+        Statement.new(self, returning: returning).update(updates || rest)
+      end
+
+      # Runs a DELETE over the current scope and returns the deleted rows.
+      #
+      #   Session.where(expires_at: ..1.week.ago).delete_all_returning(returning: %i[id user_id])
+      def delete_all_returning(returning: nil)
+        Statement.new(self, returning: returning).delete
+      end
+    end
+  end
+end

data/lib/activerecord/returning/statement.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module Returning
+    # Builds and runs the UPDATE/DELETE ... RETURNING statement for a relation.
+    #
+    # The relation itself is never rebuilt into Arel by hand. It is reduced to a
+    # primary-key SELECT and used as a subquery:
+    #
+    #   UPDATE "users" SET "role" = 'user'
+    #   WHERE "users"."id" IN (SELECT "users"."id" FROM "users" WHERE "users"."role" = 'admin')
+    #   RETURNING "id", "email"
+    #
+    # so default scopes, joins, limit, order, merge, none and composite primary
+    # keys all keep working because Active Record builds that SELECT.
+    class Statement
+      def initialize(relation, returning: nil)
+        @relation = relation
+        @klass = relation.klass
+        @returning = returning
+      end
+
+      def update(updates)
+        raise ArgumentError, "Empty list of attributes to change" if updates.blank?
+
+        run("Update All Returning") do |conn|
+          "UPDATE #{quoted_table_name(conn)} SET #{set_clause(conn, updates)} " \
+            "WHERE #{where_clause(conn)} RETURNING #{returning_clause(conn)}"
+        end
+      end
+
+      def delete
+        run("Delete All Returning") do |conn|
+          "DELETE FROM #{quoted_table_name(conn)} " \
+            "WHERE #{where_clause(conn)} RETURNING #{returning_clause(conn)}"
+        end
+      end
+
+      private
+        attr_reader :relation, :klass, :returning
+
+        def run(name)
+          with_connection do |conn|
+            validate!(conn)
+            result = conn.exec_query(yield(conn), name)
+
+            clear_query_caches(conn)
+            relation.reset # loaded records are stale now
+            result
+          end
+        end
+
+        # exec_query only dirties the query cache from Rails 7.1 on, and a cached
+        # SELECT of a row we just changed is stale.
+        #
+        # Both clears are deliberate. The thread-wide one is what update_all uses,
+        # and is the one that matters for a primary/replica setup, where the stale
+        # entry can sit in another pool. It is also a no-op on Rails 7.0 with the
+        # default legacy_connection_handling, where it walks connection_handlers
+        # and misses the handler actually in use — Rails 7.0's own update_all
+        # leaves the cache stale for the same reason. So the connection we wrote
+        # through is cleared directly as well.
+        def clear_query_caches(conn)
+          ActiveRecord::Base.clear_query_caches_for_current_thread if
+            ActiveRecord::Base.respond_to?(:clear_query_caches_for_current_thread)
+
+          conn.clear_query_cache
+        end
+
+        # Rails 7.2 deprecated holding on to a connection via klass.connection.
+        def with_connection(&block)
+          if klass.respond_to?(:with_connection)
+            klass.with_connection(&block)
+          else
+            block.call(klass.connection)
+          end
+        end
+
+        def validate!(conn)
+          unless Returning.supported?(conn)
+            raise UnsupportedAdapter,
+              "the #{conn.adapter_name} adapter does not support RETURNING on UPDATE/DELETE"
+          end
+
+          if relation.eager_loading?
+            raise Error,
+              "#{self.class.name} cannot be used with eager loading, because an `includes` that " \
+              "becomes a join cannot be reduced to a primary key subquery. Use `.joins` instead, " \
+              "or `.unscope(:includes)`."
+          end
+
+          raise Error, "#{klass.name} has no primary key, so there is nothing to match rows on" if primary_keys.empty?
+
+          unless relation.from_clause.empty?
+            raise Error,
+              "#{self.class.name} cannot be used with `from`, because the primary key subquery selects " \
+              "#{primary_keys.map { |name| "#{klass.table_name}.#{name}" }.join(", ")} while `from` renames " \
+              "the table it reads. " \
+              "The database then reads that as a reference to the row being changed and matches every " \
+              "row in the table. Use `.unscope(:from)`."
+          end
+
+          if relation.group_values.any? || !relation.having_clause.empty?
+            raise Error,
+              "#{self.class.name} cannot be used with group or having: the primary key subquery would " \
+              "select a column that is not grouped. Reduce the relation to plain conditions first, for " \
+              "example with `where(id: grouped_relation.select(:id))`."
+          end
+        end
+
+        def set_clause(conn, updates)
+          set = klass.sanitize_sql_for_assignment(resolve_aliases(updates))
+          set += ", #{increment_lock_version(conn)}" if increment_lock_version?(updates)
+          set
+        end
+
+        # alias_attribute names are not columns, so they have to be resolved
+        # before the SET clause is built. update_all does the same.
+        def resolve_aliases(updates)
+          return updates unless updates.is_a?(Hash) && klass.attribute_aliases.any?
+
+          updates.transform_keys { |key| klass.attribute_aliases[key.to_s] || key }
+        end
+
+        # Matches update_all: bump the lock column unless the caller set it.
+        def increment_lock_version?(updates)
+          return false unless klass.locking_enabled?
+          return false unless updates.is_a?(Hash)
+
+          updates = resolve_aliases(updates)
+
+          column = klass.locking_column
+          !updates.key?(column) && !updates.key?(column.to_sym)
+        end
+
+        def increment_lock_version(conn)
+          column = conn.quote_column_name(klass.locking_column)
+          "#{column} = COALESCE(#{column}, 0) + 1"
+        end
+
+        def where_clause(conn)
+          columns = primary_keys.map { |name| "#{quoted_table_name(conn)}.#{conn.quote_column_name(name)}" }
+          left = columns.one? ? columns.first : "(#{columns.join(", ")})"
+
+          "#{left} IN (#{subquery_sql})"
+        end
+
+        # Arel attributes, not bare symbols, so the primary key stays
+        # table-qualified and cannot go ambiguous under a join.
+        def subquery_sql
+          attributes = primary_keys.map { |name| klass.arel_table[name] }
+          relation.unscope(:select).select(*attributes).to_sql
+        end
+
+        def returning_clause(conn)
+          return primary_keys.map { |name| conn.quote_column_name(name) }.join(", ") if returning.nil?
+
+          # Normalized once, so every special value is checked in one place,
+          # bare or listed. The sentinel checks compare symbols, and they must
+          # run before the column path: on SQLite an unknown double-quoted
+          # identifier does not error, it falls back to a string literal —
+          # silent wrong data instead of an exception.
+          columns = Array(returning)
+          raise ArgumentError, "returning: is empty, so there is nothing to return" if columns.empty?
+
+          if columns.include?(false)
+            raise ArgumentError,
+              "returning: false is not supported, because these methods always return rows. " \
+              "Use update_all/delete_all if you only want the count."
+          end
+
+          if columns.include?(:all)
+            raise ArgumentError,
+              ":all was renamed to :_all, and RETURNING * cannot be combined with other columns — " \
+              "use returning: :_all alone. For a column literally named \"all\", use Arel.sql('\"all\"')."
+          end
+
+          # ponytail: a column literally named _all is shadowed by the sentinel; Arel.sql is the escape.
+          if columns.include?(:_all)
+            return "*" if columns.uniq == [:_all]
+
+            raise ArgumentError,
+              "returning: :_all stands for RETURNING * and cannot be combined with other columns. " \
+              "Use returning: :_all alone, or list every column. For a column literally named " \
+              "\"_all\", use Arel.sql('\"_all\"')."
+          end
+
+          columns.map { |column| returning_column(conn, column) }.join(", ")
+        end
+
+        def returning_column(conn, column)
+          # SqlLiteral is a String subclass, so it has to be checked first.
+          case column
+          when Arel::Nodes::SqlLiteral then column.to_s
+          when Symbol then returning_attribute(conn, column)
+          when String
+            raise ArgumentError,
+              "returning: does not take raw String #{column.inspect}. Pass column names as symbols " \
+              "(returning: :id, returning: %i[id email]) or wrap SQL in Arel.sql."
+          else
+            raise ArgumentError, "unsupported returning: value #{column.inspect}"
+          end
+        end
+
+        # An alias_attribute is not a column, so it has to be resolved — and then
+        # aliased back, so the caller reads the result under the name they asked
+        # for: RETURNING "title" AS "headline".
+        def returning_attribute(conn, name)
+          column = klass.attribute_aliases[name.to_s]
+          return conn.quote_column_name(name) if column.nil?
+
+          "#{conn.quote_column_name(column)} AS #{conn.quote_column_name(name)}"
+        end
+
+        def primary_keys
+          @primary_keys ||= Array(klass.primary_key)
+        end
+
+        def quoted_table_name(conn)
+          conn.quote_table_name(klass.table_name)
+        end
+    end
+  end
+end

data/lib/activerecord/returning/version.rb

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

data/lib/activerecord/returning.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "active_support/lazy_load_hooks"
+
+require_relative "returning/version"
+require_relative "returning/errors"
+require_relative "returning/relation_methods"
+require_relative "returning/querying"
+
+module ActiveRecord
+  # UPDATE ... RETURNING and DELETE ... RETURNING for ActiveRecord::Relation.
+  module Returning
+    # Can this connection run UPDATE/DELETE ... RETURNING?
+    #
+    # supports_update_returning? is the precise question, but it only exists on
+    # newer Rails. supports_insert_returning? is the closest stand-in, with one
+    # trap: MariaDB answers true to it (it has INSERT ... RETURNING since 10.5)
+    # while having no UPDATE ... RETURNING at all, so the MySQL family is ruled
+    # out explicitly.
+    #
+    # The SQLite branch is for Rails 7.0, whose SQLite3 adapter predates the
+    # capability methods even though the database itself supports RETURNING.
+    # Version compares itself to a version string by parts; a plain string
+    # compare would read "3.4.0" as newer than "3.35.0".
+    def self.supported?(connection)
+      return connection.supports_update_returning? if connection.respond_to?(:supports_update_returning?)
+
+      adapter = connection.adapter_name.to_s
+      return false if adapter.match?(/mysql|trilogy|mariadb/i)
+      return true if connection.supports_insert_returning?
+
+      adapter.match?(/sqlite/i) && connection.database_version >= "3.35.0"
+    end
+  end
+end
+
+# Loading this gem must not boot Active Record.
+ActiveSupport.on_load(:active_record) do
+  require_relative "returning/statement"
+
+  # Active Record may grow its own update_all_returning one day (rails/rails#57073
+  # proposes one with a different API: columns via select(), defaulting to all of
+  # them). An include cannot override a method defined on Relation itself, so
+  # rather than silently doing nothing, say so.
+  taken = %i[update_all_returning delete_all_returning].select do |name|
+    ActiveRecord::Relation.method_defined?(name)
+  end
+
+  if taken.any?
+    warn "[activerecord-returning] ActiveRecord::Relation already defines #{taken.join(" and ")}. " \
+         "Leaving #{taken.one? ? "that one" : "them"} alone. Note that Active Record's own version " \
+         "selects columns with select(), not with returning:."
+  end
+
+  # Add only the names Active Record has not taken, so one upstream method does
+  # not silently remove the other.
+  without_taken = lambda do |mixin|
+    next mixin if taken.empty?
+
+    mixin.dup.tap { |copy| taken.each { |name| copy.send(:remove_method, name) } }
+  end
+
+  ActiveRecord::Relation.include(without_taken.call(ActiveRecord::Returning::RelationMethods))
+  ActiveRecord::Base.extend(without_taken.call(ActiveRecord::Returning::Querying))
+end

data/lib/activerecord-returning.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "activerecord/returning"

metadata

@@ -0,0 +1,76 @@
+--- !ruby/object:Gem::Specification
+name: activerecord-returning
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Igor Kasyanchuk
+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: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.2'
+description: Adds update_all_returning and delete_all_returning to ActiveRecord::Relation,
+  so you get the changed rows back instead of a row count. PostgreSQL and SQLite 3.35+.
+email:
+- igorkasyanchuk@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/activerecord-returning.rb
+- lib/activerecord/returning.rb
+- lib/activerecord/returning/errors.rb
+- lib/activerecord/returning/querying.rb
+- lib/activerecord/returning/relation_methods.rb
+- lib/activerecord/returning/statement.rb
+- lib/activerecord/returning/version.rb
+homepage: https://github.com/igorkasyanchuk/activerecord-returning
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/igorkasyanchuk/activerecord-returning
+  changelog_uri: https://github.com/igorkasyanchuk/activerecord-returning/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/igorkasyanchuk/activerecord-returning/issues
+  documentation_uri: https://github.com/igorkasyanchuk/activerecord-returning/blob/main/README.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.2
+specification_version: 4
+summary: UPDATE ... RETURNING and DELETE ... RETURNING for ActiveRecord::Relation
+test_files: []