appquery 0.4.0.rc1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 585ecafd973b1dd9fc8c944b93c64998a8b983438250cbd1ec81317d9e2362d4
-  data.tar.gz: 8197dc68853e7299266a0f8c2dd7fa102bbbf7e743680786bce4c7c2eedcd719
+  metadata.gz: 0ca8349f2df1ddf7e2248314238dd72ff5623d2924f1265f385cb1dfde8b274d
+  data.tar.gz: 12440ed32a10ca28acd01df89175906e2ed2f77105905ed44f905bc54def4c5d
 SHA512:
-  metadata.gz: 37b5baf0f42dbad9ee1f356e0541b5677cb93a934d38ad851931142f79a041337f77cbbd4f56c1e880b4db9140460237afa8627eb0f6f9c73461fc1f6b3843cb
-  data.tar.gz: 3edc3e28e09a648a3d14634beab10cdde1be8d1b31c6c8163fd2f19844fab31a5ecf762ddcef9311f18d1356fe6e2c765f99dd2d08706284c687e94d21c36261
+  metadata.gz: 8154cfbf83c7327cc6bdfbe501430007fb4ed9a5ecfb65f6d751358e3721ca853b9d4655968955147fa2e3aa4ea898db9f71bd3da19647e4e550d2887121daab
+  data.tar.gz: a51fc511fa7b5da2bf03c4d63910abb1bb980b95fc300bf188a8749e726e965d781d14d28ffa3240dbca515c7d2bb0f5e83041eae61bb6ea7e815a1f7a13d19f

data/.irbrc

@@ -17,4 +17,13 @@ IRB.conf[:PROMPT][:APPQUERY] = {
   PROMPT_C: "#{db_indicator}appquery* ",
   RETURN: "=> %s\n"
 }
