appquery 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 64e74167bbafa7217db5f9c0bab6efc8b55655abbbcb7e2fccefca3dfe1afae8
-  data.tar.gz: 16f6870106206b547ed307fb6cbcd8d9250610239ccf9dc046e6e6c9719d76dd
+  metadata.gz: e96dbd6cf521caaee6d919ee3dd7fc796bb92f48ef3e135271b8b82408fb6bcc
+  data.tar.gz: 0c2250d2a62773ae26ff79469ea6b7e0a63ac246f2824518495a0f4f2ef2b13c
 SHA512:
-  metadata.gz: 74ce3c5a8d22b2b41bc477069e9720c7b91cad52909ee3e4db8533c0a6f357227ec7e9485f513b8306a0d4994b53556971ae09284c72c2c5370bee45a0c244e3
-  data.tar.gz: 61b01b05753f3a6f27194e47b40bb91aa822c5c263dbe78d0328f1b09aad02d95acbfc7ba191d4fb773b536c1b1ad03465e05c87c4ecf1dc279ed3e461ba97b2
+  metadata.gz: 14e0146910530087f2c56478e5c507a74ad9b6ccfea81a5c52e46fe24c07f4ef232db86056e1b97c7b7ed9ac976543b8e9c0ac4fcfcc90805aa9d668b426e061
+  data.tar.gz: 21e8afa59badf98018ba334960b3a6f301511a84305ea4941627f9d9dce3a1b24a23e52201c2a14f0a8912efbdaf9da1742b010acc364ceb72560a7910cab8e2

data/.irbrc

@@ -0,0 +1,20 @@
+puts "Loading #{__FILE__}"
+# put overrides/additions in '_irbrc'
+
+IRB.conf[:HISTORY_FILE] = "#{ENV["PROJECT_ROOT"]}/tmp/.irb_history"
+
+# Custom IRB prompt showing database adapter
+db_indicator = begin
+  adapter = ActiveRecord::Base.connection.adapter_name.downcase
+  "\e[33m[#{adapter}]\e[0m "
+rescue ActiveRecord::ConnectionNotEstablished, NameError
+  "\e[34m[no-db]\e[0m "
+end
+
+IRB.conf[:PROMPT][:APPQUERY] = {
+  PROMPT_I: "#{db_indicator}appquery> ",
+  PROMPT_S: "#{db_indicator}appquery%l ",
+  PROMPT_C: "#{db_indicator}appquery* ",
+  RETURN: "=> %s\n"
+}
+IRB.conf[:PROMPT_MODE] = :APPQUERY

data/.yardopts

@@ -0,0 +1,11 @@
+--readme README.md
+--markup markdown
+--no-private
+--output-dir doc
+--exclude tmp/
+--exclude spec/
+--exclude examples/
+--exclude gemfiles/
+lib/**/*.rb
+- LICENSE.txt
+- CHANGELOG.md

data/Appraisals

@@ -1,15 +1,25 @@
 appraise "rails-70" do
-  gem "rails", "~> 7.0"
+  gem "rails", "~> 7.0.0"
+  gem "sqlite3", "~> 1.4"
 end
 
 appraise "rails-71" do
-  gem "rails", "~> 7.1"
+  gem "rails", "~> 7.1.0"
 end
 
 appraise "rails-72" do
-  gem "rails", "~> 7.2"
+  gem "rails", "~> 7.2.0"
 end
 
 appraise "rails-80" do
-  gem "rails", "~> 8.0"
+  gem "rails", "~> 8.0.0"
+end
+
+appraise "rails-81" do
+  gem "rails", "~> 8.1.0"
+end
+
+appraise "rails-head" do
+  gem "activerecord", github: "rails/rails"
+  gem "rails", github: "rails/rails"
 end

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 ## [Unreleased]
 
-## [0.1.0] - 2024-10-13
+## [0.4.0] - 2025-12-15
 
