PgSqlCaller support of RETURNING instead of count

[blurvene]

Add optional returning: to PgSqlCaller::BulkUpdate

Lets BulkUpdate read columns back from the updated rows via SQL RETURNING, instead of just a row count.

Changes

• BulkUpdate.call(model, attrs, returning: %i[id name]) returns one Symbol-keyed, type-cast hash per updated row ([] when
  attrs_list is empty). A single column may be passed as a Symbol.
• Columns are qualified with the t alias (avoids ambiguity with the unnest source v).
• returning: columns are validated up front — empty or unknown columns raise ArgumentError before any SQL runs.
• No behavior change when returning: is omitted — still returns the affected-row Integer.

Tests / docs

• 10 new specs covering returning rows, type-casting, composite unique_by, empty list, and validation errors, plus a regression
  guard on the default count path. Full suite green, RuboCop clean.
• README "Bulk updates" section + CHANGELOG updated.

Versioning

• Bumped 1.0.0 → 1.1.0 (backward-compatible feature, SemVer MINOR).

[Copilot]

Pull request overview

Adds an optional returning: keyword to PgSqlCaller::BulkUpdate so callers can read back selected columns from updated rows via SQL RETURNING, while preserving the existing row-count behavior when omitted.

Changes:

• Extend BulkUpdate.call to accept returning: and return type-cast, Symbol-keyed row hashes when provided (otherwise return cmd_tuples count as before).
• Validate returning: columns up front (non-empty; all must be real model columns) and qualify projections with the t table alias to avoid ambiguity.
• Add specs + update README/CHANGELOG and bump gem version to 1.1.0.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
lib/pg_sql_caller/bulk_update.rb	Implements returning: support (validation, SQL RETURNING clause, return-shape handling).
spec/pg_sql_caller/bulk_update_spec.rb	Adds coverage for returning rows, type-casting, composite unique_by, empty input, and validation errors.
README.md	Documents the new “reading back updated rows” behavior and clarifies return shapes and validations.
CHANGELOG.md	Adds 1.1.0 entry describing the new returning: feature and compare link.
lib/pg_sql_caller/version.rb	Bumps version from 1.0.0 to 1.1.0.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.