+
+# copy from history easier as prompt is not repeated across lines
+IRB.conf[:PROMPT][:CLEAN] = {
+  PROMPT_I: ">> ",
+  PROMPT_S: "   ",      # same width as ">> "
+  PROMPT_C: "   ",
+  PROMPT_N: "   ",
+  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/CHANGELOG.md

@@ -1,5 +1,56 @@
 ## [Unreleased]
 
-## [0.1.0] - 2024-10-13
+## [0.5.0] - 2025-12-21
 
-- Initial release
+### 💥 Breaking Changes
+
+- 🔄 **`select:` keyword argument removed** — use positional argument instead
+  ```ruby
+  # before
+  query.select_all(select: "SELECT * FROM :_")
+  # after
+  query.select_all("SELECT * FROM :_")
+  ```
+
+### ✨ Features
+
+- 🍾 **Add paginate ERB-helper**
+  ```ruby
+  SELECT * FROM articles
+    <%= paginate(page: 1, per_page: 15) %>
+  # SELECT * FROM articles LIMIT 15 OFFSET 0
+  ```
+- 🧰 **Resolve query without extension**  
+  `AppQuery[:weekly_sales]` loads `weekly_sales.sql` or `weekly_sales.sql.erb`.
+- 🔗 **Nested result queries** via `with_select` — chain transformations using `:_` placeholder to reference the previous result
+  ```ruby
+  active_users = AppQuery("SELECT * FROM users").with_select("SELECT * FROM :_ WHERE active")
+  active_users.count("SELECT * FROM :_ WHERE admin")
+  ```
+- 🚀 **New methods**: `#column`, `#ids`, `#count`, `#entries` — efficient shortcuts that only fetch what you need
+  ```ruby
+  query.column(:email)  # SELECT email only
+  query.ids             # SELECT id only
+  query.count           # SELECT COUNT(*) only
+  query.entries         # shorthand for select_all.entries
+  ```
+
+### 🐛 Fixes
+
+- 🔧 Fix leading whitespace in `prepend_cte` causing parse errors
+- 🔧 Fix binds being reset when no placeholders found
+- ⚡ `select_one` now uses `LIMIT 1` for better performance
+
+### 📚 Documentation
+
+- 📖 Revised README with cleaner intro and examples
+- 🏠 Added example Rails app in `examples/demo`
+
+## [0.4.0] - 2025-12-15
+
+### 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,68 +1,42 @@
 # 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.  
-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
-  -- app/queries/contracts.sql.erb
-  SELECT * FROM contracts
-  <%= order_by(order) %>
-  ```
-  ```ruby
-  AppQuery["contracts.sql.erb"].render(order: {year: :desc, month: :desc}).select_all
-  ```
-- **...positional and named binds**  
-  Intuitive binds:
-  ```ruby
-  AppQuery(%{select now() - (:interval)::interval as some_date}).select_value(binds: {interval: '1 day'})
-  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
-  ```
-- **...casting**  
-  Automatic and custom casting:
-  ```ruby
-  AppQuery(%{select array[1,2]}).select_value #=> [1,2]
-  cast = {"data" => ActiveRecord::Type::Json.new}
-  AppQuery(%{select '{"a": 1}' as data}).select_value(cast:)
-  ```
-- **...helpers to rewrite a query for introspection during development and testing**  
-  See what a CTE yields: `query.select_all(select: "SELECT * FROM some_cte")`.  
-  Query the end result: `query.select_one(select: "SELECT COUNT(*) FROM _ WHERE ...")`.  
-  Append/prepend CTEs:
-  ```ruby
-  query.prepend_cte(<<~CTE)
-    articles(id, title) AS (
-      VALUES(1, 'Some title'),
-            (2, 'Another article'))
-  CTE
-  ```  
-- **...rspec-helpers**  
-  ```ruby
-  RSpec.describe "AppQuery reports/weekly", type: :query do
-    describe "CTE some_cte" do
-      # see what this CTE yields
-      expect(described_query.select_all(select: "select * from some_cte")).to \
-        include(a_hash_including("id" => 1))
-  
-      # shorter: the query and CTE are derived from the describe-descriptions so this suffices:
-      expect(select_all).to include ...
-  ```
+A Ruby gem for working with raw SQL in Rails. Store queries in `app/queries/`, execute them with proper type casting, and filter/transform results using CTEs.
+
+```ruby
+# Load and execute
+week = AppQuery[:weekly_sales].with_binds(week: 1, year: 2025)
+week.entries
+#=> [{"week" => 2025-01-13, "category" => "Electronics", "revenue" => 12500, "target_met" => true}, ...]
+
+# Filter results (query wraps in CTE, :_ references it)
+week.count("SELECT * FROM :_ WHERE NOT target_met")
+#=> 3
+
+# Extract a column efficiently (only fetches that column)
+week.column(:category)
+#=> ["Electronics", "Clothing", "Home & Garden"]
+
+# Named binds with defaults
+AppQuery[:weekly_sales].select_all(binds: {min_revenue: 5000})
+
+# ERB templating
+AppQuery("SELECT * FROM contracts <%= order_by(ordering) %>")
+  .render(ordering: {year: :desc}).select_all
+
+# Custom type casting
+AppQuery("SELECT metadata FROM products").select_all(cast: {"metadata" => ActiveRecord::Type::Json.new})
+
+# Inspect/mock CTEs for testing
+query.prepend_cte("sales AS (SELECT * FROM mock_data)")
+```
+
+**Highlights**: query files with generator · `select_all`/`select_one`/`select_value`/`count`/`column`/`ids` · query transformation via CTEs · immutable (derive new queries from existing) · named binds · ERB helpers (`order_by`, `paginate`, `values`, `bind`) · automatic + custom type casting · RSpec integration
 
 > [!IMPORTANT]  
-> **Status**: alpha. API might change. See the CHANGELOG for breaking changes when upgrading.
+> **Status**: alpha. API might change. See [the CHANGELOG](./CHANGELOG.md) for breaking changes when upgrading.
 >
 
 ## Rationale
@@ -107,14 +81,23 @@ The prompt indicates what adapter the example uses:
 => "2025-05-10"
 
 # binds
-# positional binds
-[postgresql]> AppQuery(%{select now() - ($1)::interval as date}).select_value(binds: ['2 days'])
-# named binds
+## named binds
 [postgresql]> AppQuery(%{select now() - (:interval)::interval as date}).select_value(binds: {interval: '2 days'})
 
+## not all binds need to be provided (ie they are nil by default) - so defaults can be added in SQL:
+[postgresql]> AppQuery(<<~SQL).select_all(binds: {ts1: 2.day.ago, ts2: Time.now}).column("series")
+  SELECT
+    generate_series(:ts1::timestamp, COALESCE(:ts2, :ts2::timestamp, COALESCE(:interval, '5 minutes')::interval)
+    AS series
+SQL
+
 # casting
-[postgresql]> AppQuery(%{select date('now') as today}).select_all(cast: true).to_a
-=> [{"today" => Sat, 10 May 2025}]
+## Cast values are used by default:
+[postgresql]> AppQuery(%{select date('now')}).select_first
+=> {"today" => Sat, 10 May 2025}
+## compare ActiveRecord
+[postgresql]> ActiveRecord::Base.connection.select_first(%{select date('now') as today})
+=> {"today" => "2025-12-20"}
 
 ## 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)
@@ -137,10 +120,12 @@ casts = {"today" => ActiveRecord::Type::Date.new}
 SQL
 
 ## query the articles-CTE
-[postgresql]> q.select_all(select: %{select * from articles where id < 2}).to_a
+[postgresql]> q.select_all(%{select * from articles where id < 2}).to_a
 
-## query the end-result (available as the CTE named '_')
-[postgresql]> q.select_one(select: %{select * from _ limit 1})
+## query the end-result (available via the placeholder ':_')
+[postgresql]> q.select_one(%{select * from :_ limit 1})
+### shorthand for that
+[postgresql]> q.first
 
 ## ERB templating
 # Extract a query from q that can be sorted dynamically:
@@ -167,7 +152,7 @@ SQL
 ### ...in a Rails project
 
 > [!NOTE]
-> The included [example Rails app](./examples/ror) contains all data and queries described below.
+> The included [example Rails app](./examples/demo) contains all data and queries described below.
 
 Create a query:  
 ```bash
@@ -177,15 +162,15 @@ rails g query recent_articles
 Have some SQL (for SQLite, in this example):
 ```sql
 -- app/queries/recent_articles.sql
-WITH settings(default_min_published_on) as (
-  values(datetime('now', '-6 months'))
+WITH settings(min_published_on) as (
+  values(COALESCE(:since, datetime('now', '-6 months')))
 ),
 
 recent_articles(article_id, article_title, article_published_on, article_url) AS (
   SELECT id, title, published_on, url
   FROM articles
   RIGHT JOIN settings
-  WHERE published_on > COALESCE(?1, settings.default_min_published_on)
+  WHERE published_on > settings.min_published_on
 ),
 
 tags_by_article(article_id, tags) AS (
@@ -204,7 +189,7 @@ JOIN tags_by_article USING(article_id),
 WHERE EXISTS (
   SELECT 1
   FROM json_each(tags)
-  WHERE json_each.value LIKE ?2 OR ?2 IS NULL
+  WHERE json_each.value LIKE :tag OR :tag IS NULL
 )
 GROUP BY recent_articles.article_id
 ORDER BY recent_articles.article_published_on
@@ -251,28 +236,31 @@ 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
+# we can provide a different cut off date via binds:
+AppQuery[:recent_articles].select_all(binds: {since: 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).
-  For Postgres you would always need to provide 2 values, e.g. `binds: [nil, nil]`.
+# NOTE: by default the binds get initialized with nil, e.g. for this example {since: nil, tag: nil}
+# This prevents you from having to provide all binds every time. Default values are put in the SQL (via COALESCE).
 ```
 
-We can also dig deeper by query-ing the result, i.e. the CTE `_`:
+We can also dig deeper by query-ing the result, i.e. the CTE `:_`:
 
 ```ruby
-AppQuery[:recent_articles].select_one(select: "select count(*) as cnt from _")
+AppQuery[:recent_articles].select_one("select count(*) as cnt from :_")
 # => {"cnt" => 13}
 
 # For these kind of aggregate queries, we're only interested in the value:
-AppQuery[:recent_articles].select_value(select: "select count(*) from _")
+AppQuery[:recent_articles].select_value("select count(*) from :_")
 # => 13
+
+# but there's also the shorthand #count (which takes a sub-select):
+AppQuery[:recent_articles].count #=> 13
+AppQuery[:recent_articles].count(binds: {since: 0}) #=> 275
 ```
 
 Use `AppQuery#with_select` to get a new AppQuery-instance with the rewritten SQL:
 ```ruby
-puts AppQuery[:recent_articles].with_select("select * from _")
+puts AppQuery[:recent_articles].with_select("select id from :_")
 ```
 
 
@@ -280,15 +268,15 @@ puts AppQuery[:recent_articles].with_select("select * from _")
 
 You can select from a CTE similarly:
 ```ruby
-AppQuery[:recent_articles].select_all(select: "SELECT * FROM tags_by_article")
+AppQuery[:recent_articles].select_all("SELECT * FROM tags_by_article")
 # => [{"article_id"=>1, "tags"=>"[\"release:pre\",\"release:patch\",\"release:1x\"]"},
       ...]
 
 # NOTE how the tags are json strings. Casting allows us to turn these into proper arrays^1:
 types = {"tags" => ActiveRecord::Type::Json.new}
-AppQuery[:recent_articles].select_all(select: "SELECT * FROM tags_by_article", cast: types)
+AppQuery[:recent_articles].select_all("SELECT * FROM tags_by_article", cast: types)
 
-1) PostgreSQL, unlike SQLite, has json and array types. Just casting suffices:
+1) unlike SQLite, PostgreSQL has json and array types. Just casting suffices:
 AppQuery("select json_build_object('a', 1, 'b', true)").select_one(cast: true)
 # => {"json_build_object"=>{"a"=>1, "b"=>true}}
 ```
@@ -297,7 +285,7 @@ Using the methods `(prepend|append|replace)_cte`, we can rewrite the query beyon
 
 ```ruby
 AppQuery[:recent_articles].replace_cte(<<~SQL).select_all.entries
-settings(default_min_published_on) as (
+settings(min_published_on) as (
   values(datetime('now', '-12 months'))
 )
 SQL
@@ -309,10 +297,10 @@ You could even mock existing tables (using PostgreSQL):
 sample_articles = [{id: 1, title: "Some title", published_on: 3.months.ago},
                    {id: 2, title: "Another title", published_on: 1.months.ago}]
 # show the provided cutoff date works
-AppQuery[:recent_articles].prepend_cte(<<-CTE).select_all(binds: [6.weeks.ago, nil, JSON[sample_articles]).entries
-  articles AS (
-    SELECT * from json_to_recordset($3) AS x(id int, title text, published_on timestamp)
-  )
+AppQuery[:recent_articles].prepend_cte(<<-CTE).select_all(binds: {since: 6.weeks.ago, articles: JSON[sample_articles]}).entries
+articles AS (
+  SELECT * from json_to_recordset(:articles) AS x(id int, title text, published_on timestamp)
+)
 CTE
 ```
 
@@ -332,7 +320,7 @@ require "rails_helper"
 RSpec.describe "AppQuery reports/weekly", type: :query, default_binds: [] do
   describe "CTE articles" do
     specify do
-      expect(described_query.select_all(select: "select * from :cte")).to \
+      expect(described_query.select_all("select * from :cte")).to \
         include(a_hash_including("article_id" => 1))
 
       # short version: query, cte and select are all implied from descriptions
@@ -350,225 +338,10 @@ There's some sugar:
   When doing `select_all`, you can rewrite the `SELECT` of the query by passing `select`. There's no need to use the full name of the CTE as the spec-description contains the name (i.e. "articles" in "CTE articles").
 - default_binds  
   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>
-
-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) ...`.
+## API Documentation
 
-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