pg_sql_caller 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b4ea6fd0cd19dd9e2d12d963b0c7689cef8346a63f0981e3a96821faebf4f6bc
-  data.tar.gz: f2d40a1f3790e084ebdb9e0bf5908241494aaacca55ca8604f18cf05a6dbb8d8
+  metadata.gz: 97ef871de183917ba98a3c35bdeb4a184c5aa39ab7b1e6cdc89b11ccb60e8874
+  data.tar.gz: d18b3aaada2a2a432e892f067233d6d22a45f2bd39045b1015d6b9fb34c6c154
 SHA512:
-  metadata.gz: 908fcb421cdf254ba4a91cc8c67c304938cfd65ef7a25393ae3019b02e0b84ea634c2fa250fba333e88bd287be02480aafce0cd8f0780e083d3b38800de9ab90
-  data.tar.gz: 927f8dc22e285bdf849e85bb850e5e2045429675ccb953b872150b0954ecf95602d6a6c84b52829e9b9af8b29fe8acc016d41be10628ae2181edd29c1df7d9a7
+  metadata.gz: 75e47d26186bec99d485e7661343f8096386bea04f380385df624e53ba50e0859e89fec3d6de621efe077710a8919dfe28bcd6000c7b45695588132deddd5f36
+  data.tar.gz: 5863e6f4406d10316fbfe76f4ee7504ff79e3175786e702315b39ceef2d78ade4249fdd370cbfc0b39210ba339927e04e9ac8d58e8748b86c5619cd808b819ce

data/CHANGELOG.md

@@ -5,7 +5,16 @@ All notable changes to this project will be documented in this file.
 The format is based on [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]
+## [1.1.0] - 2026-06-18
+
+### Added
+
+- `PgSqlCaller::BulkUpdate` now accepts an optional `returning:` keyword — pass one or more
+  column names to read them back from each updated row via SQL `RETURNING`. The result is one
+  `Symbol`-keyed, type-cast hash per updated row (`[]` when `attrs_list` is empty). Omitting
+  `returning:` keeps the existing behavior of returning the affected-row count.
+
+## [1.0.0] - 2026-06-08
 
 ### Added
 
@@ -84,7 +93,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   `transaction_open?`, `explain_analyze`, `typecast_array`, `sanitize_sql_array`, and
   `current_database_name`.
 
-[Unreleased]: https://github.com/didww/pg_sql_caller/compare/v0.2.3...HEAD
+[1.1.0]: https://github.com/didww/pg_sql_caller/compare/v1.0.0...v1.1.0
+[1.0.0]: https://github.com/didww/pg_sql_caller/compare/v0.2.3...v1.0.0
 [0.2.3]: https://github.com/didww/pg_sql_caller/compare/v0.2.2...v0.2.3
 [0.2.2]: https://github.com/didww/pg_sql_caller/compare/v0.2.1...v0.2.2
 [0.2.1]: https://github.com/didww/pg_sql_caller/compare/v0.2.0...v0.2.1

data/README.md

