activerecord-refined 0.8.1 → 0.9.0

data/README.md

@@ -26,7 +26,8 @@ Refinements' spec change, that implementation stopped working on Ruby 2.0.0 stab
 the project was left dormant for a long time.
 
 It has now been renamed to **activerecord-refined** and reimplemented on top of
-`Proc#refined`, which will be introduced in Ruby 4.1. `Proc#refined` returns a new proc that
+[`Proc#refined`](https://docs.ruby-lang.org/en/master/Proc.html#method-i-refined),
+which will be introduced in Ruby 4.1. `Proc#refined` returns a new proc that
 is evaluated with the given refinements activated, so a block written by the caller can
 be re-interpreted under the query DSL's refinements:
 
@@ -69,17 +70,20 @@ Just require the gem, and `where`, `select`, `joins`, `left_outer_joins`, `havin
 `order` and `group` will accept a block.
 
 ```ruby
-require 'activerecord-refined'
+require "activerecord-refined"
 ```
 
 Inside the block, symbols denote columns of the receiver's table, and `:table[:column]`
-denotes a qualified column.
+denotes a qualified column. That holds in every position — on the right of a
+comparison too, so `:age == :retirement_age` compares two columns. A value is
+written as its literal, an enum's as its string; a symbol naming no column of
+the model is refused rather than compared against nothing anyone meant.
 
 ### Conditions
 
 ```ruby
 Author.where { :age >= 18 }
-Author.where { :name.like?('A%') }          # LIKE
+Author.where { :name.like?("A%") }          # LIKE
 Author.where { :age.in?(20..40) }           # BETWEEN
 Author.where { :age.between?(20, 40) }      # BETWEEN
 Author.where { :age.in?(18..) }             # >= 18
@@ -94,10 +98,10 @@ block, which is the same rows written the way they would be written by hand:
 Author.where { :country.not_null? }             # IS NOT NULL
 Author.where { :country.not_in?(%w[JP US]) }    # NOT IN
 Author.where { :age.not_between?(20, 40) }      # not between 20 and 40
-Author.where { :name.not_like?('A%') }          # NOT LIKE
-Author.where { :name.not_ilike?('a%') }         # NOT ILIKE / NOT LIKE
+Author.where { :name.not_like?("A%") }          # NOT LIKE
+Author.where { :name.not_ilike?("a%") }         # NOT ILIKE / NOT LIKE
 
-Author.where { !:name.start_with?('A') }        # NOT (name LIKE 'A%')
+Author.where { !:name.start_with?("A") }        # NOT (name LIKE 'A%')
 ```
 
 Nothing turns on the choice: `NOT (country IS NULL)` and `country IS NOT NULL`
@@ -105,6 +109,14 @@ select the same rows, NULLs included. `not_between?` is the one whose SQL
 looks unlike its name — Arel writes it as the two comparisons, `age < 20 OR
 age > 40`, which is again the same rows.
 
+A number compares as itself, the way a bound `?` does: `:age >= 99.5` says
+`>= 99.5`, where `where(age: 99.5..)` casts to the column's type and says
+`>= 99`, letting an age of 99 through a bound it does not satisfy. Everything
+that is not an `Integer`, `Float` or `BigDecimal` keeps the column's own
+serialization — an enum's name, a time's zone, a custom type's scaling — so a
+custom type that scales a number, money kept in cents, is the one place the
+number has to be written as the column stores it.
+
 A boolean column has `true?` and `false?`, which become SQL's `IS TRUE` and
 `IS FALSE`, and the two negations to go with them:
 
@@ -145,7 +157,7 @@ one-row rule: `> any` asks whether the subquery holds a smaller value anywhere,
 `>= all` whether it holds a larger one nowhere.
 
 ```ruby
-Author.where { :age > any(Author.where(country: 'JP').select(:age)) }
+Author.where { :age > any(Author.where(country: "JP").select(:age)) }
 # "authors"."age" > ANY(SELECT "authors"."age" FROM "authors" WHERE ...)
 
 Author.where { :age >= all(Author.select(:age)) }
@@ -178,8 +190,8 @@ case-insensitive equality, folded on both sides rather than left to the
 collation, so it means the same thing everywhere:
 
 ```ruby
-Author.where { :name.ilike?('ma%') }        # ILIKE 'ma%' / LIKE 'ma%'
-Author.where { :name.casecmp?('Alice') }     # LOWER(name) = LOWER('Alice')
+Author.where { :name.ilike?("ma%") }        # ILIKE 'ma%' / LIKE 'ma%'
+Author.where { :name.casecmp?("Alice") }     # LOWER(name) = LOWER('Alice')
 ```
 
 `not_distinct_from?` and `distinct_from?` compare with NULL treated as a
@@ -189,7 +201,7 @@ and MySQL `<=>`, and the rows that come back are the same on all three:
 
 ```ruby
 Author.where { :country.not_distinct_from?(params[:country]) }  # matches NULL to nil
-Author.where { :country.distinct_from?('JP') }                  # keeps the NULL rows
+Author.where { :country.distinct_from?("JP") }                  # keeps the NULL rows
 ```
 
 `start_with?`, `end_with?` and `include?` are shortcuts for the usual `like?`
@@ -197,16 +209,16 @@ patterns. Unlike `like?`, they treat their argument as a literal string, so `%`
 and `_` in it are escaped rather than matched as wildcards:
 
 ```ruby
-Author.where { :name.start_with?('A') }     # LIKE 'A%'
-Author.where { :name.end_with?('son') }     # LIKE '%son'
-Author.where { :name.include?('test') }     # LIKE '%test%'
+Author.where { :name.start_with?("A") }     # LIKE 'A%'
+Author.where { :name.end_with?("son") }     # LIKE '%son'
+Author.where { :name.include?("test") }     # LIKE '%test%'
 ```
 
 Like their String namesakes, `start_with?` and `end_with?` take any number of
 literals; matching any one of them is enough:
 
 ```ruby
-Author.where { :name.start_with?('A', 'B') }
+Author.where { :name.start_with?("A", "B") }
 # (name LIKE 'A%' OR name LIKE 'B%')
 ```
 
@@ -217,7 +229,7 @@ what separates it from `include?`), `superset?` and `subset?` are Set's
 whole-array containment, and `intersect?` is Array's "any element in common":
 
 ```ruby
-Article.where { :tags.member?('ruby') }            # tags @> '{ruby}'
+Article.where { :tags.member?("ruby") }            # tags @> '{ruby}'
 Article.where { :scores.member?(80) }              # scores @> '{80}'
 Article.where { :tags.superset?(%w[ruby rails]) }  # tags @> '{ruby,rails}'
 Article.where { :tags.subset?(%w[ruby rails go]) } # tags <@ '{ruby,rails,go}'
@@ -233,8 +245,8 @@ something `Array#member?` does not. Requiring every element is `superset?`.
 raises there.
 
 ```ruby
-Author.where { :name =~ '^A' }              # REGEXP / ~
-Author.where { :name !~ '^A' }              # NOT REGEXP / !~
+Author.where { :name =~ "^A" }              # REGEXP / ~
+Author.where { :name !~ "^A" }              # NOT REGEXP / !~
 Author.where { :name =~ /son$/ }            # a Regexp literal works too
 ```
 
