pg_sql_caller 0.2.3 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f32bde3a1030726a04bdbabc0d9ac810dda3318e1aec4d7dd45b5b150110789c
-  data.tar.gz: 886c65ca130adddbd3f102e6bb9d0887970eba93a394bf28c34d2174219513ec
+  metadata.gz: b4ea6fd0cd19dd9e2d12d963b0c7689cef8346a63f0981e3a96821faebf4f6bc
+  data.tar.gz: f2d40a1f3790e084ebdb9e0bf5908241494aaacca55ca8604f18cf05a6dbb8d8
 SHA512:
-  metadata.gz: b7c8100f6d75a7f0d90c75f634bea9fdb67c08f345f0a7fddd8d9bb5c4f56147d8c845facf8f8a01b24b40a57c26574a9e959646bc6807c8fb6014517d581026
-  data.tar.gz: e1bc503b06afe4d8534e08daa12c491bf415651ed7efcb874d74fa31300cdf4a071eef247ba00298413643bfef76d23d6994f955e8437fe6ab424c73c3cba3c7
+  metadata.gz: 908fcb421cdf254ba4a91cc8c67c304938cfd65ef7a25393ae3019b02e0b84ea634c2fa250fba333e88bd287be02480aafce0cd8f0780e083d3b38800de9ab90
+  data.tar.gz: 927f8dc22e285bdf849e85bb850e5e2045429675ccb953b872150b0954ecf95602d6a6c84b52829e9b9af8b29fe8acc016d41be10628ae2181edd29c1df7d9a7

data/CHANGELOG.md