@@ -328,13 +328,27 @@ PgSqlCaller::BulkUpdate.call(Employee, attrs_list, unique_by: :employee_number)
 PgSqlCaller::BulkUpdate.call(Employee, attrs_list, unique_by: %i[department_id name])
 ```
 
+### Reading back updated rows
+
+Pass `returning` to read columns back from each updated row (SQL `RETURNING`) instead of a row count. The result is one `Symbol`-keyed hash per updated row, with values cast to their Ruby types (the same casting as [`select_all_serialized`](#serialized-reads-ruby-type-casting)):
+
+```ruby
+PgSqlCaller::BulkUpdate.call(Employee, [
+  { id: 1, name: 'John', department_id: 10 },
+  { id: 2, name: 'Jane', department_id: 20 }
+], returning: %i[id name])
+# => [{ id: 1, name: 'John' }, { id: 2, name: 'Jane' }]
+```
+
+A single column may be passed as a `Symbol` (`returning: :id`). Without `returning` (the default) the call returns the affected-row **count** exactly as before — the behavior is unchanged.
+
 ### Rules and behavior
 
 - **Every row must include each `unique_by` column**, and all hashes must share the same set of keys.
 - Only the columns you list are written; `unique_by` columns are used for matching, the rest are updated. Columns you omit (e.g. `created_at`) are left untouched.
 - Rows that don't match an existing row are simply not updated — this **never inserts**.
-- Returns the number of rows affected (`0` when `attrs_list` is empty — a no-op).
-- Raises `ArgumentError` (before touching the database) if a row omits a `unique_by` column or names a column that doesn't exist on the model.
+- Returns the number of rows affected (`0` when `attrs_list` is empty — a no-op). With `returning`, it instead returns the updated rows as `Symbol`-keyed hashes (`[]` when `attrs_list` is empty).
+- Raises `ArgumentError` (before touching the database) if a row omits a `unique_by` column, names a column that doesn't exist on the model, or `returning` is empty or names an unknown column.
 
 ### Why not `upsert_all` or a loop of `update_all`?
 

data/lib/pg_sql_caller/bulk_update.rb

@@ -42,37 +42,71 @@ module PgSqlCaller
     #   `unique_by` column, and all hashes MUST share the same keys
     # @param unique_by [Symbol, Array<Symbol>] the match column(s) — a single column,
     #   or all parts of a composite key (default +:id+)
-    # @return [Integer] the number of rows affected
-    def self.call(model_class, attrs_list, unique_by: :id)
-      new(model_class, attrs_list, unique_by: unique_by).call
+    # @param returning [Symbol, Array<Symbol>, nil] column(s) to read back from each
+    #   updated row via SQL `RETURNING`; +nil+ (default) keeps the row-count behavior
+    # @return [Integer, Array<Hash{Symbol => Object}>] the number of rows affected, or —
+    #   when +returning+ is given — the updated rows as type-cast, Symbol-keyed hashes
+    def self.call(model_class, attrs_list, unique_by: :id, returning: nil)
+      new(model_class, attrs_list, unique_by: unique_by, returning: returning).call
     end
 
-    attr_reader :model_class, :unique_by, :attrs_list
+    attr_reader :model_class, :unique_by, :attrs_list, :returning
 
     # @param model_class [Class<ActiveRecord::Base>] the model whose table is updated
     # @param attrs_list [Array<Hash>] one hash per row; each MUST include every
     #   `unique_by` column, and all hashes MUST share the same keys
     # @param unique_by [Symbol, Array<Symbol>] the match column(s) — a single column,
     #   or all parts of a composite key (default +:id+)
-    def initialize(model_class, attrs_list, unique_by: :id)
+    # @param returning [Symbol, Array<Symbol>, nil] column(s) to read back from each
+    #   updated row via SQL `RETURNING`; +nil+ (default) keeps the row-count behavior
+    def initialize(model_class, attrs_list, unique_by: :id, returning: nil)
       @model_class = model_class
       @attrs_list = attrs_list
       @unique_by = Array(unique_by)
+      @returning = returning.nil? ? nil : Array(returning)
     end
 
     # Execute the bulk update as a single `UPDATE ... FROM unnest(...)` statement.
     #
-    # @return [Integer] the number of rows affected (0 when +attrs_list+ is empty)
-    # @raise [ArgumentError] if a row omits a `unique_by` column, or names a column
-    #   that does not exist on the model
+    # @return [Integer, Array<Hash{Symbol => Object}>] without +returning+, the number of
+    #   rows affected (0 when +attrs_list+ is empty); with +returning+, the updated rows as
+    #   type-cast, Symbol-keyed hashes (+[]+ when +attrs_list+ is empty)
+    # @raise [ArgumentError] if a row omits a `unique_by` column, names a column that does
+    #   not exist on the model, or +returning+ is empty or names an unknown column
     def call
-      return 0 if attrs_list.empty?
+      validate_returning! unless returning.nil?
+      return empty_result if attrs_list.empty?
 
-      sql_caller.execute(sql, *bindings).cmd_tuples
+      if returning.nil?
+        sql_caller.execute(sql, *bindings).cmd_tuples
+      else
+        sql_caller.select_all_serialized(sql, *bindings)
+      end
     end
 
     private
 
+    # The value returned for an empty +attrs_list+: a zero row count, or an empty row set
+    # when +returning+ was requested — mirroring the shape {#call} returns when it runs.
+    #
+    # @return [Integer, Array]
+    def empty_result
+      returning.nil? ? 0 : []
+    end
+
+    # Validate the requested `RETURNING` columns before any SQL runs: at least one column
+    # must be named, and every column must exist on the model (each is qualified with the
+    # target alias `t`, so it must be a real column, never an expression).
+    #
+    # @return [void]
+    # @raise [ArgumentError] if +returning+ is empty or names a column unknown to the model
+    def validate_returning!
+      raise ArgumentError, 'returning must name at least one column' if returning.empty?
+
+      unknown = returning.map(&:to_s) - model_class.column_names
+      raise ArgumentError, "unknown #{model_class} returning columns: #{unknown.join(', ')}" if unknown.any?
+    end
+
     # The SQL executor, built from the model's own connection: it sanitizes the bound
     # values, runs the statement and encodes the typed PostgreSQL arrays.
     #
@@ -123,16 +157,28 @@ module PgSqlCaller
     end
 
     # The full `UPDATE ... FROM unnest(...)` statement, with one `?` placeholder per
-    # column for the value arrays.
+    # column for the value arrays, plus a `RETURNING` clause when +returning+ was given.
     #
     # @return [String]
     def sql
-      <<~SQL.squish
+      statement = <<~SQL.squish
         UPDATE #{model_class.quoted_table_name} AS t
         SET #{set_clause}
         FROM unnest(#{unnest_args}) AS v(#{column_aliases})
         WHERE #{match_clause}
       SQL
+      return statement if returning.nil?
+
+      "#{statement} RETURNING #{returning_clause}"
+    end
+
+    # The `RETURNING t.col, ...` projection. Each column is qualified with the target
+    # alias `t` because the `unnest` source alias `v` shares the same column names, so an
+    # unqualified `RETURNING` would be ambiguous.
+    #
+    # @return [String]
+    def returning_clause
+      returning.map { |col| "t.#{quoted(col)}" }.join(', ')
     end
 
     # The `SET col = v.col, ...` assignments for the value columns.

data/lib/pg_sql_caller/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PgSqlCaller
-  VERSION = '1.0.0'
+  VERSION = '1.1.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pg_sql_caller
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Denis Talakevich