pg_sql_caller 1.1.1 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dcc72483e5ca6259c0d54d32100d69dc0b95d280a1980326508ef0a925d610fb
-  data.tar.gz: 2d59c43a923c2ca41040b5c427a1dead6d025329a9eb67df20ede963b187f55b
+  metadata.gz: adaedfadf46e6d79df0bdee58f8264ce6a5414a271898ddc1a7104751f1cdcca
+  data.tar.gz: 26a3c8bfb922d08eea5570a0d05dc0bc4c639c06546ae1c34ea7aac8b9f0e2a5
 SHA512:
-  metadata.gz: 5d416d3882391975f85c6145fcac4e05a7a09d97dbbfb4c14f232121c1e4e63054efea8e7901ebc8093ed3c5388bc0791236f494b187ce3cf08e8838081828ee
-  data.tar.gz: a7280cd40f97b54f51f3c9deb241dc41d1448850e0f7df092b2c6da54ce0c8bfe4d2bdcf4835d91253ff9ea0aff0564ad9da80d05b0c2faf325633f3211b2eab
+  metadata.gz: 70dc60fc4336c0bc8bda7b1c68b1c4de2b7964ab57e98a79831e0a3a9d05b90f5acef160792d4b9ba4c0a4da2e702708be21bfc6fe66f46aebada7eff62ed365
+  data.tar.gz: 0e51a8dd6bf7db096566d1b86784a8134baed55ee1ffa59dd9681af645b427b533455dea9baffd1eac1f8dd03974f62fe1a2f39511c35c8b3e7de4930b1d056c

data/CHANGELOG.md

@@ -5,6 +5,30 @@ 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.2.0] - 2026-07-23
+
+### Added
+
+- `PgSqlCaller::BulkUpdate` now accepts an optional `condition:` keyword — a raw-SQL predicate
+  ANDed onto the key match, so only rows that also satisfy it are updated (e.g. apply a payload
+  only while the row is still in the state you read it in).
+- `PgSqlCaller::BulkUpdate` now accepts an optional `set_override:` keyword — a hash of
+  column ⇒ raw-SQL expression replacing that column's default `col = v.col` assignment (e.g.
+  `CASE WHEN t."status" = 'pending' THEN v."status" ELSE t."status" END`). A key absent from
+  `attrs_list` contributes an assignment of its own, so a column can be written purely from SQL.
+  Both fragments are interpolated verbatim and must not be built from untrusted input; column
+  references in them must be qualified with `t.` or `v.`.
+- `PgSqlCaller::BulkUpdate#sql` is now public, returning the exact statement `#call` runs. It
+  runs the same validations, so any input `#call` rejects raises the same `ArgumentError` rather
+  than yielding an invalid statement; an empty `attrs_list`, for which `#call` runs no statement
+  at all, raises too.
+- `PgSqlCaller::BulkUpdate` now accepts `unique_by:` as String(s) as well as Symbol(s). They were
+  previously matched against the payload's Symbol keys as-is, so a String silently failed to
+  exclude its column from the `SET` clause and escaped the `set_override` guard against
+  rewriting a match column.
+
 ## [1.1.1] - 2026-06-22
 
 ### Fixed