@@ -267,10 +279,10 @@ parentheses around each comparison necessary, though the `?` methods above need
 none:
 
 ```ruby
-Author.where { (:age >= 18) & ((:country == 'JP') | (:country == 'US')) }
+Author.where { (:age >= 18) & ((:country == "JP") | (:country == "US")) }
 Author.where { !(:age.in?(0..17) | :country.null?) }
 Author.where { !:country.in?(%w[JP US]) }   # NOT (country IN ('JP', 'US'))
-Author.where { !:name.like?('%test%') }     # NOT (name LIKE '%test%')
+Author.where { !:name.like?("%test%") }     # NOT (name LIKE '%test%')
 ```
 
 ### Joins
@@ -360,9 +372,12 @@ Sale.group { cube(:region, :product) }     # GROUP BY CUBE( "region", "product"
 A row that a set did not group by comes back with NULL there, which is also
 what a real NULL looks like; `fn(:grouping, :region)` tells the two apart.
 
-These are PostgreSQL's. SQLite has none of them, and MySQL has only `WITH
-ROLLUP`, which says one of the three and says it elsewhere in the clause, so
-the block raises `NotImplementedError` on both.
+`grouping_sets` and `cube` are PostgreSQL's; SQLite has none of the three and
+both raise `NotImplementedError` elsewhere. `rollup` runs on MySQL and
+MariaDB too, spelled as their `WITH ROLLUP` — which trails the whole group
+list, so there a rollup cannot stand beside other group entries the way
+`ROLLUP(...)` can, and the block says so. MariaDB is also the one that
+refuses `ORDER BY` next to it, and the one without `fn(:grouping, ...)`.
 
 ### Lateral joins
 
@@ -472,7 +487,7 @@ Author.select { count(:*).filter { :age < 50 }.as(:young) }
 # COUNT(*) FILTER (WHERE "age" < 50) AS "young"
 
 Author.select {
-  [count(:*).as(:all), sum(:age).filter { :country == 'JP' }.as(:jp_years)]
+  [count(:*).as(:all), sum(:age).filter { :country == "JP" }.as(:jp_years)]
 }
 ```
 
