appquery 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 10872e5424d3f5853f5317384cd44927241c74ac6f1df8ba41f925796384816b
-  data.tar.gz: eaa746cb1b2c7b2a48058ae1ceb1374245b6a197fab801411d0d602f4f58e7e2
+  metadata.gz: c63ba7b9e16d2f5b7071f8dd9203695f3c46b956d0302ff27a5cab0970cc598f
+  data.tar.gz: 71bebdc43197fce0e8917a3e6f4be0615bcb28215ef004b2496ce0554241c54d
 SHA512:
-  metadata.gz: 8a11faf4af63d87413ccfd28e2224ad230e2e451cdf3518302c4faaf2df0594118f7d2ac99fa57d65a75feb52163780088038e9748ffeb2212b41cc4505ae0a3
-  data.tar.gz: 7a6e4c0337a2fff23f845b04878994f162f7c49b5e9d981f1713cd5d0c490d8b0ea226871a92d754b3a4a5cc0e0b873217d650ec9d9f52ba79a0cfc257d24acc
+  metadata.gz: 4f372fb1b1e524e05a2cdf5338d1114f76e08df3b2ec2028e9ec42b515dcbfe4c4c6d9d318a367351e884cfc3ed8e0c670f215d2ccdb072753271fa248993eed
+  data.tar.gz: d91262c52aac1d7cb753eab122c2fbf7d352bd160f5112e3139cf1b5bda848e05456644d3e8e37b2c038ba0795fcfe707470c5bb903cc05e0d0d81a30725de80

data/.envrc

@@ -1 +1,6 @@
-PATH_add bin
+# direnv config
+PATH_add bin
+
+export APP_ROOT=$(pwd)
+
+source_env_if_exists .envrc.private

data/.envrc.private.example

@@ -0,0 +1,2 @@
+# copy this to .envrc.private to use with direnv
+export PG_DATABASE_URL=postgres://localhost:5432/some_db

data/.standard.yml

@@ -1,3 +1,5 @@
 # For available configuration options, see:
 #   https://github.com/standardrb/standard
-ruby_version: 3.0
+ruby_version: 3.1
+ignore:
+  - 'examples/**/*'

data/README.md

@@ -1,32 +1,478 @@
-# Appquery
+# AppQuery - raw SQL 🥦, cooked :stew:
 