@@ -0,0 +1,92 @@
+# Changelog
+
+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]
+
+### Added
+
+- `PgSqlCaller::Model` — a standalone, instantiable class holding the SQL API.
+  Build one directly with `PgSqlCaller::Model.new(ApplicationRecord)`; `PgSqlCaller::Base`
+  is now a thin `Singleton` facade subclassing it.
+- `PgSqlCaller::BulkUpdate` — partial update of many existing rows in a single
+  `UPDATE ... FROM unnest(...)` statement and round-trip, with single- or composite-column
+  `unique_by` matching and column validation.
+- `quote_value`, `quote_column_name`, and `quote_table_name` quoting helpers.
+- `with_min_messages(level)` — temporarily set the connection's `client_min_messages`
+  around a block.
+- `with_notice_processor(callback)` — capture PostgreSQL `NOTICE` output emitted during a block.
+- `define_sql_method` (single-name) helper; the variadic `define_sql_methods` is retained for
+  backward compatibility.
+- CI test matrix against Rails 7.1, 7.2, 8.0, and 8.1 (bundled `gemfiles/`).
+
+### Changed
+
+- **BREAKING**: Minimum Ruby raised to `>= 3.2.0` (was `>= 2.3.0`).
+- **BREAKING**: `activerecord` and `activesupport` now require `>= 7.1` (previously unconstrained).
+- `PgSqlCaller::Base` now forwards class-level calls to its singleton instance via
+  `delegate_missing_to`, so every public `Model` instance method is available as a class
+  method automatically.
+- **BREAKING**: `current_database_name` was renamed to `current_database`.
+
+### Removed
+
+- **BREAKING**: The custom `Forwardable`-based `delegate` macro on `Base`, superseded by
+  ActiveSupport delegation and `delegate_missing_to`.
+
+## [0.2.3] - 2025-02-07
+
+### Fixed
+
+- `select_value_serialized` no longer raises when the query returns no rows; it now
+  returns `nil`.
+
+## [0.2.2] - 2023-02-08
+
+### Fixed
+
+- The class-level `PgSqlCaller::Base.connection` call now resolves correctly (delegated
+  to the singleton instance).
+
+## [0.2.1] - 2023-02-08
+
+### Added
+
+- `connection` exposed as a public method on the caller.
+
+## [0.2.0] - 2020-12-23
+
+### Added
+
+- `select_value_serialized` and `select_values_serialized` type-cast reads.
+- `next_sequence_value` to peek at a table's next sequence value.
+- `table_full_size` and `table_data_size` relation-size helpers.
+
+### Fixed
+
+- Serialized reads no longer raise on columns whose type is unknown; the raw value is
+  returned unchanged.
+
+### Changed
+
+- Homepage moved to the `didww` organization.
+
+## [0.1.0] - 2020-03-24
+
+### Added
+
+- Initial release: `PgSqlCaller::Base` singleton facade over an ActiveRecord class,
+  with `?`-bound, sanitized SQL helpers — `select_value`, `select_values`, `select_all`,
+  `select_rows`, `select_row`, `execute`, `select_all_serialized`, `transaction`,
+  `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
+[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
+[0.2.0]: https://github.com/didww/pg_sql_caller/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/didww/pg_sql_caller/releases/tag/v0.1.0

data/README.md

@@ -1,67 +1,395 @@
 # PgSqlCaller
 
-Postgresql Sql Caller for ActiveRecord.
+[![Gem Version](https://img.shields.io/gem/v/pg_sql_caller.svg)](https://rubygems.org/gems/pg_sql_caller)
+[![CI](https://github.com/didww/pg_sql_caller/actions/workflows/ci.yml/badge.svg)](https://github.com/didww/pg_sql_caller/actions/workflows/ci.yml)
+[![CodeQL](https://github.com/didww/pg_sql_caller/actions/workflows/codeql.yml/badge.svg)](https://github.com/didww/pg_sql_caller/actions/workflows/codeql.yml)
+
+A small, focused wrapper for running **raw SQL against PostgreSQL through ActiveRecord**.
+
+It gives you a clean API for the things ActiveRecord's query builder makes awkward — `SELECT`s that return a single scalar, a single column, raw rows, `EXPLAIN ANALYZE`, sequence/table introspection, PostgreSQL `NOTICE` capture, and efficient set-based bulk updates — while keeping every value **bound and sanitized** by ActiveRecord so your statements stay injection-safe.
+
+```ruby
+class Sql < PgSqlCaller::Base
+  model_class 'ApplicationRecord'
+end
+
+Sql.select_value('SELECT count(*) FROM users WHERE active = ?', true) # => 42
+Sql.select_values('SELECT id FROM users WHERE name = ?', 'John Doe')  # => [1, 2, 3]
+Sql.transaction { Sql.execute('DELETE FROM logs WHERE created_at < ?', 1.year.ago) }
+```
+
+## Table of contents
+
+- [Why use this](#why-use-this)
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Configuration](#configuration) — three ways to set it up
+- [How `?` placeholders work](#how--placeholders-work)
+- [API reference](#api-reference)
+  - [Reading data](#reading-data)
+  - [Serialized reads (Ruby type casting)](#serialized-reads-ruby-type-casting)
+  - [Writing data](#writing-data)
+  - [Transactions](#transactions)
+  - [Database & table introspection](#database--table-introspection)
+  - [Query plans](#query-plans)
+  - [PostgreSQL NOTICE capture](#postgresql-notice-capture)
+  - [Quoting & sanitizing helpers](#quoting--sanitizing-helpers)
+  - [Extending with custom SQL methods](#extending-with-custom-sql-methods)
+- [Bulk updates](#bulk-updates)
+- [Security](#security)
+- [Versioning & changelog](#versioning--changelog)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Why use this
+
+ActiveRecord already exposes low-level connection methods (`select_value`, `select_all`, `execute`, …), but reaching for them directly means writing `Model.connection.select_value(...)` everywhere, manually sanitizing bind values, and re-implementing the same small helpers in every project. `PgSqlCaller`:
+
+- Wraps those connection methods behind a stable, documented API on a class **you** name.
+- Binds `?` placeholders through ActiveRecord's sanitizer automatically — no manual quoting.
+- Adds PostgreSQL-specific helpers (type-cast reads, sequence peeking, relation sizes, `EXPLAIN ANALYZE`, `NOTICE` capture).
+- Provides a fast, injection-safe [bulk update](#bulk-updates) for partial updates of many existing rows in a single round-trip.
+
+## Requirements
+
+| Dependency    | Version            |
+| ------------- | ------------------ |
+| Ruby          | `>= 3.2.0`         |
+| ActiveRecord  | `>= 7.1`           |
+| ActiveSupport | `>= 7.1`           |
+| Database      | PostgreSQL         |
+
+Continuously tested against Rails **7.1, 7.2, 8.0, and 8.1** on Ruby **3.2–3.4**. PostgreSQL is required — the gem uses PostgreSQL-specific features (`pg_total_relation_size`, `unnest`, sequence introspection, the `pg` notice processor).
 
 ## Installation
 
-Add this line to your application's Gemfile:
+Add to your application's `Gemfile`:
 
 ```ruby
 gem 'pg_sql_caller'
 ```
 
-And then execute:
+Then run:
+
+```sh
+bundle install
+```
+
+Or install it directly:
 
-    $ bundle install
+```sh
+gem install pg_sql_caller
+```
 
-Or install it yourself as:
+## Configuration
 
-    $ gem install pg_sql_caller
+A caller is always backed by **one ActiveRecord class**, whose connection runs every statement and whose column types are used to sanitize and cast values. Pick whichever of the three setups below fits your app.
 
-## Usage
+### 1. Subclass `PgSqlCaller::Base` (recommended)
 
-create subclass from `PgSqlCaller::Base` and define `model_class` for it
+Declare the backing model once, then call SQL methods directly on your class. This is the most common setup and lets you have several callers (e.g. one per database) if needed.
 
 ```ruby
 require 'pg_sql_caller'
 