@@ -528,10 +543,53 @@ Post.select { fn(:format, :amount, 2) }   # MySQL's, on purpose
 written, so a case-sensitive one can be spelled exactly:
 
 ```ruby
-Post.select { fn(:date_trunc, 'day', :created_at).as(:day) }
+Post.select { fn(:date_trunc, "day", :created_at).as(:day) }
 # SELECT date_trunc('day', "posts"."created_at") AS day
 ```
 
+`op` is the same escape hatch for operators — PostgreSQL alone has dozens
+with no method here, `<@` and `&&` and the geometric ones among them. The
+operator is emitted as written and, like `fn`'s names, whether the adapter
+has it is your assertion; it is checked against the characters PostgreSQL
+allows an operator, so a letter, a space or a quote is refused rather than
+written into the SQL. Both sides take what `fn`'s arguments take — a
+column, an expression, a value quoted by the adapter — and a value is
+spelled in the adapter's own syntax, `to_json` saying a document, `'{a,b}'`
+an array; a Ruby Hash or Array is refused rather than guessed at. The
+result is parenthesized, its precedence being unknown, and so is an
+expression on either side, so a dug value cannot be re-grouped out from
+under it:
+
+```ruby
+Post.where { op("&&", :tags, "{ruby,sql}") }
+# WHERE ("posts"."tags" && '{ruby,sql}')
+
+Post.where { op("<@", :meta.dig(:author), { name: "alice" }.to_json) }
+# WHERE (("meta" #> '{author}') <@ '{"name":"alice"}')
+```
+
+`sql` is the last resort, for what neither `fn` nor `op` can spell: the
+statement goes out as written. It is the one way a string means SQL inside a
+block — everywhere else a string is a value — so writing SQL is always asked
+for by name, and an interpolation has a spelling that is not it: `?` and
+`:name` placeholders take values quoted by the adapter, through
+`sanitize_sql_array`. A `?` is rewritten only when there are positional binds
+to put in it, so PostgreSQL's `?` operators can share a statement with named
+binds, or with none. The result carries the predications and arithmetic, and
+is parenthesized where it stands inside a larger expression — its precedence
+is whatever was written — but comes out bare at the top of a select list,
+where parentheses would refuse an alias written into the string:
+
+```ruby
+Post.where { sql("length(title) > ?", 10) }
+# WHERE (length(title) > 10)
+
+Post.where { sql("score + ?", 10) * 2 >= 60 }
+# WHERE (score + 10) * 2 >= 60
+
+Post.select { sql("count(*) FILTER (WHERE score > 0) AS positive") }
+```
+
 Values are quoted by the adapter wherever they appear, as they are in
 Active Record, and so is a column alias. That is what makes the name asked for
 the name that comes back: unquoted, PostgreSQL folds a capital away where the