-TODO: Delete this and the text below, and describe your gem
+[![Gem Version](https://badge.fury.io/rb/appquery.svg)](https://badge.fury.io/rb/appquery)
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/appquery`. To experiment with that code, run `bin/console` for an interactive prompt.
+A Rubygem :gem: that makes working with raw SQL 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
+  ```
+- **...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 ...
+  ```
 
-## Installation
+> [!IMPORTANT]  
+> **Status**: alpha. API might change. See the CHANGELOG for breaking changes when upgrading.
+>  
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+## Installation
 
 Install the gem and add to the application's Gemfile by executing:
 
 ```bash
-bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+bundle add appquery
 ```
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+## Usage
+
+> [!NOTE]
+> The following (trivial) examples are not meant to convince you to ditch your ORM, but just to show how this gem handles raw SQL queries.
+
+### Create
 
+> [!NOTE]
+> The included [example Rails app](./examples/ror) contains all data and queries described below.
+
+Create a query:  
 ```bash
-gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+rails g query recent_articles
 ```
 
-## Usage
+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'))
+),
+
+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)
+),
+
+tags_by_article(article_id, tags) AS (
+  SELECT articles_tags.article_id,
+    json_group_array(tags.name) AS tags
+  FROM articles_tags
+  JOIN tags ON articles_tags.tag_id = tags.id
+  GROUP BY articles_tags.article_id
+)
+
+SELECT recent_articles.*,
+       group_concat(json_each.value, ',' ORDER BY value ASC) tags_str
+FROM recent_articles
+JOIN tags_by_article USING(article_id),
+  json_each(tags)
+WHERE EXISTS (
+  SELECT 1
+  FROM json_each(tags)
+  WHERE json_each.value LIKE ?2 OR ?2 IS NULL
+)
+GROUP BY recent_articles.article_id
+ORDER BY recent_articles.article_published_on
+```
+
+The result would look like this:
+
+```ruby
+[{"article_id"=>292,
+ "article_title"=>"Rails Versions 7.0.8.2, and 7.1.3.3 have been released!",
+ "article_published_on"=>"2024-05-17",
+ "article_url"=>"https://rubyonrails.org/2024/5/17/Rails-Versions-7-0-8-2-and-7-1-3-3-have-been-released",
+ "tags_str"=>"release:7x,release:revision"},
+...
+]
+```
+
+Even for this fairly trivial query, there's already quite some things 'encoded' that we might want to verify or capture in tests:
+- only certain columns
+- only published articles
+- only articles _with_ tags
+- only articles published after some date
+  - either provided or using the default
+- articles are sorted in a certain order
+- tags appear in a certain order and are formatted a certain way
+
+Using the SQL-rewriting capabilities shown below, this library allows you to express these assertions in tests or verify them during development.
+
+### Verify query results
+
+> [!NOTE]
+> There's `AppQuery#select_all`, `AppQuery#select_one` and `AppQuery#select_value` to execute a query. `select_(all|one)` are tiny wrappers around the equivalent methods from `ActiveRecord::Base.connection`.  
+> Instead of [positional arguments](https://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/DatabaseStatements.html#method-i-select_all), these methods accept keywords `select`, `binds` and `cast`. See below for examples.
+
+Given the query above, you can get the result like so:
+```ruby
+AppQuery[:recent_articles].select_all.entries
+# =>
+[{"article_id"=>292,
+ "article_title"=>"Rails Versions 7.0.8.2, and 7.1.3.3 have been released!",
+ "article_published_on"=>"2024-05-17",
+ "article_url"=>"https://rubyonrails.org/2024/5/17/Rails-Versions-7-0-8-2-and-7-1-3-3-have-been-released",
+ "tags_str"=>"release:7x,release:revision"},
+...
+]
+
+# 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).
+  For Postgres you would always need to provide 2 values, e.g. `binds: [nil, nil]`.
+```
+
+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 _")
+# => {"cnt" => 13}
+
+# For these kind of aggregate queries, we're only interested in the value:
+AppQuery[:recent_articles].select_value(select: "select count(*) from _")
+# => 13
+```
+
+Use `AppQuery#with_select` to get a new AppQuery-instance with the rewritten SQL:
+```ruby
+puts AppQuery[:recent_articles].with_select("select * from _")
+```
+
+
+### Verify CTE results
+
+You can select from a CTE similarly:
+```ruby
+AppQuery[:recent_articles].select_all(select: "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)
+
+1) PostgreSQL, unlike SQLite, 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}}
+```
+
+Using the methods `(prepend|append|replace)_cte`, we can rewrite the query beyond just the select:
+
+```ruby
+AppQuery[:recent_articles].replace_cte(<<~SQL).select_all.entries
+settings(default_min_published_on) as (
+  values(datetime('now', '-12 months'))
+)
+SQL
+```
+
+You could even mock existing tables (using PostgreSQL):
+```ruby
+# using Ruby data:
+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)
+  )
+CTE
+```
+
+Use `AppQuery#with_select` to get a new AppQuery-instance with the rewritten sql:
+```ruby
+puts AppQuery[:recent_articles].with_select("select * from some_cte")
+```
+
+### Spec
+
+When generating a query `reports/weekly`, a spec-file like below is generated:
+
+```ruby
+# spec/queries/reports/weekly_query_spec.rb
+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 \
+        include(a_hash_including("article_id" => 1))
+
+      # short version: query, cte and select are all implied from descriptions
+      expect(select_all).to include(a_hash_including("article_id" => 1))
+    end
+  end
+end
+```
+
+There's some sugar:
+- `described_query`  
+  ...just like `described_class` in regular class specs.  
+  It's an instance of `AppQuery` based on the last word of the top-description (i.e. "reports/weekly" from "AppQuery reports/weekly").
+- `:cte` placeholder  
+  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>
 
-TODO: Write usage instructions here
+### 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) ...`.
+
+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>
+
+## Compatibility
+
+- 💾 tested with **SQLite** and **PostgreSQL**
+- 🚆 tested with Rails **v6.1**, **v7** and **v8.0**
+- 💎 requires Ruby **>v3.1**  
+  Goal is to support [maintained Ruby versions](https://www.ruby-lang.org/en/downloads/branches/).
 
 ## 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 repo, run `bin/setup` to install dependencies. **Make sure to check it exits with status code 0.**
+
+Using [direnv](https://direnv.net/) for env-vars recommended.
+
+
+Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
 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 the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
@@ -37,3 +483,4 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/eval/a
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+

data/lib/app_query/rspec/helpers.rb

@@ -0,0 +1,90 @@
+module AppQuery
+  module RSpec
+    module Helpers
+      def default_binds
+        self.class.default_binds
+      end
+
+      def expand_select(s)
+        s.gsub(":cte", cte_name)
+      end
+
+      def select_all(select: nil, binds: default_binds, **kws)
+        @query_result = described_query(select:).select_all(binds:, **kws)
+      end
+
+      def select_one(select: nil, binds: default_binds, **kws)
+        @query_result = described_query(select:).select_one(binds:, **kws)
+      end
+
+      def select_value(select: nil, binds: default_binds, **kws)
+        @query_result = described_query(select:).select_value(binds:, **kws)
+      end
+
+      def described_query(select: nil)
+        select ||= "SELECT * FROM :cte" if cte_name
+        select &&= expand_select(select) if cte_name
+        self.class.described_query.with_select(select)
+      end
+
+      def cte_name
+        self.class.cte_name
+      end
+
+      def query_name
+        self.class.query_name
+      end
+
+      def query_result
+        @query_result
+      end
+
+      module ClassMethods
+        def described_query
+          AppQuery[query_name]
+        end
+
+        def metadatas
+          scope = is_a?(Class) ? self : self.class
+          metahash = scope.metadata
+          result = []
+          loop do
+            result << metahash
+            metahash = metahash[:parent_example_group]
+            break unless metahash
+          end
+          result
+        end
+
+        def descriptions
+          metadatas.map { _1[:description] }
+        end
+
+        def query_name
+          descriptions.find { _1[/(app)?query\s/i] }&.then { _1.split.last }
+        end
+
+        def cte_name
+          descriptions.find { _1[/cte\s/i] }&.then { _1.split.last }
+        end
+
+        def default_binds
+          metadatas.find { _1[:default_binds] }&.[](:default_binds) || []
+        end
+
+        def included(klass)
+          super
+          # Inject classmethods into the group.
+          klass.extend(ClassMethods)
+          # If the describe block is aimed at string or resource/provider class
+          # then set the default subject to be the Chef run.
+          # if klass.described_class.nil? || klass.described_class.is_a?(Class) && (klass.described_class < Chef::Resource || klass.described_class < Chef::Provider)
+          #  klass.subject { chef_run }
+          # end
+        end
+      end
+
+      extend ClassMethods
+    end
+  end
+end

data/lib/app_query/rspec.rb

@@ -0,0 +1,5 @@
+require_relative "rspec/helpers"
+
+RSpec.configure do |config|
+  config.include AppQuery::RSpec::Helpers, type: :query
+end