-- Initial release
+### features
+
+- add insert, update and delete
+- API docs at [eval.github.io/appquery](https://eval.github.io/appquery)
+- add ERB-helpers [values, bind and quote ](https://eval.github.io/appquery/AppQuery/RenderHelpers.html).
+- enabled trusted publishing to rubygems.org

data/README.md

@@ -1,18 +1,13 @@
 # AppQuery - raw SQL 🥦, cooked :stew:
 
 [![Gem Version](https://badge.fury.io/rb/appquery.svg)](https://badge.fury.io/rb/appquery)
+[![API Docs](https://img.shields.io/badge/API_Docs-YARD-blue.svg)](https://eval.github.io/appquery/)
 
-A Rubygem :gem: that makes working with raw SQL (READ) queries in Rails projects more convenient.  
+A Rubygem :gem: that makes working with raw SQL queries in Rails projects convenient.  
 Specifically it provides:
 - **...a dedicated folder for queries**  
   e.g. `app/queries/reports/weekly.sql` is instantiated via `AppQuery["reports/weekly"]`.
-- **...Rails/rspec generators**  
-  ```
-  $ rails generate query reports/weekly
-    create  app/queries/reports/weekly.sql
-    invoke  rspec
-    create    spec/queries/reports/weekly_query_spec.rb
-  ```
+
 - **...ERB templating**  
   Simple ERB templating with helper-functions:
   ```sql
@@ -26,7 +21,9 @@ Specifically it provides:
 - **...positional and named binds**  
   Intuitive binds:
   ```ruby
-  AppQuery(%{select now() - (:interval)::interval as some_date}).select_value(binds: {interval: '1 day'})
+  AppQuery(<<~SQL).select_value(binds: {interval: '1 day'})
+    select now() - (:interval)::interval as some_date
+  SQL
   AppQuery(<<~SQL).select_all(binds: [2.day.ago, Time.now, '5 minutes']).column("series")
     select generate_series($1::timestamp, $2::timestamp, $3::interval) as series
   SQL
@@ -48,8 +45,8 @@ Specifically it provides:
       VALUES(1, 'Some title'),
             (2, 'Another article'))
   CTE
-  ```  
-- **...rspec-helpers**  
+  ```
+- **...rspec generators and helpers**  
   ```ruby
   RSpec.describe "AppQuery reports/weekly", type: :query do
     describe "CTE some_cte" do
@@ -95,60 +92,65 @@ Testdriving can be easily done from the console. Either by cloning this reposito
   ```
 </details>
 
-The following examples assume PostgreSQL (SQLite where stated):
+The prompt indicates what adapter the example uses:
 
 ```ruby
 # showing select_(all|one|value)
-> AppQuery(%{select date('now') as today}).select_all.to_a
+[postgresql]> AppQuery(%{select date('now') as today}).select_all.to_a
 => [{"today" => "2025-05-10"}]
-> AppQuery(%{select date('now') as today}).select_one
+[postgresql]> AppQuery(%{select date('now') as today}).select_one
 => {"today" => "2025-05-10"}
-> AppQuery(%{select date('now') as today}).select_value
+[postgresql]> AppQuery(%{select date('now') as today}).select_value
 => "2025-05-10"
 
 # binds
 # positional binds
-> AppQuery(%{select now() - ($1)::interval as date}).select_value(binds: ['2 days'])
+[postgresql]> AppQuery(%{select now() - ($1)::interval as date}).select_value(binds: ['2 days'])
 # named binds
-> AppQuery(%{select now() - (:interval)::interval as date}).select_value(binds: {interval: '2 days'})
+[postgresql]> AppQuery(%{select now() - (:interval)::interval as date}).select_value(binds: {interval: '2 days'})
 
 # casting
-> AppQuery(%{select date('now') as today}).select_all(cast: true).to_a
+[postgresql]> AppQuery(%{select date('now') as today}).select_all(cast: true).to_a
 => [{"today" => Sat, 10 May 2025}]
 
 ## SQLite doesn't have a notion of dates or timestamp's so casting won't do anything:
-sqlite> AppQuery(%{select date('now') as today}).select_one(cast: true)
+[sqlite]> AppQuery(%{select date('now') as today}).select_one(cast: true)
 => {"today" => "2025-05-12"}
 ## Providing per-column-casts fixes this:
 casts = {"today" => ActiveRecord::Type::Date.new}
-sqlite> AppQuery(%{select date('now') as today}).select_one(cast: casts)
+[sqlite]> AppQuery(%{select date('now') as today}).select_one(cast: casts)
 => {"today" => Mon, 12 May 2025}
 
+
 # rewriting queries (using CTEs)
-q = AppQuery(<<~SQL)
-  WITH articles(id,title,published_on) AS (
-    values(1, 'Some title', '2024-3-31'),
-          (2, 'Other title', '2024-10-31'),
-          (3, 'Same title?', '2024-3-31'))
+[postgresql]> articles = [
+  [1, "Using my new static site generator", 2.months.ago.to_date],
+  [2, "Let's learn SQL", 1.month.ago.to_date],
+  [3, "Another article", 2.weeks.ago.to_date]
+]
+[postgresql]> q = AppQuery(<<~SQL, cast: {"published_on" => ActiveRecord::Type::Date.new}).render(articles:)
+  WITH articles(id,title,published_on) AS (<%= values(articles) %>)
   select * from articles order by id DESC
 SQL
 
 ## query the articles-CTE
-q.select_all(select: %{select * from articles where id < 2}).to_a
+[postgresql]> q.select_all(select: %{select * from articles where id < 2}).to_a
 
 ## query the end-result (available as the CTE named '_')
-q.select_one(select: %{select * from _ limit 1})
+[postgresql]> q.select_one(select: %{select * from _ limit 1})
 
 ## ERB templating
 # Extract a query from q that can be sorted dynamically:
-q2 = q.with_select("select id,title,published_on::date from articles <%= order_by(order) %>")
-q2.render(order: {"published_on::date": :desc, 'lower(title)': "asc"}).select_all.entries
+[postgresql]> q2 = q.with_select("select id,title,published_on::date from articles <%= order_by(order) %>")
+[postgresql]> q2.render(order: {"published_on::date": :desc, 'lower(title)': "asc"}).select_all.entries
+
 # shows latest articles first, and titles sorted alphabetically
 # for articles published on the same date.
 # order_by raises when it's passed something that would result in just `ORDER BY`:
-q2.render(order: {})
+[postgresql]> q2.render(order: {})
+
 # doing a select using a query that should be rendered, a `AppQuery::UnrenderedQueryError` will be raised:
-q2.select_all.entries
+[postgresql]> q2.select_all.entries
 
 # NOTE you can use both `order` and `@order`: local variables like `order` are required,
 # while instance variables like `@order` are optional.
@@ -249,7 +251,8 @@ AppQuery[:recent_articles].select_all.entries
 # we can provide a different cut off date via binds^1:
 AppQuery[:recent_articles].select_all(binds: [1.month.ago]).entries
 
-1) note that SQLite can deal with unbound parameters, i.e. when no binds are provided it assumes null for $1 and $2 (which our query can deal with).
+1) note that SQLite can deal with unbound parameters, i.e. when no binds are provided it assumes null for
+  $1 and $2 (which our query can deal with).
   For Postgres you would always need to provide 2 values, e.g. `binds: [nil, nil]`.
 ```
 
@@ -346,229 +349,15 @@ There's some sugar:
   The `binds`-value used when not explicitly provided.  
   E.g. given a query with a where-clause `WHERE published_at > COALESCE($1::timestamp, NOW() - '3 month'::interval)`, when setting `defaults_binds: [nil]` then `select_all` works like `select_all(binds: [nil])`.
 
-## 💎 API Doc 💎
-
-### generic
-
-<details>
-  <summary><code>AppQuery(sql) ⇒ AppQuery::Q</code></summary>
-  
-  ### Examples
-  
-  ```ruby
-  AppQuery("some sql")
-  ```
-</details>
-
-### module AppQuery
-
-<details>
-<summary><code>AppQuery[query_name] ⇒ AppQuery::Q</code></summary>
-
-### Examples
-
-```ruby
-AppQuery[:recent_articles]
-AppQuery["export/articles"]
-```
-
-</details>
-
-<details>
-<summary><code>AppQuery.configure {|Configuration| ... } ⇒ void </code></summary>
-
-Configure AppQuery.
-
-### Examples
-
-```ruby
-AppQuery.configure do |cfg|
-  cfg.query_path = "db/queries" # default: "app/queries"
-end
-```
-
-</details>
-
-<details>
-<summary><code>AppQuery.configuration ⇒ AppQuery::Configuration </code></summary>
-
-Get configuration
-
-### Examples
-
-```ruby
-AppQuery.configure do |cfg|
-  cfg.query_path = "db/queries" # default: "app/queries"
-end
-AppQuery.configuration
-```
-
-</details>
-
-### class AppQuery::Q
-
-Instantiate via `AppQuery(sql)` or `AppQuery[:query_file]`.
-
-<details>
-<summary><code>AppQuery::Q#cte_names ⇒ [Array< String >] </code></summary>
-
-Returns names of CTEs in query.
-
-### Examples
-
-```ruby
-AppQuery("select * from articles").cte_names # => []
-AppQuery("with foo as(select 1) select * from foo").cte_names # => ["foo"]
-```
-
-</details>
-
-<details>
-<summary><code>AppQuery::Q#recursive? ⇒ Boolean </code></summary>
-
-Returns whether or not the WITH-clause is recursive or not.
-
-### Examples
-
-```ruby
-AppQuery("select * from articles").recursive? # => false
-AppQuery("with recursive foo as(select 1) select * from foo") # => true
-```
-
-</details>
-
-<details>
-<summary><code>AppQuery::Q#select ⇒ String </code></summary>
+## API Documentation
 
-Returns select-part of the query. When using CTEs, this will be `<select>` in a query like `with foo as (select 1) <select>`.
-
-### Examples
-
-```ruby
-AppQuery("select * from articles") # => "select * from articles"
-AppQuery("with foo as(select 1) select * from foo") # => "select * from foo"
-```
-
-</details>
-
-#### query execution
-
-<details>
-<summary><code>AppQuery::Q#select_all(select: nil, binds: [], cast: false) ⇒ AppQuery::Result</code></summary>
-
-`select` replaces the existing select. The existing select is wrapped in a CTE named `_`.  
-`binds` array with values for any (positional) placeholder in the query.  
-`cast` boolean or `Hash` indicating whether or not (and how) to cast. E.g. `{"some_column" => ActiveRecord::Type::Date.new}`.
-
-### Examples
-
-```ruby
-# SQLite
-aq = AppQuery(<<~SQL)
-with data(id, title) as (
-  values('1', 'Some title'),
-     ('2', 'Another title')
-)
-select * from data
-where id=?1 or ?1 is null
-SQL
-
-# selecting from the select
-aq.select_all(select: "select * from _ where id > 1").entries #=> [{...}]
-
-# selecting from a CTE
-aq.select_all(select: "select id from data").entries
-
-# casting
-aq.select_all(select: "select id from data", cast: {"id" => ActiveRecord::Type::Integer.new})
-
-# binds
-aq.select_all(binds: ['2'])
-```
-
-</details>
-
-<details>
-<summary><code>AppQuery::Q#select_one(select: nil, binds: [], cast: false) ⇒ AppQuery::Result </code></summary>
-
-First result from `AppQuery::Q#select_all`.
-
-See examples from `AppQuery::Q#select_all`.
-
-</details>
-
-<details>
-<summary><code>AppQuery::Q#select_value(select: nil, binds: [], cast: false) ⇒ AppQuery::Result </code></summary>
-
-First value from `AppQuery::Q#select_one`. Typically for selects like `select count(*) ...`, `select min(article_published_on) ...`.
-
-See examples from `AppQuery::Q#select_all`.
-
-</details>
-
-#### query rewriting
-
-<details>
-<summary><code>AppQuery::Q#with_select(sql) ⇒ AppQuery::Q</code></summary>
-
-Returns new instance with provided select. The existing select is available via CTE `_`.
-
-### Examples
-
-```ruby
-puts AppQuery("select 1").with_select("select 2")
-WITH _ as (
-  select 1
-)
-select 2
-```
-
-</details>
-
-<details>
-<summary><code>AppQuery::Q#prepend_cte(sql) ⇒ AppQuery::Q</code></summary>
-
-Returns new instance with provided CTE.
-
-### Examples
-
-```ruby
-query.prepend_cte("foo as (values(1, 'Some article'))").cte_names # => ["foo", "existing_cte"]
-```
-
-</details>
-
-<details>
-<summary><code>AppQuery::Q#append_cte(sql) ⇒ AppQuery::Q</code></summary>
-
-Returns new instance with provided CTE.
-
-### Examples
-
-```ruby
-query.append_cte("foo as (values(1, 'Some article'))").cte_names # => ["existing_cte", "foo"]
-```
-
-</details>
-
-<details>
-<summary><code>AppQuery::Q#replace_cte(sql) ⇒ AppQuery::Q</code></summary>
-
-Returns new instance with replaced CTE. Raises `ArgumentError` when CTE does not already exist.  
-
-### Examples
-
-```ruby
-query.replace_cte("recent_articles as (select values(1, 'Some article'))")
-```
-
-</details>
+See the [YARD documentation](https://eval.github.io/appquery/) for the full API reference.
 
 ## Compatibility
 
 - 💾 tested with **SQLite** and **PostgreSQL**
-- 🚆 tested with Rails **v6.1**, **v7** and **v8.0**
-- 💎 requires Ruby **>v3.2**  
+- 🚆 tested with Rails v7.x and v8.x (might still work with v6.1, but is no longer included in the test-matrix)
+- 💎 requires Ruby **>=v3.2**  
   Goal is to support [maintained Ruby versions](https://www.ruby-lang.org/en/downloads/branches/).
 
 ## Development
@@ -581,11 +370,14 @@ Using [mise](https://mise.jdx.dev/) for env-vars recommended.
 
 The [console-script](./bin/console) is setup such that it's easy to connect with a database and experiment with the library:
 ```bash
-$ ./bin/console sqlite3::memory:
-$ ./bin/console postgres://localhost:5432/some_db
+$ bin/console sqlite3::memory:
+$ bin/console postgres://localhost:5432/some_db
 
 # more details
-$ ./bin/console -h
+$ bin/console -h
+
+# when needing an appraisal, use bin/run (this ensures signals are handled correctly):
+$ bin/run rails_head console
 ```
 
 ### various

data/lib/app_query/render_helpers.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+module AppQuery
+  # Provides helper methods for rendering SQL templates in ERB.
+  #
+  # These helpers are available within ERB templates when using {Q#render}.
+  # They provide safe SQL construction with parameterized queries.
+  #
+  # @note These methods require +@collected_binds+ (Hash) and
+  #   +@placeholder_counter+ (Integer) instance variables to be initialized
+  #   in the including context.
+  #
+  # @example Basic usage in an ERB template
+  #   SELECT * FROM users WHERE name = <%= bind(name) %>
+  #   <%= order_by(sorting) %>
+  #
+  # @see Q#render
+  module RenderHelpers
+    # Quotes a value for safe inclusion in SQL using ActiveRecord's quoting.
+    #
+    # Use this helper when you need to embed a literal value directly in SQL
+    # rather than using a bind parameter. This is useful for values that need
+    # to be visible in the SQL string itself.
+    #
+    # @param value [Object] the value to quote (typically a String or Number)
+    # @return [String] the SQL-safe quoted value
+    #
+    # @example Quoting a string with special characters
+    #   quote("Let's learn SQL!") #=> "'Let''s learn SQL!'"
+    #
+    # @example In an ERB template
+    #   INSERT INTO articles (title) VALUES(<%= quote(title) %>)
+    #
+    # @note Prefer {#bind} for parameterized queries when possible, as it
+    #   provides better security and query plan caching.
+    #
+    # @see #bind
+    def quote(value)
+      ActiveRecord::Base.connection.quote(value)
+    end
+
+    # Creates a named bind parameter placeholder and collects the value.
+    #
+    # This is the preferred way to include dynamic values in SQL queries.
+    # The value is collected internally and a placeholder (e.g., +:b1+) is
+    # returned for insertion into the SQL template.
+    #
+    # @param value [Object] the value to bind (any type supported by ActiveRecord)
+    # @return [String] the placeholder string (e.g., ":b1", ":b2", etc.)
+    #
+    # @example Basic bind usage
+    #   bind("Some title") #=> ":b1" (with "Some title" added to collected binds)
+    #
+    # @example In an ERB template
+    #   SELECT * FROM videos WHERE title = <%= bind(title) %>
+    #   # Results in: SELECT * FROM videos WHERE title = :b1
+    #   # With binds: {b1: <value of title>}
+    #
+    # @example Multiple binds
+    #   SELECT * FROM t WHERE a = <%= bind(val1) %> AND b = <%= bind(val2) %>
+    #   # Results in: SELECT * FROM t WHERE a = :b1 AND b = :b2
+    #
+    # @see #values for binding multiple values in a VALUES clause
+    # @see #quote for embedding quoted literals directly
+    def bind(value)
+      collect_bind(value)
+    end
+
+    # Generates a SQL VALUES clause from a collection with automatic bind parameters.
+    #
+    # Supports three input formats:
+    # 1. *Array of Arrays* - Simple row data without column names
+    # 2. *Array of Hashes* - Row data with automatic column name extraction
+    # 3. *Collection with block* - Custom value transformation per row
+    #
+    # @param coll [Array<Array>, Array<Hash>] the collection of row data
+    # @param skip_columns [Boolean] when true, omits the column name list
+    #   (useful for UNION ALL or CTEs where column names are defined elsewhere)
+    # @yield [item] optional block to transform each item into an array of SQL expressions
+    # @yieldparam item [Object] each item from the collection
+    # @yieldreturn [Array<String>] array of SQL expressions for the row values
+    # @return [String] the complete VALUES clause SQL fragment
+    #
+    # @example Array of arrays (simplest form)
+    #   values([[1, "Title A"], [2, "Title B"]])
+    #   #=> "VALUES (:b1, :b2),\n(:b3, :b4)"
+    #   # binds: {b1: 1, b2: "Title A", b3: 2, b4: "Title B"}
+    #
+    # @example Array of hashes (with automatic column names)
+    #   values([{id: 1, title: "Video A"}, {id: 2, title: "Video B"}])
+    #   #=> "(id, title) VALUES (:b1, :b2),\n(:b3, :b4)"
+    #
+    # @example Hashes with mixed keys (NULL for missing values)
+    #   values([{title: "A"}, {title: "B", published_on: "2024-01-01"}])
+    #   #=> "(title, published_on) VALUES (:b1, NULL),\n(:b2, :b3)"
+    #
+    # @example Skip columns for UNION ALL
+    #   SELECT id FROM articles UNION ALL <%= values([{id: 1}], skip_columns: true) %>
+    #   #=> "SELECT id FROM articles UNION ALL VALUES (:b1)"
+    #
+    # @example With block for custom expressions
+    #   values(videos) { |v| [bind(v[:id]), quote(v[:title]), 'now()'] }
+    #   #=> "VALUES (:b1, 'Escaped Title', now()), (:b2, 'Other', now())"
+    #
+    # @example In a CTE
+    #   WITH articles(id, title) AS (<%= values(data) %>)
+    #   SELECT * FROM articles
+    #
+    # @see #bind for individual value binding
+    # @see #quote for quoting literal values
+    #
+    # TODO: Add types: parameter to cast bind placeholders (needed for UNION ALL
+    #   where PG can't infer types). E.g. values([[1]], types: [:integer])
+    #   would generate VALUES (:b1::integer)
+    def values(coll, skip_columns: false, &block)
+      first = coll.first
+
+      # For hash collections, collect all unique keys
+      if first.is_a?(Hash) && !block
+        all_keys = coll.flat_map(&:keys).uniq
+
+        rows = coll.map do |row|
+          vals = all_keys.map { |k| row.key?(k) ? collect_bind(row[k]) : "NULL" }
+          "(#{vals.join(", ")})"
+        end
+
+        columns = skip_columns ? "" : "(#{all_keys.join(", ")}) "
+        "#{columns}VALUES #{rows.join(",\n")}"
+      else
+        # Arrays or block - current behavior
+        rows = coll.map do |item|
+          vals = if block
+            block.call(item)
+          elsif item.is_a?(Array)
+            item.map { |v| collect_bind(v) }
+          else
+            [collect_bind(item)]
+          end
+          "(#{vals.join(", ")})"
+        end
+        "VALUES #{rows.join(",\n")}"
+      end
+    end
+
+    # Generates an ORDER BY clause from a hash of column directions.
+    #
+    # Converts a hash of column names and sort directions into a valid
+    # SQL ORDER BY clause.
+    #
+    # @param hash [Hash{Symbol, String => Symbol, String, nil}] column names mapped to
+    #   sort directions (+:asc+, +:desc+, +"ASC"+, +"DESC"+) or nil for default
+    # @return [String] the complete ORDER BY clause
+    #
+    # @example Basic ordering
+    #   order_by(year: :desc, month: :desc)
+    #   #=> "ORDER BY year DESC, month DESC"
+    #
+    # @example Mixed directions
+    #   order_by(published_on: :desc, title: :asc)
+    #   #=> "ORDER BY published_on DESC, title ASC"
+    #
+    # @example Column without direction (uses database default)
+    #   order_by(id: nil)
+    #   #=> "ORDER BY id"
+    #
+    # @example In an ERB template with a variable
+    #   SELECT * FROM articles
+    #   <%= order_by(ordering) %>
+    #
+    # @example Making it optional (when ordering may not be provided)
+    #   <%= @ordering.presence && order_by(ordering) %>
+    #
+    # @example With default fallback
+    #   <%= order_by(@order || {id: :desc}) %>
+    #
+    # @raise [ArgumentError] if hash is blank (nil, empty, or not present)
+    #
+    # @note The hash must not be blank. Use conditional ERB for optional ordering.
+    def order_by(hash)
+      raise ArgumentError, "Provide columns to sort by, e.g. order_by(id: :asc)  (got #{hash.inspect})." unless hash.present?
+      "ORDER BY " + hash.map do |k, v|
+        v.nil? ? k : [k, v.upcase].join(" ")
+      end.join(", ")
+    end
+
+    private
+
+    # Collects a value as a bind parameter and returns the placeholder name.
+    #
+    # This is the internal mechanism used by {#bind} and {#values} to
+    # accumulate bind values during template rendering. Each call generates
+    # a unique placeholder name (b1, b2, b3, ...).
+    #
+    # @api private
+    # @param value [Object] the value to collect
+    # @return [String] the placeholder string with colon prefix (e.g., ":b1")
+    def collect_bind(value)
+      @placeholder_counter += 1
+      key = :"b#{@placeholder_counter}"
+      @collected_binds[key] = value
+      ":#{key}"
+    end
+  end
+end