@@ -584,7 +642,7 @@ raises there:
 Post.where { extract(:year, :created_at) == 2026 }
 # SELECT "posts".* FROM "posts" WHERE EXTRACT(YEAR FROM "posts"."created_at") = 2026
 
-Post.select { cast(:price, 'decimal(10,2)').as(:price) }
+Post.select { cast(:price, "decimal(10,2)").as(:price) }
 # SELECT CAST("posts"."price" AS decimal(10,2)) AS price
 ```
 
@@ -598,6 +656,17 @@ Item.where { :price * :quantity > 1000 }
 Item.select { sum(:price * :quantity).as(:total) }
 ```
 
+The number may stand on the left — only a column or an expression on the
+right builds a query, so Ruby's own arithmetic is untouched — and
+`BigDecimal` is a number here, being what a decimal column's values are,
+quoted as the exact decimal on either side. A `Rational` is refused: no
+decimal spells `1/3r` exactly, and `to_d` is what says the decimal meant.
+
+```ruby
+Item.select { greatest(20 - :quantity, 0).as(:shortfall) }
+Item.where { BigDecimal("1.08") * :price > 500 }
+```
+
 `&`, `|`, `^`, `~`, `<<` and `>>` are SQL's bitwise operators. Between
 conditions `&` and `|` are AND and OR, and that is where they are defined,
 which leaves them free to mean here what SQL means by them:
@@ -648,11 +717,12 @@ number, the others as a negative one, and the bits are the same either way.
 
 One place asks for a value to be said out loud: the top of a select list.
 Everywhere else a bare literal is already a value — `where { :age > 18 }`,
-`concat(:name, '-x')` — but Active Record reads a string in `select` as SQL,
-so `value` is how you ask for the other meaning. It carries the predications
-and arithmetic with it, so a literal can be compared and combined like
-anything else. Numbers have a shorthand, since nothing else could be meant by
-one:
+`concat(:name, '-x')` — but a bare string at the top of the list would be SQL
+to Active Record and a value everywhere else in the block, so it is refused
+rather than read either way: `sql` says the SQL, `value` the value. `value`
+carries the predications and arithmetic with it, so a literal can be compared
+and combined like anything else, and numbers and strings have a shorthand,
+since a literal that has been sent `as` has already said it is a value:
 
 ```ruby
 Node.select { [:id, value(0).as(:depth)] }
@@ -660,14 +730,12 @@ Node.select { [:id, value(0).as(:depth)] }
 
 Node.select { [:id, 0.as(:depth)] }         # the same thing
 
-Post.select { [:title, value('draft').as(:state)] }
+Post.select { [:title, "draft".as(:state)] }
 # SELECT "posts"."title", 'draft' AS state FROM "posts"
 ```
 
-The shorthand is `Integer` and `Float` only. `String` keeps its two meanings —
-SQL in a select list, a value everywhere else — and refining it would make the
-same literal mean one thing or the other depending on whether it had been sent
-a message.
+What the shorthand does not cover, `value` still spells: `value(true)`,
+`value(nil)`, or a literal that goes on to be compared rather than selected.
 
 `CASE` is grammar rather than a function, and has two shapes. With an operand, each `when` is
 something to compare it against; without one, each `when` carries a condition
@@ -676,13 +744,13 @@ reachable through the receiver — `self.case` — and each shape has a shorthan
 that does not need it:
 
 ```ruby
-Author.select { :country.when('JP').then('Japan').else('elsewhere').as(:where) }
+Author.select { :country.when("JP").then("Japan").else("elsewhere").as(:where) }
 # CASE "country" WHEN 'JP' THEN 'Japan' ELSE 'elsewhere' END AS where
 
-Author.select { case_when { :age >= 60 }.then('senior').else('adult').as(:band) }
+Author.select { case_when { :age >= 60 }.then("senior").else("adult").as(:band) }
 # CASE WHEN "age" >= 60 THEN 'senior' ELSE 'adult' END AS band
 
-Author.select { self.case(mod(:age, 10)).when(0).then('round').else('not').as(:v) }
+Author.select { self.case(mod(:age, 10)).when(0).then("round").else("not").as(:v) }
 ```
 
 A `when` takes a value or a block, and so do `then` and `else`; the block is