@@ -104,6 +128,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`.
 
+[1.2.0]: https://github.com/didww/pg_sql_caller/compare/v1.1.1...v1.2.0
+[1.1.1]: https://github.com/didww/pg_sql_caller/compare/v1.1.0...v1.1.1
 [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

data/README.md

@@ -342,13 +342,51 @@ PgSqlCaller::BulkUpdate.call(Employee, [
 
 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.
 
+### Updating only rows in an expected state
+
+Pass `condition` — a raw-SQL predicate ANDed onto the key match — to skip rows whose current state isn't what you expect. Typical use: apply the payload only while the row is still in the state you read it in.
+
+```ruby
+# Move to 'processing', but only rows still 'pending' in the database.
+PgSqlCaller::BulkUpdate.call(Order, [
+  { id: 1, status: 'processing' },
+  { id: 2, status: 'processing' }
+], condition: %q{t."status" = 'pending'})
+# => 1   (only one of the two was still pending)
+```
+
+Non-matching rows are simply not updated — with `returning`, they are absent from the result, so the return value tells you exactly which rows the condition let through.
+
+### Overriding how a column is assigned
+
+Pass `set_override` — a hash of column ⇒ raw-SQL expression — to replace the default `col = v.col` assignment. Typical use: leave a column at its stored value unless the row is in the expected state, while still writing the other columns.
+
+```ruby
+PgSqlCaller::BulkUpdate.call(Order, [
+  { id: 1, status: 'delivered', delivered_at: Time.current }
+], set_override: {
+  status: %q{CASE WHEN t."status" = 'pending' THEN v."status" ELSE t."status" END}
+})
+```
+
+A key that isn't in `attrs_list` adds an assignment of its own (there is no `v.col` for it to replace), so a column can be written purely from SQL:
+
+```ruby
+PgSqlCaller::BulkUpdate.call(Employee, attrs_list, set_override: { updated_at: 'NOW()' })
+```
+
+Overridden payload columns keep their position in the `SET` clause; overrides of columns absent from the payload are appended after it.
+
+> ⚠️ **`condition` and `set_override` values are raw SQL, interpolated verbatim** — they are the one part of `BulkUpdate` that is not bound through the sanitizer. Never build them from untrusted input; use `quote_value` for any value you need to embed. Qualify every column reference with `t.` (the target table) or `v.` (the `unnest` source): both aliases expose the same column names, so an unqualified reference is rejected by PostgreSQL as `column reference "..." is ambiguous`.
+
 ### 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.
+- 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 — unless a `set_override` names them.
 - 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). 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.
+- Raises `ArgumentError` (before touching the database) if a row omits a `unique_by` column, names a column that doesn't exist on the model, `returning` is empty or names an unknown column, `condition` is blank, or `set_override` names an unknown or `unique_by` column or carries a blank expression.
+- The statement is available without running it: `PgSqlCaller::BulkUpdate.new(Employee, attrs_list, **options).sql` returns the exact SQL `.call` would execute (its `?` placeholders bound to one typed array per column). It validates exactly what `.call` does, so anything `.call` would reject raises the same `ArgumentError` here instead of yielding an invalid statement — including an empty `attrs_list`, for which `.call` runs no statement at all.
 
 ### Why not `upsert_all` or a loop of `update_all`?
 
@@ -365,7 +403,7 @@ A single column may be passed as a `Symbol` (`returning: :id`). Without `returni
 `PgSqlCaller` is built so that **values are always bound through ActiveRecord's sanitizer and never interpolated into SQL**:
 
 - All `?` placeholders in reading/writing methods are sanitized by `sanitize_sql_array` (quoted and escaped).
-- `BulkUpdate` binds every value as a typed PostgreSQL array; the only identifiers placed into its SQL are restricted to the model's own column names (validated against `column_names`), so the statement is injection-safe by construction — even values like `"'); DROP TABLE employees;--"` are stored verbatim as data.
+- `BulkUpdate` binds every value as a typed PostgreSQL array; the only identifiers placed into its SQL are restricted to the model's own column names (validated against `column_names`), so the statement is injection-safe by construction — even values like `"'); DROP TABLE employees;--"` are stored verbatim as data. Its optional `condition:` and `set_override:` fragments are the exception: they are raw SQL you supply and are interpolated verbatim (see [Bulk updates](#bulk-updates)).
 
 What is **your** responsibility: any SQL fragment, table name, or column name you build into a statement string yourself (rather than passing as a `?` binding) is run as-is. Use `quote_column_name`, `quote_table_name`, and `quote_value` for those, and never interpolate untrusted input directly into the SQL string.
 

data/lib/pg_sql_caller/bulk_update.rb

@@ -17,6 +17,24 @@ module PgSqlCaller
   #
   #   PgSqlCaller::BulkUpdate.call(Employee, attrs_list, unique_by: %i[department_id name])
   #