-class MySqlCaller < PgSqlCaller::Base
-  model_class 'ApplicationRecord'
+class Sql < PgSqlCaller::Base
+  model_class 'ApplicationRecord' # a String (constantized on first use) or the Class itself
 end
 
-MySqlCaller.select_values 'SELECT id from users WHERE parent_name = ?', 'John Doe' # => [1, 2, 3]
+Sql.select_values('SELECT id FROM users WHERE parent_name = ?', 'John Doe') # => [1, 2, 3]
 ```
 
-or just define `model_class` for `PgSqlCaller::Base` itself
+`model_class` accepts either the class or its name as a `String`. Passing a `String` defers loading the constant until the first call, which avoids autoload-order problems at boot.
+
+`PgSqlCaller::Base` is a `Singleton`: every class-level call is forwarded to the shared `.instance`, and **every** public instance method (including ones you add with [`define_sql_method`](#extending-with-custom-sql-methods)) is available as a class method.
+
+### 2. Configure `PgSqlCaller::Base` directly
+
+If you only need a single, global caller, configure the base class itself instead of subclassing:
 
 ```ruby
 PgSqlCaller::Base.model_class 'ApplicationRecord'
 
-PgSqlCaller::Base.select_values 'SELECT id from users WHERE parent_name = ?', 'John Doe' # => [1, 2, 3]
+PgSqlCaller::Base.select_values('SELECT id FROM users WHERE parent_name = ?', 'John Doe') # => [1, 2, 3]
+```
+
+### 3. Instantiate `PgSqlCaller::Model` per call
+
+For one-off use, or when you want an ordinary object rather than a singleton, build a `Model` directly. This is also what [`BulkUpdate`](#bulk-updates) uses internally.
+
+```ruby
+sql = PgSqlCaller::Model.new(ApplicationRecord)
+sql.select_value('SELECT count(*) FROM users') # => 42
+```
+
+> The class methods on `PgSqlCaller::Base` and the instance methods on `PgSqlCaller::Model` are the same API — the examples in the reference below use a `sql` instance, but `Sql.select_value(...)` works identically.
+
+## How `?` placeholders work
+
+Every reading and writing method takes a SQL string plus optional positional bindings. Each `?` in the SQL is replaced, **in order**, by a binding value that ActiveRecord quotes and escapes — values are never interpolated into the string yourself:
+
+```ruby
+sql.select_value('SELECT id FROM employees WHERE name = ?', "O'Brien")
+# ActiveRecord turns this into:  SELECT id FROM employees WHERE name = 'O''Brien'
+```
+
+If you pass no bindings, the SQL is run verbatim. See [Security](#security) for the guarantees this provides.
+
+## API reference
+
+The examples use this schema:
+
+```ruby
+class Department < ApplicationRecord; end
+class Employee   < ApplicationRecord  # columns: id, department_id, name, created_at, updated_at
+  belongs_to :department
+end
+```
+
+### Reading data
+
+| Method                                  | Returns                                                              |
+| --------------------------------------- | ------------------------------------------------------------------- |
+| `select_value(sql, *bindings)`          | First column of the first row, or `nil` if no row matches           |
+| `select_values(sql, *bindings)`         | First column of **every** row, as an `Array`                        |
+| `select_row(sql, *bindings)`            | First row as an `Array` of column values, or `nil`                  |
+| `select_rows(sql, *bindings)`           | Every row as an `Array` of column-value `Array`s                    |
+| `select_all(sql, *bindings)`            | An `ActiveRecord::Result` of String-keyed row hashes                |
+
+```ruby
+sql.select_value('SELECT count(*) FROM employees')                       # => 2
+sql.select_value('SELECT name FROM employees WHERE id = ?', -1)          # => nil
+
+sql.select_values('SELECT name FROM employees WHERE department_id = ?', 5)
+# => ["John", "Jane"]
+
+sql.select_row('SELECT id, name FROM employees ORDER BY id')             # => [1, "John"]
+sql.select_rows('SELECT id, name FROM employees')                        # => [[1, "John"], [2, "Jane"]]
+
+result = sql.select_all('SELECT id, name FROM employees')
+result                       # => #<ActiveRecord::Result ...>
+result.to_a                  # => [{ "id" => 1, "name" => "John" }, { "id" => 2, "name" => "Jane" }]
+```
+
+> **Type casting note:** the non-serialized reads above return values as decoded by the PostgreSQL adapter — common scalar types (integers, booleans, floats, timestamps) come back as Ruby objects, but **array and other complex/custom column types arrive as raw strings** (e.g. `'{1,2,3}'`). Use the serialized variants below when you need those cast to Ruby types.
+
+### Serialized reads (Ruby type casting)
+
+The `*_serialized` variants run the same query, then cast each value back to its Ruby type using ActiveRecord's column types — handling arrays and custom attribute types that the raw adapter leaves as strings. `select_all_serialized` additionally keys each row by `Symbol`.
+
+| Method                                    | Returns                                                       |
+| ----------------------------------------- | ------------------------------------------------------------- |
+| `select_value_serialized(sql, *bindings)` | First value of the first row, type-cast, or `nil`             |
+| `select_values_serialized(sql, *bindings)`| Every row as an `Array` of type-cast values                   |
+| `select_all_serialized(sql, *bindings)`   | Every row as a `Hash` with `Symbol` keys and type-cast values |
+
+```ruby
+# Raw read returns the PostgreSQL array literal as a String...
+sql.select_value('SELECT ARRAY[1,2,3]::int[]')              # => "{1,2,3}"
+# ...the serialized read casts it to a Ruby Array.
+sql.select_value_serialized('SELECT ARRAY[1,2,3]::int[]')   # => [1, 2, 3]
+
+sql.select_values_serialized('SELECT id, ARRAY[1,2]::int[] FROM employees')
+# => [[1, [1, 2]]]
+
+sql.select_all_serialized('SELECT id, created_at FROM employees')
+# => [{ id: 1, created_at: 2026-06-08 12:00:00 +0000 }, ...]
+```
+
+### Writing data
+
+| Method                     | Returns                                                       |
+| -------------------------- | ------------------------------------------------------------- |
+| `execute(sql, *bindings)`  | The raw `PG::Result` (use `#cmd_tuples` for affected rows)    |
+
+`execute` is for `INSERT` / `UPDATE` / `DELETE` / DDL and any statement whose row data you don't need back.
+
+```ruby
+result = sql.execute('UPDATE employees SET name = ? WHERE id = ?', 'Renamed', 1)
+result.cmd_tuples   # => 1  (number of rows affected)
+```
+
+For updating many existing rows efficiently, see [Bulk updates](#bulk-updates).
+
+### Transactions
+
+```ruby
+sql.transaction do
+  sql.execute('UPDATE accounts SET balance = balance - ? WHERE id = ?', 100, from_id)
+  sql.execute('UPDATE accounts SET balance = balance + ? WHERE id = ?', 100, to_id)
+end
+```
+
+- `transaction { ... }` — runs the block inside a database transaction, committing on success and rolling back if it raises. Returns the block's value. Raises `ArgumentError` if no block is given.
+- `transaction_open?` — `true` when a transaction is currently open on the connection (including one opened on the model class itself, e.g. `ApplicationRecord.transaction { ... }`).
+
+### Database & table introspection
+
+| Method                          | Returns                                                                                   |
+| ------------------------------- | ----------------------------------------------------------------------------------------- |
+| `current_database`              | The connected database name (`SELECT current_database()`)                                 |
+| `next_sequence_value(table)`    | The table's `<table>_id_seq` `last_value + 1`, read **without consuming** the sequence     |
+| `table_full_size(table)`        | Total on-disk size in bytes including indexes & TOAST (`pg_total_relation_size`)          |
+| `table_data_size(table)`        | Main data fork size in bytes only (`pg_relation_size`)                                    |
+
+```ruby
+sql.current_database                 # => "my_app_production"
+sql.next_sequence_value('employees') # => 124
+sql.table_full_size('employees')     # => 81920
+sql.table_data_size('employees')     # => 8192
+```
+
+> `next_sequence_value` peeks at the sequence's current value; it does not allocate or advance it, so it is **not** safe to use as a way to reserve an id under concurrency.
+
+### Query plans
+
+```ruby
+puts sql.explain_analyze('SELECT * FROM employees WHERE department_id = 5')
+# QUERY_PLAN
+# Seq Scan on employees  (cost=0.00..1.05 rows=1 width=...) (actual time=0.012..0.013 rows=1 loops=1)
+#   Filter: (department_id = 5)
+# Planning Time: 0.060 ms
+# Execution Time: 0.030 ms
+```
+
+`explain_analyze(sql)` runs `EXPLAIN ANALYZE` (which **executes** the statement) and returns the plan as a single multi-line `String` under a `QUERY_PLAN` header.
+
+### PostgreSQL NOTICE capture
+
+Capture `NOTICE` output (e.g. from `RAISE NOTICE` inside a `DO` block or function) emitted while a block runs:
+
+```ruby
+sql.with_notice_processor(->(msg) { Rails.logger.info(msg) }) do
+  sql.execute("DO $$ BEGIN RAISE NOTICE 'migrating row %', 42; END $$")
+end
+```
+
+- `with_notice_processor(callback) { ... }` — invokes `callback` with each notice message (a chomped `String`) emitted during the block. Lowers `client_min_messages` to `notice` for the duration and restores the previous notice processor afterward. Returns the block's value.
+- `with_min_messages(level) { ... }` — temporarily sets the connection's `client_min_messages` to `level` (`debug5`…`debug1`, `log`, `notice`, `warning`, `error`) for the block, restoring the previous value afterward. Returns the block's value.
+
+### Quoting & sanitizing helpers
+
+For the cases where you must build SQL fragments yourself, these expose ActiveRecord's quoting so you stay safe:
+
+| Method                         | Purpose                                                                            |
+| ------------------------------ | --------------------------------------------------------------------------------- |
+| `quote_value(value)`           | Quote/escape a value as a SQL literal — `"O'Brien"` → `"'O''Brien'"`               |
+| `quote_column_name(name)`      | Quote a column identifier — `"name"` → `'"name"'`                                  |
+| `quote_table_name(name)`       | Quote a table identifier — `"employees"` → `'"employees"'`                         |
+| `sanitize_sql_array(sql, *b)`  | Interpolate `?` placeholders and return the safe SQL `String` (no execution)       |
+| `typecast_array(values, type:)`| Encode a Ruby `Array` into a PostgreSQL array literal for the given attribute type |
+
+```ruby
+sql.quote_value("O'Brien")                                 # => "'O''Brien'"
+sql.quote_column_name('name')                              # => "\"name\""
+sql.sanitize_sql_array('name = ? AND id = ?', "O'Brien", 5) # => "name = 'O''Brien' AND id = 5"
+sql.typecast_array([1, 2, 3], type: :integer)              # => "{1,2,3}"
+sql.typecast_array(['a', 'b,c'], type: :string)            # => "{a,\"b,c\"}"
+```
+
+Accessors `model_class` (the wrapped class) and `connection` (its adapter) are also public.
+
+### Extending with custom SQL methods
+
+`PgSqlCaller::Model` builds its core readers with the class macro `define_sql_method`, which wraps any connection method that takes a SQL string. Subclass `Model` (or `Base`) to expose additional connection methods with the same `?`-binding behavior:
+
+```ruby
+class Sql < PgSqlCaller::Base
+  model_class 'ApplicationRecord'
+
+  # Expose the adapter's #exec_query through the same binding/sanitizing path.
+  define_sql_method :exec_query
+end
+
+Sql.exec_query('SELECT * FROM employees WHERE id = ?', 1)
 ```
 
+Because `PgSqlCaller::Base` delegates missing class methods to its singleton instance, methods added this way are immediately callable at the class level.
+
+## Bulk updates
+
+`PgSqlCaller::BulkUpdate` performs a **partial update of many existing rows in a single statement and a single round-trip**, using `UPDATE ... FROM unnest(...)`. Each column is sent as one typed PostgreSQL array; `unnest` zips the arrays back into rows that are joined to the target table on a key.
+
+```ruby
+PgSqlCaller::BulkUpdate.call(Employee, [
+  { id: 1, name: 'John', department_id: 10 },
+  { id: 2, name: 'Jane', department_id: 20 }
+])
+# => 2   (number of rows affected)
+```
+
+### Matching on a composite key
+
+By default rows are matched on `:id`. Pass `unique_by` to match on a different column, or an array of columns for a composite key:
+
+```ruby
+PgSqlCaller::BulkUpdate.call(Employee, attrs_list, unique_by: :employee_number)
+PgSqlCaller::BulkUpdate.call(Employee, attrs_list, unique_by: %i[department_id name])
+```
+
+### 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.
+
+### Why not `upsert_all` or a loop of `update_all`?
+
+- **vs. `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 touches the listed columns of rows that already exist.
+- **vs. N `update_all` calls in a transaction:** a transaction makes those writes atomic but doesn't batch them — it's still N statements, N round-trips, and N parse/plan cycles. `BulkUpdate` is one statement and one round-trip; round-trip latency dominates the N-call approach as the row count grows, so `BulkUpdate` stays roughly flat while the loop scales linearly.
+
+> There's a benchmark demonstrating the speedup in `spec/pg_sql_caller/bulk_update_spec.rb`. Run it with:
+> ```sh
+> bundle exec rspec spec/pg_sql_caller/bulk_update_spec.rb --tag benchmark
+> ```
+
+## Security
+
+`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.
+
+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.
+
+The repository's CI runs RuboCop, `bundle-audit` (dependency CVEs), CodeQL, and Semgrep (including a custom SQL-injection ruleset) on every change.
+
+## Versioning & changelog
+
+This project adheres to [Semantic Versioning](https://semver.org). Given a `MAJOR.MINOR.PATCH` version, breaking API changes bump `MAJOR`, backward-compatible additions bump `MINOR`, and fixes bump `PATCH`.
+
+All notable changes are recorded in [CHANGELOG.md](CHANGELOG.md), which follows the [Keep a Changelog](https://keepachangelog.com) format. Unreleased changes are listed there before each release.
+
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies.
-Create `spec/config/database.yml` (look at `spec/config/database.travis.yml` for example).
-You need to create test database, so run `psql -c 'CREATE DATABASE pg_sql_caller_test;'`.
-Then, run `rake spec` to run the tests. 
-You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo:
 
-To install this gem onto your local machine, run `bundle exec rake install`. 
-To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+```sh
+bin/setup                                   # install dependencies
+cp spec/config/database.github.yml spec/config/database.yml   # then edit credentials as needed
+psql -c 'CREATE DATABASE pg_sql_caller_test;'                  # create the test database
+bundle exec rake spec                       # run the tests
+```
 
-## TODO
+`bin/console` gives you an interactive prompt to experiment.
 
-* add more tests
-* add more usage examples
-* add documentation
-* release 1.0 after all above
+To test against a specific Rails version, use one of the bundled gemfiles:
 
-## Contributing
+```sh
+BUNDLE_GEMFILE=gemfiles/rails_8_1.gemfile bundle install
+BUNDLE_GEMFILE=gemfiles/rails_8_1.gemfile bundle exec rspec
+```
+
+Available: `rails_7_1`, `rails_7_2`, `rails_8_0`, `rails_8_1`.
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/didww/pg_sql_caller. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/didww/sql_caller/blob/master/CODE_OF_CONDUCT.md).
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `lib/pg_sql_caller/version.rb`, then run `bundle exec rake release`, which creates a git tag, pushes commits and tags, and pushes the `.gem` to [rubygems.org](https://rubygems.org).
+
+## Contributing
 
+Bug reports and pull requests are welcome on GitHub at https://github.com/didww/pg_sql_caller. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/didww/pg_sql_caller/blob/master/CODE_OF_CONDUCT.md).
 
 ## License
 
@@ -69,4 +397,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the PGSqlCaller project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/didww/pg_sql_caller/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the PgSqlCaller project's codebases, issue trackers, chat rooms, and mailing lists is expected to follow the [code of conduct](https://github.com/didww/pg_sql_caller/blob/master/CODE_OF_CONDUCT.md).