@@ -694,9 +762,9 @@ something that reaches the database:
 
 ```ruby
 Author.select {
-  case_when { :age < 18 }.then('minor').
-    when { :age >= 60 }.then('senior').
-    else('adult').as(:band)
+  case_when { :age < 18 }.then("minor").
+    when { :age >= 60 }.then("senior").
+    else("adult").as(:band)
 }
 
 Author.select { sum(case_when { :age >= 60 }.then(1).else(0)).as(:seniors) }
@@ -712,10 +780,10 @@ document to be dug into further or asked the JSON questions. `dig_text` gives
 the value as text instead, which is what a comparison wants:
 
 ```ruby
-Post.where { :meta.dig_text(:author, :name) == 'alice' }
+Post.where { :meta.dig_text(:author, :name) == "alice" }
 Post.select { :meta.dig(:author).as(:author) }
 Post.where { :meta.key?(:draft) }
-Post.where { :meta.contains?(status: 'open') }
+Post.where { :meta.contains?(status: "open") }
 ```
 
 No two adapters spell any of this alike, and the block is the same on all
@@ -725,7 +793,7 @@ three:
 | --- | --- | --- | --- |
 | `dig(:a, :b)` | `#> '{a,b}'` | `-> '$.a.b'` | `JSON_EXTRACT(…, '$.a.b')` |
 | `dig_text(:a, :b)` | `#>> '{a,b}'` | `->> '$.a.b'` | `JSON_UNQUOTE(JSON_EXTRACT(…, '$.a.b'))` |
-| `key?(:a)` | `jsonb_exists(…, 'a')` | `json_type(…, '$.a') IS NOT NULL` | `JSON_CONTAINS_PATH(…, 'one', '$.a')` |
+| `key?(:a)` | `? 'a'` | `json_type(…, '$.a') IS NOT NULL` | `JSON_CONTAINS_PATH(…, 'one', '$.a')` |
 | `contains?(…)` | `@>` | — | `JSON_CONTAINS` |
 
 MariaDB answers to the `mysql2` adapter and has none of `->` or `->>`, so the
@@ -736,8 +804,8 @@ value with its type, so a comparison that worked there would fail on the other
 two; a number is compared through a `cast` on all three:
 
 ```ruby
-Post.where { :meta.dig_text(:n) == '5' }
-Post.where { cast(:meta.dig_text(:n), 'integer') > 6 }   # 'signed' on MySQL
+Post.where { :meta.dig_text(:n) == "5" }
+Post.where { cast(:meta.dig_text(:n), "integer") > 6 }   # 'signed' on MySQL
 ```
 
 The type is the adapter's own name for it, here as everywhere `cast` is used.
@@ -748,29 +816,45 @@ as `"true"` on the other two; a JSON `null` is SQL `NULL` everywhere but
 MariaDB, which spells it `"null"`. A key that is not there is `NULL` on all
 three.
 