+  # Narrow which rows are eligible with `condition`, and rewrite how individual columns are
+  # assigned with `set_override` — both are raw SQL fragments, interpolated verbatim:
+  #
+  #   PgSqlCaller::BulkUpdate.call(Order, [{ id: 1, status: 'processing' }],
+  #                                condition: "t.status = 'pending'")
+  #
+  #   PgSqlCaller::BulkUpdate.call(
+  #     Order,
+  #     [{ id: 1, status: 'delivered', delivered_at: now }],
+  #     set_override: {
+  #       status: "CASE WHEN t.status = 'pending' THEN v.status ELSE t.status END"
+  #     }
+  #   )
+  #
+  # Qualify every column reference in those fragments with `t.` (the target table) or `v.`
+  # (the unnest source): both aliases expose the same column names, so an unqualified
+  # reference raises `column reference "..." is ambiguous`.
+  #
   # Chosen over `upsert_all`: PostgreSQL NOT NULL-checks the candidate INSERT tuple of
   # `INSERT ... ON CONFLICT DO UPDATE` *before* conflict arbitration, so upsert rejects
   # partial payloads that omit the table's other NOT NULL columns. This join only ever
@@ -33,37 +51,56 @@ module PgSqlCaller
   # Each column is sent as one typed PostgreSQL array; `unnest` zips the arrays back
   # into rows. Values are bound through ActiveRecord's sanitizer (PgSqlCaller::Model) and
   # never interpolated; the only identifiers placed into the SQL are restricted to the
-  # model's own columns, so the statement is injection-safe by construction.
+  # model's own columns, so the statement is injection-safe by construction. The exception
+  # is `condition` and the `set_override` expressions: those are raw SQL supplied by the
+  # caller and interpolated verbatim, so they must never be built from untrusted input.
   class BulkUpdate
     # Build and run a bulk update in one call.
     #
     # @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+)
+    # @param unique_by [Symbol, String, Array<Symbol>, Array<String>] the match column(s) —
+    #   a single column, or all parts of a composite key (default +: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
+    # @param condition [String, nil] an extra raw-SQL predicate ANDed onto the match
+    #   clause, so only rows also satisfying it are updated; +nil+ (default) adds nothing
+    # @param set_override [Hash{Symbol, String => String}] raw-SQL expressions replacing the
+    #   default +v.col+ assignment of the named columns (default +{}+)
     # @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
+    def self.call(model_class, attrs_list, unique_by: :id, returning: nil, condition: nil, set_override: {})
+      new(
+        model_class,
+        attrs_list,
+        unique_by: unique_by,
+        returning: returning,
+        condition: condition,
+        set_override: set_override
+      ).call
     end
 
-    attr_reader :model_class, :unique_by, :attrs_list, :returning
+    attr_reader :model_class, :unique_by, :attrs_list, :returning, :condition, :set_override
 
     # @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+)
+    # @param unique_by [Symbol, String, Array<Symbol>, Array<String>] the match column(s) —
+    #   a single column, or all parts of a composite key (default +: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)
+    # @param condition [String, nil] an extra raw-SQL predicate ANDed onto the match
+    #   clause, so only rows also satisfying it are updated; +nil+ (default) adds nothing
+    # @param set_override [Hash{Symbol, String => String}] raw-SQL expressions replacing the
+    #   default +v.col+ assignment of the named columns (default +{}+)
+    def initialize(model_class, attrs_list, unique_by: :id, returning: nil, condition: nil, set_override: {})
       @model_class = model_class
       @attrs_list = attrs_list
-      @unique_by = Array(unique_by)
+      @unique_by = Array(unique_by).map(&:to_sym)
       @returning = returning.nil? ? nil : Array(returning)
+      @condition = condition
+      @set_override = set_override.to_h.transform_keys(&:to_sym)
     end
 
     # Execute the bulk update as a single `UPDATE ... FROM unnest(...)` statement.
@@ -72,20 +109,57 @@ module PgSqlCaller
     #   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
