simple_query 0.4.0 → 0.6.0

data/README.md

@@ -1,39 +1,76 @@
 # SimpleQuery
 
-SimpleQuery is a lightweight and efficient query builder for ActiveRecord, designed to provide a flexible and performant way to construct complex database queries in Ruby on Rails applications.
+[![Gem Version](https://badge.fury.io/rb/simple_query.svg)](https://badge.fury.io/rb/simple_query)
+[![SimpleQuery CI](https://github.com/kholdrex/simple_query/actions/workflows/ci.yml/badge.svg)](https://github.com/kholdrex/simple_query/actions/workflows/ci.yml)
+
+SimpleQuery is a lightweight query builder for ActiveRecord. It gives Rails applications an explicit, chainable API for read-heavy queries, joins, aggregations, read models, bulk updates, and adapter-aware streaming without replacing ActiveRecord.
+
+Use it when you want ActiveRecord-backed SQL with less object-instantiation overhead, predictable result shapes, or a small query/read-model layer around reporting and data-processing code.
+
+## Features
+
+- Chainable query builder for ActiveRecord models
+- Struct results by default for lightweight reads
+- Optional custom read models with explicit attributes
+- Hash, Arel, raw SQL, and ActiveRecord-style placeholder conditions
+- Inner, left, right, and full joins
+- `distinct`, `group`, `having`, `order`, `limit`, and `offset`
+- Aggregation helpers: `count`, `sum`, `avg`, `min`, `max`, `variance`, `stddev`, `group_concat`, `stats`, and custom aggregations
+- Named `simple_scope` definitions for reusable SimpleQuery chains
+- `bulk_update` for set-based updates
+- `stream_each` for large result sets on PostgreSQL and MySQL
 
 ## Installation
 
-Add this line to your application's Gemfile:
+Add SimpleQuery to your application's Gemfile:
 
 ```ruby
-gem 'simple_query'
+gem "simple_query"
 ```
 
-And then execute:
+Then install:
+
 ```bash
 bundle install
 ```
 
-Or install it yourself as:
+Or install it directly:
+
 ```bash
 gem install simple_query
 ```
 
+## Compatibility
+
+SimpleQuery currently declares support for:
+
+- Ruby `>= 2.7`
+- ActiveRecord `>= 7.0`, `< 8.2`
+
+Queries run on the model's own connection, so models that use `connects_to` or `establish_connection` for another database work as expected.
+
+The CI matrix covers ActiveRecord 7.0, 7.1, 7.2, 8.0, and 8.1 across PostgreSQL and MySQL. ActiveRecord 7.0 is covered through Ruby 3.2; ActiveRecord 8.0 and 8.1 require Ruby 3.2 or newer; otherwise each Ruby is exercised on the ActiveRecord versions that support it.
+
 ## Configuration
 
-By default, `SimpleQuery` does **not** automatically patch `ActiveRecord::Base`. You can **manually** include the module in individual models or in a global initializer:
+SimpleQuery does not patch every ActiveRecord model by default. Include it in the models that should expose `.simple_query`:
 
 ```ruby
-# Manual include (per model)
 class User < ActiveRecord::Base
   include SimpleQuery
 end
+```
+
+Or include it globally if you want every ActiveRecord model to have `.simple_query`:
+
+```ruby
+# config/initializers/simple_query.rb
+require "simple_query"
 
-# or do it globally
 ActiveRecord::Base.include(SimpleQuery)
 ```
-If you prefer a “just works” approach (i.e., every model has `.simple_query`), you can opt in:
+
+You can also opt into global inclusion through SimpleQuery's configuration hook:
 
 ```ruby
 # config/initializers/simple_query.rb
@@ -42,28 +79,144 @@ SimpleQuery.configure do |config|
 end
 ```
 
-This tells SimpleQuery to automatically do `ActiveRecord::Base.include(SimpleQuery)` for you.
+## Basic usage
+
+```ruby
+users = User.simple_query
+            .select(:name, :email)
+            .where(active: true)
+            .order(name: :asc)
+            .limit(50)
+            .execute
+
+users.first
+# => #<struct name="Jane Doe", email="jane@example.com">
+```
+
+`execute` returns an array of lightweight `Struct` objects unless you map the query to a custom read model.
+
+## Conditions
 
-## Usage
+SimpleQuery accepts several condition styles.
 
-SimpleQuery offers an intuitive interface for building queries with joins, conditions, and aggregations. Here are some examples:
+### Hash conditions
 
-Basic query
 ```ruby
-User.simple_query.select(:name, :email).where(active: true).execute
+User.simple_query
+    .select(:name, :email)
+    .where(active: true, admin: false)
+    .execute
 ```
 
-Query with join
+Hash conditions are predicates against the query's base table. Arrays become `IN (...)` (a `nil` element adds `OR ... IS NULL`), ranges become `BETWEEN`, and other values become equality checks. PostgreSQL array and range columns compare by equality, as in ActiveRecord.
+
+### Arel conditions
 
-SimpleQuery now supports **all major SQL join types** — including LEFT, RIGHT, and FULL — through the following DSL methods:
 ```ruby
+users = User.arel_table
+
 User.simple_query
-    .left_join(:users, :companies, foreign_key: :user_id, primary_key: :id)
-    .select("users.name", "companies.name")
+    .select(:name)
+    .where(users[:created_at].gteq(30.days.ago))
+    .execute
+```
+
+### Placeholder conditions
+
+Array conditions are sanitized through ActiveRecord's `sanitize_sql_array`, so they are the preferred way to use SQL fragments with external or user-provided values:
+
+```ruby
+escaped_search = ActiveRecord::Base.sanitize_sql_like(params[:search].to_s)
+search_pattern = "%#{escaped_search}%"
+
+User.simple_query
+    .where(["name LIKE ?", search_pattern])
+    .execute
+
+User.simple_query
+    .where(["email = :email", { email: params[:email] }])
     .execute
 ```
 
-Complex query with multiple joins and conditions
+Keep the SQL fragment itself static and pass dynamic values as positional or named placeholders so ActiveRecord quotes them as SQL data literals. Do not interpolate request parameters, form values, or other untrusted input into the SQL string.
+
+### Raw SQL conditions
+
+Plain strings are treated as raw SQL fragments:
+
+```ruby
+User.simple_query
+    .where("active = TRUE")
+    .execute
+```
+
+Raw SQL strings are an escape hatch for trusted, application-owned SQL only. If any value comes from a user, request, file, or external service, use hash, Arel, or placeholder conditions instead. The checklist below shows the safer patterns to prefer when query inputs are dynamic.
+
+### SQL fragment safety checklist
+
+SimpleQuery intentionally accepts SQL fragments in places where ActiveRecord also leaves judgment to the application, such as raw `where` strings, string `select` values, and `custom_aggregation` expressions. Treat those fragments as trusted code, not as a templating surface for request data.
+
+Prefer these patterns for dynamic values:
+
+```ruby
+# Good: read dynamic values, then pass them separately so ActiveRecord quotes them.
+email = params.fetch(:email)
+User.simple_query
+    .where(["email = :email", { email: email }])
+    .execute
+
+# Good: quote LIKE values with placeholders. Escape wildcard characters when
+# `%` and `_` should be treated as literal search text instead of wildcards.
+search = params.fetch(:search)
+escaped_search = ActiveRecord::Base.sanitize_sql_like(search)
+User.simple_query
+    .where(["name LIKE ?", "%#{escaped_search}%"])
+    .execute
+```
+
+Avoid interpolating untrusted values into SQL fragments:
+
+```ruby
+# Unsafe: request data is interpolated into a raw SQL string.
+User.simple_query
+    .where("email = '#{params[:email]}'")
+    .execute
+```
+
+Even with quotes around the value, interpolation is unsafe because an apostrophe or SQL fragment in the input can break out of the literal. Keep the SQL string static and pass values through placeholders so ActiveRecord quotes them as SQL data literals instead. For `LIKE` queries, `sanitize_sql_like` only changes matching semantics by escaping `%`, `_`, and the escape character itself; it is useful when those characters should be searched literally, but it does not replace placeholder quoting.
+
+The same boundary applies outside `where`: keep selected expressions, ordering fragments, and custom aggregation SQL static and application-owned. When a user chooses a column, sort direction, or metric, map that input to a small allowlist before building the query:
+
+```ruby
+sort_columns = {
+  "name" => :name,
+  "created_at" => :created_at
+}
+sort_directions = {
+  "asc" => :asc,
+  "desc" => :desc
+}
+
+User.simple_query
+    .select(:id, :name, :email)
+    .order(sort_columns.fetch(params[:sort], :name) => sort_directions.fetch(params[:direction], :asc))
+    .execute
+```
+
+## Joins
+
+Joins are explicit: pass the left table, right table, foreign key, and primary key.
+
+```ruby
+User.simple_query
+    .select(:name, :email)
+    .join(:users, :companies, foreign_key: :user_id, primary_key: :id)
+    .where(Company.arel_table[:name].eq("TechCorp"))
+    .execute
+```
+
+Multiple joins can be chained:
+
 ```ruby
 User.simple_query
     .select(:name)
@@ -71,67 +224,125 @@ User.simple_query
     .join(:companies, :projects, foreign_key: :company_id, primary_key: :id)
     .where(Company.arel_table[:industry].eq("Technology"))
     .where(Project.arel_table[:status].eq("active"))
-    .where(User.arel_table[:admin].eq(true))
     .execute
 ```
 
-Lazy execution
+Join helpers are also available:
+
 ```ruby
 User.simple_query
+    .left_join(:users, :companies, foreign_key: :user_id, primary_key: :id)
     .select(:name)
-    .where(active: true)
-    .lazy_execute
+    .execute
 ```
 
-Placeholder-Based Conditions
+Supported join types:
+
+- `join(..., type: :inner)` / `join(...)`
+- `left_join(...)`
+- `right_join(...)`
+- `full_join(...)`
+
+Database support for right and full outer joins depends on the adapter and database version.
 
-SimpleQuery now supports **ActiveRecord-style placeholders**, letting you pass arrays with `?` or `:named` placeholders to your `.where` clauses:
+## Selecting, ordering, and paging
 
 ```ruby
-# Positional placeholders:
 User.simple_query
-    .where(["name LIKE ?", "%Alice%"])
+    .select(:id, :name, "LOWER(email) AS normalized_email")
+    .distinct
+    .where(active: true)
+    .order(name: :asc)
+    .limit(25)
+    .offset(50)
     .execute
+```
 
-# Named placeholders:
-User.simple_query
-    .where(["email = :email", { email: "alice@example.com" }])
-    .execute
+`select` accepts symbols, SQL strings, and Arel nodes. SQL strings are inserted as SQL fragments, so keep them trusted.
 
-# Multiple placeholders in one condition:
-User.simple_query
-    .where(["age >= :min_age AND age <= :max_age", { min_age: 18, max_age: 35 }])
-    .execute
+`order` accepts a hash of column names to directions, such as `order(created_at: :desc)`.
+
+## Aggregations
+
+SimpleQuery can build common aggregate expressions without hand-writing each SQL expression.
+
+```ruby
+Company.simple_query
+       .count
+       .sum(:annual_revenue)
+       .avg(:annual_revenue)
+       .min(:annual_revenue)
+       .max(:annual_revenue)
+       .execute
 ```
 
-## Custom Read Models
-By default, SimpleQuery returns results as `Struct` objects for maximum speed. However, you can also define a lightweight model class for more explicit attribute handling or custom logic.
+Custom aliases are supported:
 
-**Create a read model** inheriting from `SimpleQuery::ReadModel`:
 ```ruby
-class MyUserReadModel < SimpleQuery::ReadModel
-  attribute :identifier, column: :id
-  attribute :full_name,  column: :name
-end
+Company.simple_query
+       .count(:id, alias_name: "company_count")
+       .sum(:annual_revenue, alias_name: "total_revenue")
+       .execute
 ```
 
-**Map query results** to your read model:
+Grouped aggregations work with selected fields:
+
 ```ruby
-results = User.simple_query
-              .select("users.id AS id", "users.name AS name")
-              .where(active: true)
-              .map_to(MyUserReadModel)
-              .execute
+Company.simple_query
+       .select(:industry)
+       .count(alias_name: "company_count")
+       .sum(:annual_revenue, alias_name: "total_revenue")
+       .group(:industry)
+       .execute
+```
+
+Convenience helpers include:
+
+```ruby
+Company.simple_query.stats(:annual_revenue).execute
+Company.simple_query.total_count.execute
+User.simple_query.variance(:score).stddev(:score).execute
+User.simple_query.group_concat(:name, separator: ", ").execute
+```
+
+For database-specific expressions, use `custom_aggregation` with trusted SQL:
+
+```ruby
+Company.simple_query
+       .custom_aggregation("COUNT(DISTINCT industry)", "unique_industries")
+       .execute
+```
 
-results.each do |user|
-  puts user.identifier    # => user.id from the DB
-  puts user.full_name     # => user.name from the DB
+## Custom read models
+
+By default, query results are returned as `Struct` objects. For named methods and domain-specific result objects, define a read model:
+
+```ruby
+class UserSummary < SimpleQuery::ReadModel
+  attribute :identifier, column: :id
+  attribute :full_name, column: :name
 end
 ```
-This custom read model approach provides more clarity or domain-specific logic while still being faster than typical ActiveRecord instantiation.
 
-## Named Scopes
-SimpleQuery now supports named scopes, allowing you to reuse common query logic in a style similar to ActiveRecord’s built-in scopes. To define a scope, use the simple_scope class method in your model:
+Map query results to the read model:
+
+```ruby
+users = User.simple_query
+            .select("users.id AS id", "users.name AS name")
+            .where(active: true)
+            .map_to(UserSummary)
+            .execute
+
+users.first.identifier
+users.first.full_name
+```
+
+The selected SQL aliases must match the read model's configured column names.
+
+## Named scopes
+
+Use `simple_scope` to define reusable query fragments on a model that includes SimpleQuery:
+
 ```ruby
 class User < ActiveRecord::Base
   include SimpleQuery
@@ -140,119 +351,239 @@ class User < ActiveRecord::Base
     where(active: true)
   end
 
-  simple_scope :admins do
-    where(admin: true)
-  end
+  simple_scope :admins, -> { where(admin: true) }
 
-  # Block-based scope with parameter
   simple_scope :by_name do |name|
     where(name: name)
   end
-
-  # Lambda-based scope with parameter
-  simple_scope :by_name, ->(name) { where(name: name) }
 end
 ```
-You can then chain these scopes seamlessly with the normal SimpleQuery DSL:
+
+Scopes are evaluated in the context of the SimpleQuery builder and can be chained with the normal DSL:
 
 ```ruby
-# Parameterless scopes
-results = User.simple_query.active.admins.execute
+User.simple_query
+    .active
+    .admins
+    .by_name("Jane Doe")
+    .select(:id, :name)
+    .execute
+```
 
-# Parameterized scope
-results = User.simple_query.by_name("Jane Doe").execute
+SimpleQuery validates positional scope arguments before invoking the scope body. If a scope is called with too few or too many positional arguments, it raises `ArgumentError` with the scope name and expected argument count. For scopes that declare Ruby keyword parameters, SimpleQuery forwards keywords to the scope body and lets Ruby raise its native keyword-argument errors.
 
-# Mixing scopes with other DSL calls
-results = User.simple_query
-              .by_name("John")
-              .active
-              .select(:id, :name)
-              .order(name: :asc)
-              .execute
-```
-### How It Works
+## Lazy execution and streaming
 
-Each scope block (e.g. by_name) is evaluated in the context of the SimpleQuery builder, so you can call any DSL method (where, order, etc.) inside it.
-Parameterized scopes accept arguments — passed directly to the block (e.g. |name| above).
-Scopes return self, so you can chain multiple scopes or mix them with standard query methods.
+`lazy_execute` returns an `Enumerator` over the query results:
 
-## Streaming Large Datasets
+```ruby
+enumerator = User.simple_query
+                 .select(:name)
+                 .where(active: true)
+                 .lazy_execute
+
+enumerator.each do |user|
+  puts user.name
+end
+```
 
-For massive queries (millions of rows), **SimpleQuery** offers a `.stream_each` method to avoid loading the entire result set into memory. It **automatically** picks a streaming approach depending on your database adapter:
+`lazy_execute` is useful when you want enumerator-style consumption, but it still uses ActiveRecord's `select_all` internally.
 
-- **PostgreSQL**: Uses a **server-side cursor** via `DECLARE ... FETCH`.
-- **MySQL**: Uses `mysql2` gem’s **streaming** (`stream: true, cache_rows: false, as: :hash`).
+For large PostgreSQL or MySQL result sets, use `stream_each`:
 
 ```ruby
-# Example usage:
 User.simple_query
+    .select(:id, :email)
     .where(active: true)
-    .stream_each(batch_size: 10_000) do |row|
-  # row is a struct or read-model instance
-  puts row.name
+    .stream_each(batch_size: 10_000) do |user|
+  puts user.email
 end
 ```
 
+Adapter behavior:
+
+- PostgreSQL: uses a server-side cursor with `DECLARE` / `FETCH`; `batch_size` must be a positive integer and controls the number of rows fetched per cursor read
+- MySQL: uses `mysql2` streaming with `stream: true`, `cache_rows: false`, and `as: :hash`; `batch_size` is validated as a positive integer for API symmetry, but mysql2 streams rows directly and does not expose a SimpleQuery-controlled batch size
+- Other adapters: `stream_each` raises `SimpleQuery::UnsupportedAdapterError` with the current adapter name
+
+Failure behavior:
+
+- `batch_size` must be a positive integer; invalid values raise `ArgumentError` before any adapter-specific SQL runs
+- PostgreSQL streaming wraps the cursor in a transaction, closes a declared cursor before rollback when row processing fails, attempts cursor cleanup before rollback on fetch failures, and propagates the original error
+- MySQL streaming uses the mysql2 driver's streaming result handling; query and row processing errors are propagated to the caller
+
+## Bulk updates
+
+`bulk_update` builds and executes a set-based `UPDATE` for the current query conditions:
+
+```ruby
+User.simple_query
+    .where(active: false)
+    .bulk_update(set: { status: 0 })
+```
+
+`bulk_update` sends SQL directly through the ActiveRecord connection and does not instantiate models or run ActiveRecord callbacks. If no `where` conditions are present, it updates the entire table. Joins, `limit`/`offset`, and `group`/`having` are not applied to the `UPDATE`, so `bulk_update` raises `ArgumentError` when any of them are present.
+
+## Subqueries
+
+You can use `build_query` to embed a SimpleQuery query as an Arel subquery:
+
+```ruby
+company_users = Company.simple_query
+                       .select(:user_id)
+                       .where(industry: "Technology")
+                       .build_query
+
+User.simple_query
+    .select(:name)
+    .where(User.arel_table[:id].in(company_users))
+    .execute
+```
+
 ## Performance
 
-SimpleQuery aims to outperform standard ActiveRecord queries at scale. We’ve benchmarked **1,000,000** records on **both PostgreSQL** and **MySQL**, with the following results:
+SimpleQuery is designed for read paths where ActiveRecord model instantiation is unnecessary overhead. Returning structs or read models can reduce allocation costs for large reporting-style queries.
+
+The repository includes an optional benchmark harness comparing ActiveRecord object loading and `update_all` with SimpleQuery structs, read models, and `bulk_update`. Treat benchmark numbers as workload-specific: validate them against your database, indexes, adapter, Ruby version, and query shape before making production claims.
+
+Run the reproducible local benchmark with:
+
+```sh
+bundle exec rake benchmark:reproducible
+```
+
+The harness uses SQLite by default, seeds deterministic data, warms up and repeats each timing measurement, and prints JSON with environment metadata plus timing results. If `memory_profiler` is available in your development bundle, the JSON also includes single-run allocation profiles for the read-path scenarios. Tune the workload with environment variables:
+
+```sh
+BENCHMARK_ROWS=50000 BENCHMARK_WARMUP=3 BENCHMARK_RUNS=10 \
+  bundle exec rake benchmark:reproducible
+```
+
+Available variables:
+
+- `BENCHMARK_ROWS` (default: `10000`) controls the number of users and matching companies seeded.
+- `BENCHMARK_WARMUP` (default: `2`) controls warmup iterations before samples are collected.
+- `BENCHMARK_RUNS` (default: `5`) controls the number of timed samples per scenario.
+- `BENCHMARK_DATABASE` (default: `:memory:`) can point at a SQLite database file if you want to inspect the generated benchmark-specific tables. The harness drops and recreates `simple_query_benchmark_users` and `simple_query_benchmark_companies` in that database on every run.
+
+The benchmark task writes JSON to standard output so it can be redirected into an artifact file. Keep progress messages or diagnostics on standard error if you extend the harness later.
+
+To preserve a run as a reviewable artifact, capture the JSON output to a file, validate that the artifact is parseable JSON, and keep the workload settings alongside it:
+
+```sh
+set -e
+mkdir -p tmp/benchmarks
+export BENCHMARK_ROWS=50000
+export BENCHMARK_WARMUP=3
+export BENCHMARK_RUNS=10
+bundle exec rake benchmark:reproducible > tmp/benchmarks/simple_query-reproducible.json
+ruby -rjson -e 'JSON.parse(File.read(ARGV.fetch(0)))' tmp/benchmarks/simple_query-reproducible.json
+```
 
-### PostgreSQL (1,000,000 records)
+Before sharing or comparing a result, record enough environment metadata to recreate the run. The benchmark JSON includes runtime details, key dependency versions, and exported `BENCHMARK_*` values. When the task runs from a Git checkout, it also includes the current Git revision and dirty-checkout status; otherwise those Git fields are `null`. It is still useful to save companion hardware notes and the short Git status from the same shell session:
+
+```sh
+set -e
+mkdir -p tmp/benchmarks
+{
+  echo "git_revision=$(git describe --always --dirty)"
+  echo "git_status_short_start"
+  git status --short
+  echo "git_status_short_end"
+  echo "hardware=$(uname -a)"
+} > tmp/benchmarks/simple_query-reproducible.metadata
 ```
-🚀 Performance Results (1000,000 records):
-ActiveRecord Query:                  10.36932 seconds
-SimpleQuery Execution (Struct):      3.46136 seconds
-SimpleQuery Execution (Read model):  2.20905 seconds
 
-----------------------------------------------------
-ActiveRecord find_each:              6.10077 seconds
-SimpleQuery stream_each:             2.75639 seconds
+Use captured benchmark output only as a reproducibility artifact. Do not compare runs from different hardware, databases, Ruby versions, dependency sets, dataset sizes, warmup counts, run counts, or benchmark databases as if they were equivalent. Prefer comparing changes by rerunning the same command on the same machine from a clean checkout of each revision, and treat non-empty `git status --short` metadata as a signal that the run may not be reproducible from the recorded revision alone. Scrub sensitive environment values before sharing artifacts if any `BENCHMARK_*` setting contains credentials, private paths, or hostnames.
+
+## Safety notes
+
+SimpleQuery is a query-building library, not an authorization or SQL-injection protection layer. It exposes both parameterized condition helpers and raw SQL escape hatches; choose the narrowest API that fits the value source.
+
+Recommended usage:
+
+- Prefer hash, Arel, or placeholder conditions for values derived from users or external systems.
+- Treat raw SQL strings in `select`, `where`, and `custom_aggregation` as trusted-only escape hatches.
+- Keep `group_concat` separators static and trusted; they are interpolated into database-specific SQL.
+- `having` accepts the same condition styles as `where`; raw strings are trusted-only there too.
+- Keep tenant, authorization, and visibility constraints explicit in your query code.
+- Remember that `bulk_update` bypasses model callbacks and validations, like any direct SQL update.
+
+### Parameterized values
 
---- AR find_each Memory Report ---
-Total allocated: 1.98 GB (16,001,659 objects)
-Retained:        ~2 KB
+Use hash conditions for simple equality predicates and array placeholder conditions for SQL fragments that include external values:
 
---- SimpleQuery stream_each Memory Report ---
-Total allocated: 1.38 GB (8,000,211 objects)
-Retained:        ~3 KB
+```ruby
+# Equality predicates are built through Arel.
+User.simple_query.where(email: params[:email]).execute
+
+# SQL fragments with external values should use ActiveRecord-style placeholders.
+query = params[:query].to_s
+escaped_query = ActiveRecord::Base.sanitize_sql_like(query)
+
+User.simple_query
+    .where(["name ILIKE ?", "%#{escaped_query}%"])
+    .execute
+
+User.simple_query
+    .where(["email = :email", { email: params[:email] }])
+    .execute
 ```
-- **Struct-based** approach remains the fastest, skipping model overhead.
-- **Read model** approach is still significantly faster than standard ActiveRecord while allowing domain-specific logic.
 
-### MySQL (1,000,000 records)
+Placeholders quote values as SQL data literals, while `sanitize_sql_like` makes `%` and `_` match literally in `LIKE` patterns; escaping the pattern does not replace placeholder quoting.
+
+Do not interpolate external values into raw strings:
+
+```ruby
+# Unsafe: params[:query] is part of the SQL string itself.
+User.simple_query.where("name ILIKE '%#{params[:query]}%'").execute
 ```
-🚀 Performance Results (1000,000 records):
-ActiveRecord Query:                  10.45833 seconds
-SimpleQuery Execution (Struct):      3.04655 seconds
-SimpleQuery Execution (Read model):  3.69052 seconds
 
-----------------------------------------------------
-ActiveRecord find_each:              5.04671 seconds
-SimpleQuery stream_each:             2.96602 seconds
+### Trusted SQL escape hatches
+
+Some APIs intentionally accept SQL fragments because they are meant for expressions that Arel or SimpleQuery helpers do not model:
 
---- AR find_each Memory Report ---
-Total allocated: 1.32 GB (11,001,445 objects)
-Retained:        ~2.7 KB
+```ruby
+# Trusted expression: fixed by the application, not assembled from request input.
+User.simple_query.select("LOWER(email) AS normalized_email").execute
 
---- SimpleQuery stream_each Memory Report ---
-Total allocated: 1.22 GB (8,000,068 objects)
-Retained:        ~3.9 KB
+Company.simple_query
+       .custom_aggregation("COUNT(DISTINCT industry)", "unique_industries")
+       .execute
 ```
-- Even in MySQL, **Struct** was roughly **three times faster** than ActiveRecord’s overhead.
-- Read models still outperform AR, though by a narrower margin in this scenario.
+
+Keep aliases, custom aggregation expressions, raw `select` strings, raw `where` strings, `having` expressions, and `group_concat` separators static or otherwise trusted. If a condition must include external values, express those values with hash, Arel, or placeholder `where` syntax instead of interpolating them into raw SQL fragments.
+
+### Direct updates
+
+`bulk_update` is a set-based SQL update. It is useful for maintenance jobs and data workflows where callbacks are intentionally skipped, but it will not run ActiveRecord validations, callbacks, authorization checks, or per-record business logic. Always add the intended `where` conditions before calling it unless the whole table is the target.
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. 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 repository:
+
+```bash
+bin/setup
+bundle exec rspec
+bundle exec rubocop
+```
+
+Database-sensitive behavior is tested against PostgreSQL and MySQL in CI.
+
+You can also open a console:
+
+```bash
+bin/console
+```
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/kholdrex/simple_query. 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/kholdrex/simple_query/blob/master/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at [kholdrex/simple_query](https://github.com/kholdrex/simple_query). Contributors are expected to follow the [Code of Conduct](CODE_OF_CONDUCT.md).
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+The gem is available as open source under the terms of the [MIT License](LICENSE.txt).
 
 ## Code of Conduct
 
-Everyone interacting in the SimpleQuery project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/kholdrex/simple_query/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the SimpleQuery project's codebases, issue trackers, chat rooms, and mailing lists is expected to follow the [Code of Conduct](CODE_OF_CONDUCT.md).