-Comparing a dug value with anything but a string raises `ArgumentError` rather
-than being left to the adapters, which answer it three ways: `dig_text(:n) ==
-5` is true on SQLite, an error on PostgreSQL and true on MySQL, and
-`dig_text(:flag) == true` is true, an error and false. `cast` is what says
-which type was meant, and then all three agree. `dig` is refused the other way
-about — the JSON for a string carries its quotes, so `dig(:name) == 'alice'`
-is false, an error and true — and `dig_text` is the one that gives the value.
-What `bury` and `except` give back is JSON as `dig`'s is, and is refused the
-same way. A column, a function or another dug value on the right goes through
-untouched; only a Ruby literal is refused. Arithmetic and the bit operators
-are refused outright on both sides — `dig_text(:n) + 1` is 6 on SQLite, an
-error on PostgreSQL and 6.0 on MariaDB — and `cast` settles those too.
+Comparing `dig_text`'s value with anything but a string raises
+`ArgumentError` rather than being left to the adapters, which answer it three
+ways: `dig_text(:n) == 5` is true on SQLite, an error on PostgreSQL and true
+on MySQL, and `dig_text(:flag) == true` is true, an error and false. `cast`
+is what says which type was meant, and then all three agree.
+
+A JSON comparison — `dig`'s side, and `bury`'s and `except`'s — belongs to
+the JSON types: on PostgreSQL's `jsonb` and MySQL's `JSON` alike, numbers
+compare as numbers and documents structurally, key order and spelling aside,
+so a dug value compares with a Ruby one directly. SQLite and MariaDB have
+only the text of each, which is a different question, and raise
+`NotImplementedError` as the SQL is written. `in?` and `between?` are the
+two MySQL leaves out of its JSON comparisons, so there they are spelled as
+the comparisons they mean — the range as its bounds, the list as one
+equality per element, which names the dug value once per element the way
+SQLite's XOR names its operands twice:
+
+```ruby
+Post.where { :meta.dig(:stars) >= 10 }              # PostgreSQL and MySQL
+Post.where { :meta.dig(:author) == { "name" => "alice" } }
+Post.where { :meta.dig(:stars).in?([5, 10]) }
+Post.where { cast(:meta.dig_text(:stars), "integer") >= 10 }   # everywhere
+```
+
+A column, a function or another dug value on the right goes through untouched
+on every adapter. Arithmetic and the bit operators are refused outright on
+both sides — `dig_text(:n) + 1` is 6 on SQLite, an error on PostgreSQL and
+6.0 on MariaDB — and `cast` settles those too.
 
 `bury` sets what `dig` reads: the last argument is the value and the rest are
 the path to it. The document comes back changed rather than being written
 anywhere, so `update_all` is what makes it stick:
 
 ```ruby
-Post.update_all { { meta: :meta.bury(:author, :name, 'alice') } }
+Post.update_all { { meta: :meta.bury(:author, :name, "alice") } }
 # SET "meta" = jsonb_set("meta", '{author,name}', '"alice"')
 # ...          JSON_SET("meta", '$.author.name', 'alice')   elsewhere
 
-Post.update_all { { meta: :meta.bury(:tags, ['ruby', 'sql']) } }
+Post.update_all { { meta: :meta.bury(:tags, ["ruby", "sql"]) } }
 Post.update_all { { meta: :meta.bury(:copy, :meta.dig(:n)) } }
 ```
 
@@ -792,7 +876,7 @@ Post.update_all { { meta: :meta.except(:draft) } }
 # SET "meta" = "meta" - CAST('{"draft"}' AS text[])
 # ...          JSON_REMOVE("meta", '$.draft')   elsewhere
 
-Post.update_all { { meta: :meta.bury(:author, :name, 'alice').except(:tmp) } }
+Post.update_all { { meta: :meta.bury(:author, :name, "alice").except(:tmp) } }
 ```
 
 A key that is not there is not an error, as it is not to `Hash#except`. The
@@ -813,14 +897,14 @@ question asked of a part of the document rather than of all of it:
 
 ```ruby
 Post.where { :meta.dig(:author).key?(:email) }
-Post.where { :meta.dig(:author).dig_text(:name) == 'alice' }
-Post.update_all { { meta: :meta.dig(:author).bury(:name, 'alice') } }
+Post.where { :meta.dig(:author).dig_text(:name) == "alice" }
+Post.update_all { { meta: :meta.dig(:author).bury(:name, "alice") } }
 ```
 
 Containment reads it too, on the adapters that have containment at all:
 
 ```ruby
-Post.where { :meta.dig(:tags).contains?(['ruby']) }
+Post.where { :meta.dig(:tags).contains?(["ruby"]) }
 ```
 
 Asking the same of `dig_text` raises `ArgumentError`: what it gives is text,