+    #   not exist on the model, +returning+ is empty or names an unknown column,
+    #   +condition+ is blank, or +set_override+ names an unknown or `unique_by` column
+    #   or carries a blank expression
     def call
-      validate_returning! unless returning.nil?
+      validate!
       return empty_result if attrs_list.empty?
 
       if returning.nil?
-        sql_caller.execute(sql, *bindings).cmd_tuples
+        sql_caller.execute(build_sql, *bindings).cmd_tuples
       else
-        sql_caller.select_all_serialized(sql, *bindings)
+        sql_caller.select_all_serialized(build_sql, *bindings)
       end
     end
 
+    # The full `UPDATE ... FROM unnest(...)` statement, with one `?` placeholder per
+    # column for the value arrays, plus a `RETURNING` clause when +returning+ was given.
+    # Public so the generated SQL can be inspected and asserted on directly: it runs the
+    # very same validations as {#call}, so an input {#call} would reject never yields a
+    # statement here either. An empty +attrs_list+ has no statement at all ({#call}
+    # short-circuits to {#empty_result} instead of building one), so it raises.
+    #
+    # @return [String]
+    # @raise [ArgumentError] on any input {#call} rejects (see {#validate!} and
+    #   {#validate_columns!}), or when +attrs_list+ is empty
+    def sql
+      validate!
+      raise ArgumentError, 'attrs_list must not be empty to build SQL' if attrs_list.empty?
+
+      build_sql
+    end
+
     private
 
+    # Assemble the statement itself, with no validation of its own: {#call} and {#sql} each
+    # validate before reaching here, so this is only ever called on inputs already checked
+    # and on a non-empty +attrs_list+.
+    #
+    # @return [String]
+    # @raise [ArgumentError] via {#validate_columns!} on first use of {#columns}
+    def build_sql
+      statement = <<~SQL.squish
+        UPDATE #{model_class.quoted_table_name} AS t
+        SET #{set_clause}
+        FROM unnest(#{unnest_args}) AS v(#{column_aliases})
+        WHERE #{where_clause}
+      SQL
+      return statement if returning.nil?
+
+      "#{statement} RETURNING #{returning_clause}"
+    end
+
     # 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.
     #
@@ -94,6 +168,20 @@ module PgSqlCaller
       returning.nil? ? 0 : []
     end
 
+    # Validate every option that does not depend on the payload — the entry point of both
+    # {#call} and {#sql}, so the two reject exactly the same inputs. {#call} runs it before
+    # its empty-+attrs_list+ short-circuit, so bad options raise even when there is nothing
+    # to update. The payload's own columns are validated separately, by {#validate_columns!}
+    # on first use of {#columns}.
+    #
+    # @return [void]
+    # @raise [ArgumentError] if +returning+, +condition+ or +set_override+ is invalid
+    def validate!
+      validate_returning! unless returning.nil?
+      validate_condition! unless condition.nil?
+      validate_set_override! unless set_override.empty?
+    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).
@@ -107,6 +195,35 @@ module PgSqlCaller
       raise ArgumentError, "unknown #{model_class} returning columns: #{unknown.join(', ')}" if unknown.any?
     end
 
+    # Validate the extra `WHERE` predicate before any SQL runs. Its contents are raw SQL and
+    # cannot be checked further — only that something was actually given, so a blank string
+    # never silently produces `... AND ()`.
+    #
+    # @return [void]
+    # @raise [ArgumentError] if +condition+ is blank
+    def validate_condition!
+      raise ArgumentError, 'condition must not be blank' if condition.to_s.strip.empty?
+    end
+
+    # Validate the `SET` overrides before any SQL runs: every key must be a real column of the
+    # model (it becomes a quoted assignment target) and must not be one of the `unique_by`
+    # columns (rewriting a match column would change the very key the row was found by), and
+    # every expression must be non-blank so no assignment is left dangling. The expressions
+    # themselves are raw SQL and cannot be checked further.
+    #
+    # @return [void]
+    # @raise [ArgumentError] if a key is unknown or a `unique_by` column, or a value is blank
+    def validate_set_override!
+      unknown = set_override.keys.map(&:to_s) - model_class.column_names
+      raise ArgumentError, "unknown #{model_class} set_override columns: #{unknown.join(', ')}" if unknown.any?
+
+      overridden_keys = set_override.keys & unique_by
+      raise ArgumentError, "set_override must not override unique_by #{overridden_keys.inspect}" if overridden_keys.any?
+
+      blank = set_override.select { |_col, expression| expression.to_s.strip.empty? }.keys
+      raise ArgumentError, "set_override expressions must not be blank: #{blank.inspect}" if blank.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.
     #
