pg_sql_caller 1.0.0 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b4ea6fd0cd19dd9e2d12d963b0c7689cef8346a63f0981e3a96821faebf4f6bc
-  data.tar.gz: f2d40a1f3790e084ebdb9e0bf5908241494aaacca55ca8604f18cf05a6dbb8d8
+  metadata.gz: dcc72483e5ca6259c0d54d32100d69dc0b95d280a1980326508ef0a925d610fb
+  data.tar.gz: 2d59c43a923c2ca41040b5c427a1dead6d025329a9eb67df20ede963b187f55b
 SHA512:
-  metadata.gz: 908fcb421cdf254ba4a91cc8c67c304938cfd65ef7a25393ae3019b02e0b84ea634c2fa250fba333e88bd287be02480aafce0cd8f0780e083d3b38800de9ab90
-  data.tar.gz: 927f8dc22e285bdf849e85bb850e5e2045429675ccb953b872150b0954ecf95602d6a6c84b52829e9b9af8b29fe8acc016d41be10628ae2181edd29c1df7d9a7
+  metadata.gz: 5d416d3882391975f85c6145fcac4e05a7a09d97dbbfb4c14f232121c1e4e63054efea8e7901ebc8093ed3c5388bc0791236f494b187ce3cf08e8838081828ee
+  data.tar.gz: a7280cd40f97b54f51f3c9deb241dc41d1448850e0f7df092b2c6da54ce0c8bfe4d2bdcf4835d91253ff9ea0aff0564ad9da80d05b0c2faf325633f3211b2eab

data/CHANGELOG.md

@@ -5,7 +5,27 @@ 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.1] - 2026-06-22
+
+### Fixed
+
+- `PgSqlCaller::BulkUpdate` no longer truncates `datetime`/`time` values to whole seconds.
+  PostgreSQL's default timestamp array encoder formats elements via Ruby's `Time#to_s`,
+  dropping sub-seconds — which silently corrupted sub-second writes and, worse, broke any
+  `unique_by` match on a sub-second timestamp key (the truncated bind never equalled the
+  stored value, so the row was missed and the update became a silent no-op). Temporal
+  columns are now encoded at full microsecond precision.
+
+## [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 +104,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.
@@ -170,8 +216,55 @@ module PgSqlCaller
     def bindings
       columns.map do |col|
         values = attrs_list.map { |attrs| attrs[col] }
-        sql_caller.typecast_array(values, type: model_class.type_for_attribute(col.to_s).type)
+        encode_column_array(col, values)
+      end
+    end
+
+    # Encode one column's values as a PostgreSQL array literal for its `?::<sql_type>[]`
+    # placeholder. Temporal columns are encoded at full microsecond precision: PostgreSQL's
+    # default timestamp/time array encoder formats elements via Ruby's `Time#to_s`, which
+    # truncates to whole seconds — silently corrupting writes and, worse, breaking any
+    # `unique_by` match on a sub-second key (the truncated bind never equals the stored
+    # sub-second value, so the row is missed). Non-temporal columns use the standard
+    # typed-array encoder unchanged.
+    #
+    # @param col [Symbol] the column name
+    # @param values [Array] the per-row values for that column
+    # @return [String] a PostgreSQL array literal
+    def encode_column_array(col, values)
+      ar_type = model_class.type_for_attribute(col.to_s)
+      case ar_type.type
+      when :datetime then format_date_time_array(ar_type, values, include_date: true)
+      when :time     then format_date_time_array(ar_type, values, include_date: false)
+      else sql_caller.typecast_array(values, type: ar_type.type)
+      end
+    end
+
+    # Build a `{...}` array literal of microsecond-precision temporal literals, reparsed to
+    # the column's real type by the surrounding `?::<sql_type>[]` cast with no precision
+    # loss. When `include_date` is set (`datetime` columns) the value is normalized to UTC and
+    # suffixed `+00:00` — correct for both `timestamp` (the offset is ignored) and `timestamptz`
+    # (the offset is honored); otherwise (`time` columns) only the wall-clock time of day is
+    # emitted, with no date or zone. Each element is built from a value already cast to a Time
+    # and then `strftime`'d into a fixed numeric format, so the literal can hold only
+    # `[-0-9:. +]` and needs no escaping. `nil` becomes SQL `NULL`.
+    #
+    # @param ar_type [ActiveRecord::Type::Value] the column's cast type, used to coerce each
+    #   value to a Time
+    # @param values [Array] the per-row values for that column
+    # @param include_date [Boolean] true for `datetime` (date + time, normalized to UTC),
+    #   false for `time` (time of day only)
+    # @return [String] a PostgreSQL array literal
+    def format_date_time_array(ar_type, values, include_date:)
+      elements = values.map do |value|
+        time = ar_type.cast(value)
+        next 'NULL' if time.nil?
+
+        time = time.utc if include_date
+        formatted = include_date ? time.strftime('%Y-%m-%d %H:%M:%S.%6N%:z') : time.strftime('%H:%M:%S.%6N')
+        %("#{formatted}")
       end
+      "{#{elements.join(',')}}"
     end
 
     # The PostgreSQL type of a column, used to build its array cast.

data/lib/pg_sql_caller/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PgSqlCaller
-  VERSION = '1.0.0'
+  VERSION = '1.1.1'
 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.1
 platform: ruby
 authors:
 - Denis Talakevich