@@ -836,6 +920,87 @@ built. On PostgreSQL, `dig` and `dig_text` are all the `json` type carries;
 A key that is not a plain name travels as itself rather than being refused:
 `dig(:'odd key')` becomes `'{odd key}'` or `$."odd key"`.
 
+`keys` gives the keys of the document, as `Hash#keys` does — a JSON array
+of them. Only the MySQL family has a function for it; the other two reach
+the same array through a subquery over their key-listing functions, guarded
+by type so that all four answer alike: the keys of anything that is not an
+object are `NULL` — rather than SQLite's array indices or PostgreSQL's
+error — and the keys of `{}` are `[]` rather than PostgreSQL's `NULL`:
+
+```ruby
+Post.select { :meta.keys.as(:fields) }
+Post.select { :meta.dig(:author).keys.as(:author_fields) }
+# JSON_KEYS("meta")                                              MySQL
+# CASE WHEN jsonb_typeof("meta") = 'object' THEN COALESCE((…))   PostgreSQL
+# CASE WHEN json_type("meta") = 'object' THEN (SELECT …)         SQLite
+```
+
+The order the keys come in is the adapters' own: the JSON types give their
+normalized order and the text ones the stored order — the same divide every
+JSON comparison here rides on.
+
+`json_array` and `json_object` build a document in the row — `json_array`
+from the values given, `json_object` from a Ruby hash. The names are the
+standard's, which SQLite and the MySQL family say as written; PostgreSQL is
+asked to build `jsonb`. A hash rather than SQL's alternating keys and
+values, because a bare symbol means a column in every block here: the keys
+are Ruby's and the values are expressions, so `title: :title` reads the
+column in under its own name with no rule to remember:
+
+```ruby
+Post.select { json_object(title: :title, stars: :meta.dig(:stars)).as(:summary) }
+# jsonb_build_object('title', "title", 'stars', "meta" #> '{stars}')   PostgreSQL
+# JSON_OBJECT('title', "title", 'stars', JSON_EXTRACT(…))              elsewhere
+
+Post.where { :meta.dig(:author) == json_object(name: :name) }
+```
+
+A Ruby value among the arguments goes in as its JSON self — a string or a
+number as themselves, `nil` as `null`, and a boolean or a whole document
+through the same route `bury` takes them, so SQLite's `true` is not its
+`1`. A key that is not a string or a symbol is refused, before the
+adapters answer a NULL key three ways. The empty calls stand —
+`json_array()` is `[]` and `json_object()` is `{}` on all four — and what
+comes back is JSON as `dig`'s is, so the operations and comparisons above
+read it.
+
+`json_arrayagg` and `json_objectagg` gather rows into one JSON document — a
+value from each row into an array, a key and a value into an object. The
+names are the SQL standard's, which the MySQL family says as written;
+PostgreSQL is asked the `jsonb` pair and SQLite its own:
+
+```ruby
+Post.group { :author_id }.select { json_arrayagg(:title).as(:titles) }
+# jsonb_agg("title")          PostgreSQL
+# json_group_array("title")   SQLite
+# JSON_ARRAYAGG("title")      MySQL
+
+Post.select { json_objectagg(:title, :meta.dig(:stars)).as(:stars) }
+
+Post.group { :author_id }.
+  select { json_arrayagg(json_object(title: :title, stars: :meta.dig(:stars))).as(:posts) }
+```
+
+What they give is JSON as `dig`'s is, so it compares the way a dug value
+does, and `filter` and `over` come along as with any aggregate — with two
+refusals where a respelling would change the meaning rather than the
+spelling. The MySQL family has no `FILTER`, and the `CASE` that stands in
+for it elsewhere would leave a JSON `null` in the document for every row it
+drops, so there `filter` raises `NotImplementedError`; MariaDB takes every
+other aggregate as a window function but not these two, so `over` raises
+there too.
+
+The documents agree across adapters, up to the edges of their JSON types.
+Over no rows at all SQLite answers `[]` and `{}` where the others answer
+`NULL`, as their aggregates do. A key aggregated twice keeps the last pair
+on the JSON types — `jsonb` and MySQL's — and every pair on the text ones,
+SQLite and MariaDB, and a `NULL` key is an error on the former pair and a
+dropped pair on the latter. And a bare JSON *column* is text to SQLite's
+`json_group_array`, so it lands as the string that spells the document
+rather than nesting as it does on the other three; a dug value nests
+everywhere, so `json_arrayagg(:meta.dig(:author))` is the portable way to
+collect part of a document.
+
 ### Window functions
 
 `over` gives a function a window, which is what turns an aggregate into a