@@ -131,19 +248,22 @@ module PgSqlCaller
     end
 
     # Validate the payload's columns before any SQL runs: every `unique_by` column must
-    # be present, at least one value column must remain, every column must exist on the
-    # model, and every row must carry the same key set as the first row (so no row
-    # silently writes NULLs or drops extra keys).
+    # be present, at least one column must be assigned (a value column, or a `set_override`
+    # expression standing in for one), every column must exist on the model, and every row
+    # must carry the same key set as the first row (so no row silently writes NULLs or
+    # drops extra keys).
     #
     # @param cols [Array<Symbol>] the columns taken from the first row
     # @return [void]
-    # @raise [ArgumentError] if a `unique_by` column is missing, there are no value
-    #   columns to update, a column is unknown, or a row's keys differ from the first row
+    # @raise [ArgumentError] if a `unique_by` column is missing, there is nothing to
+    #   assign, a column is unknown, or a row's keys differ from the first row
     def validate_columns!(cols)
       missing = unique_by - cols
       raise ArgumentError, "attrs_list rows must include unique_by #{missing.inspect}" if missing.any?
 
-      raise ArgumentError, "attrs_list has no value columns to update (only unique_by #{unique_by.inspect})" if (cols - unique_by).empty?
+      if (cols - unique_by).empty? && set_override.empty?
+        raise ArgumentError, "attrs_list has no value columns to update (only unique_by #{unique_by.inspect})"
+      end
 
       unknown = cols.map(&:to_s) - model_class.column_names
       raise ArgumentError, "unknown #{model_class} columns: #{unknown.join(', ')}" if unknown.any?
@@ -156,22 +276,6 @@ module PgSqlCaller
       end
     end
 
-    # The full `UPDATE ... FROM unnest(...)` statement, with one `?` placeholder per
-    # column for the value arrays, plus a `RETURNING` clause when +returning+ was given.
-    #
-    # @return [String]
-    def sql
-      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.
@@ -181,11 +285,28 @@ module PgSqlCaller
       returning.map { |col| "t.#{quoted(col)}" }.join(', ')
     end
 
-    # The `SET col = v.col, ...` assignments for the value columns.
+    # The `SET col = v.col, ...` assignments: one per value column, in payload order, each
+    # taking its raw-SQL `set_override` expression in place of `v.col` when one was given —
+    # followed by the overrides that name a column absent from the payload, which contribute
+    # an assignment of their own (there is no `v.col` for them to replace).
     #
     # @return [String]
     def set_clause
-      value_columns.map { |col| "#{quoted(col)} = v.#{quoted(col)}" }.join(', ')
+      extra_columns = set_override.keys - value_columns
+      (value_columns + extra_columns).map { |col|
+        "#{quoted(col)} = #{set_override.fetch(col) { "v.#{quoted(col)}" }}"
+      }.join(', ')
+    end
+
+    # The `WHERE` clause: the key match, narrowed by the raw-SQL +condition+ when one was
+    # given. The condition is parenthesized so a top-level `OR` inside it cannot widen the
+    # match beyond the join keys.
+    #
+    # @return [String]
+    def where_clause
+      return match_clause if condition.nil?
+
+      "#{match_clause} AND (#{condition})"
     end
 
     # Match each row on every `unique_by` column — one column, or all parts of a composite key.

data/lib/pg_sql_caller/version.rb

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

metadata

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