@@ -994,14 +1159,17 @@ the default; set `ADAPTER` to run the same suite against another one.
 ```sh
 rake test                    # sqlite3
 ADAPTER=postgresql rake test
-ADAPTER=mysql2 rake test
-rake test:all                # all three in turn
+ADAPTER=mysql2 rake test     # MariaDB
+rake test:mysql8             # Oracle's MySQL, on port 3307
+rake test:all                # all of the above; MySQL skipped when 3307 is empty
 ```
 
-PostgreSQL and MySQL are reached on `127.0.0.1` as the current user with no
-password, which is how the devcontainer sets them up. Override with
-`DB_HOST`, `DB_USERNAME` and `DB_PASSWORD`. The `activerecord_refined_test`
-database is created on first use.
+PostgreSQL and the MySQLs are reached on `127.0.0.1` as the current user with
+no password, which is how the devcontainer sets them up — MariaDB on its own
+port and Oracle's MySQL on 3307, since the two answer the `mysql2` adapter
+differently and CI runs both. Override with `DB_HOST`, `DB_PORT`,
+`DB_USERNAME` and `DB_PASSWORD`. The `activerecord_refined_test` database is
+created on first use.
 
 The `pg` and `mysql2` gems are in the Gemfile's `db` group, since building them
 needs the client libraries installed. Skip them if SQLite is all you need,

data/Rakefile

@@ -1,10 +1,22 @@
+# frozen_string_literal: true
+
 require "bundler/gem_tasks"
 require "rake/testtask"
+require "socket"
 
 ADAPTERS = %w[sqlite3 postgresql mysql2].freeze
 
+# The devcontainer serves Oracle's MySQL beside MariaDB, on 3307.  A
+# container from before it existed serves nothing there, and test:all says
+# so rather than failing or keeping quiet.
+def mysql8_reachable?
+  Socket.tcp("127.0.0.1", 3307, connect_timeout: 1) { true }
+rescue SystemCallError
+  false
+end
+
 Rake::TestTask.new do |t|
-  t.test_files = FileList['test/test_*.rb']
+  t.test_files = FileList["test/test_*.rb"]
 end
 
 namespace :test do
@@ -12,14 +24,30 @@ namespace :test do
     desc "Run the tests against #{adapter}"
     task adapter do
       puts "==== #{adapter} ===="
-      ENV['ADAPTER'] = adapter
+      ENV["ADAPTER"] = adapter
+      ENV.delete("DB_PORT")
       Rake::Task[:test].reenable
       Rake::Task[:test].invoke
     end
   end
 
+  desc "Run the tests against MySQL, which the devcontainer serves on 3307"
+  task :mysql8 do
+    puts "==== mysql2 (MySQL, port 3307) ===="
+    ENV["ADAPTER"] = "mysql2"
+    ENV["DB_PORT"] = "3307"
+    Rake::Task[:test].reenable
+    Rake::Task[:test].invoke
+  end
+
   desc "Run the tests against every adapter in turn"
-  task all: ADAPTERS
+  task all: ADAPTERS do
+    if mysql8_reachable?
+      Rake::Task["test:mysql8"].invoke
+    else
+      puts "MySQL is not listening on 3307; skipped"
+    end
+  end
 end
 
 task default: :test