activerecord-refined 0.8.1 → 0.10.0

data/lib/active_record/refined/ast.rb

@@ -1,45 +1,66 @@
+# frozen_string_literal: true
+
 # JSON.generate, for the document a containment test is given.
-require 'json'
+require "json"
 
 module ActiveRecord
   module Refined
     module AST
+      # @private
       NAME = /[[:alpha:]_][[:alnum:]_$]*/
+      # @private
       ALIAS_NAME = /\A#{NAME}\z/
+      # @private
       FUNCTION_NAME = /\A#{NAME}(\.#{NAME})?\z/
+      # A collation name where the family writes it bare, as all but PostgreSQL
+      # do.  A plain identifier: a hyphen unquoted would read as the collation
+      # minus a number, `x COLLATE nocase-1` as `(x COLLATE nocase) - 1`, valid
+      # and wrong.  PostgreSQL quotes the name and widens this; see its dialect.
+      # @private
+      COLLATION_NAME = /\A#{NAME}\z/
       # A SQL type as cast writes it: words, at most parenthesized with
       # lengths -- double precision, decimal(10,2).
+      # @private
       TYPE_NAME = /\A[[:alpha:]_][[:alnum:]_ ]*(\(\d+(, ?\d+)?\))?\z/
-
-      # Which family of spellings an adapter belongs to.  MariaDB answers to
-      # the mysql2 adapter and is counted with MySQL, though the two part
-      # company over JSON.  An adapter nobody has classified keeps the
-      # standard spellings and is left to say for itself what it cannot do.
-      #
-      # pglite is PostgreSQL itself compiled to WebAssembly, reached through
-      # wasmify-rails' adapter; the server it answers for is the same one.
-      ADAPTER_FAMILIES = {
-        'sqlite3' => :sqlite,
-        'postgresql' => :postgresql,
-        'postgis' => :postgresql,
-        'pglite' => :postgresql,
-        'mysql2' => :mysql,
-        'trilogy' => :mysql,
-      }.freeze
-
-      def self.adapter_family(model)
-        ADAPTER_FAMILIES[model.connection_db_config.adapter] || :unknown
-      end
+      # The characters PostgreSQL allows an operator to be made of, the
+      # widest operator alphabet of the three; op admits nothing else, so a
+      # letter, a space or a quote never reaches the SQL as an operator.
+      # @private
+      OPERATOR = %r{\A[+\-*/<>=~!@\#%^&|`?]+\z}
 
       def self.check_name(name, pattern, what)
         return name if pattern.match?(name.to_s)
         raise ArgumentError, "#{name.inspect} is not a plain #{what}"
       end
 
+      # A Ruby document or boolean written where JSON is wanted.  Taken as it
+      # is, a document would be the string that spells it and a boolean
+      # SQLite's own 1.  SQLite's json() marks the literal for the JSON
+      # functions; the MySQL family, which has no json(), reads it with
+      # JSON_EXTRACT.
+      def self.json_argument(value, model)
+        Dialect.for(model).json_argument(value, model)
+      end
+
+      # The conditions a column or an expression can be put in.  Every one
+      # gives back a condition that combines with `&`, `|` and `!`, and the
+      # comparisons quote a Ruby value on the right the way Active Record
+      # does, or take a column, an expression or a subquery there.
+      #
+      # @example
+      #   Author.where { :age.between?(20, 40) & :name.like?("A%") }
+      #   Author.where { :id.in?(Post.select(:author_id)) }
+      #
       # Predicate builders shared by symbols, qualified columns and
       # expressions. Imported into the Symbol refinement with
       # Refinement#import_methods, so every method must be defined with def.
       module Predications
+        # `=`.  A value, a column, an expression or a scalar subquery on the right; `nil` is refused, since `= NULL` is never true -- {#null?} is the spelling.
+        # @return [AST::Predicate]
+        # @example
+        #   Author.where { :name == "alice" }
+        #   Author.where { :age == Author.select { max(:age) } }
+        #
         # == and != mean SQL = and <>, and = NULL is never true there, so nil
         # is rejected rather than silently rewritten to IS NULL.  null? builds
         # its node directly and stays clear of this check.
@@ -50,6 +71,8 @@ module ActiveRecord
           Comparison.new(self, :==, other)
         end
 
+        # `!=`; `nil` is refused, as with `==`.
+        # @return [AST::Predicate]
         def !=(other)
           if other.nil?
             raise ArgumentError, "!= does not take nil; use !null? instead"
@@ -57,30 +80,50 @@ module ActiveRecord
           Comparison.new(self, :!=, other)
         end
 
+        # `>`.
+        # @return [AST::Predicate]
         def >(other)
           Comparison.new(self, :>, other)
         end
 
+        # `>=`.
+        # @return [AST::Predicate]
         def >=(other)
           Comparison.new(self, :>=, other)
         end
 
+        # `<`.
+        # @return [AST::Predicate]
         def <(other)
           Comparison.new(self, :<, other)
         end
 
+        # `<=`.
+        # @return [AST::Predicate]
         def <=(other)
           Comparison.new(self, :<=, other)
         end
 
+        # A regular expression match: `~` on PostgreSQL, `REGEXP` on MySQL, and what the adapter has elsewhere.  A Ruby Regexp's source is the pattern.
+        # @param pattern [Regexp, String]
+        # @return [AST::Predicate]
+        # @example
+        #   Author.where { :name =~ /^A/ }
         def =~(pattern)
           Match.new(self, pattern)
         end
 
+        # The negated regular expression match.
+        # @return [AST::Predicate]
         def !~(pattern)
           Match.new(self, pattern, negated: true)
         end
 
+        # `IS NULL`.
+        # @return [AST::Predicate]
+        # @example
+        #   Author.where { :country.null? }
+        #
         # `!` negates any predicate, so these are here for the four that SQL
         # spells for itself: IS NOT NULL rather than NOT (... IS NULL), and
         # likewise NOT IN and NOT LIKE.  They mean the same thing either way,
@@ -89,10 +132,17 @@ module ActiveRecord
           Comparison.new(self, :==, nil)
         end
 
+        # `IS NOT NULL`.
+        # @return [AST::Predicate]
         def not_null?
           Comparison.new(self, :!=, nil)
         end
 
+        # `IS TRUE`: true of the rows where the boolean is true, false where it is false or NULL -- where `== true` would be NULL.
+        # @return [AST::Predicate]
+        # @example
+        #   Post.where { :published.true? }
+        #
         # IS TRUE and IS FALSE differ from a comparison against the literal in
         # what they make of NULL: `flag = TRUE` is itself NULL there, and a
         # NULL predicate selects nothing, while these two answer false.  So the
@@ -102,34 +152,62 @@ module ActiveRecord
           TruthValue.new(self, true)
         end
 
+        # `IS NOT TRUE`: keeps the NULL rows that `!(:flag == true)` drops.
+        # @return [AST::Predicate]
         def not_true?
           TruthValue.new(self, true, negated: true)
         end
 
+        # `IS FALSE`.
+        # @return [AST::Predicate]
         def false?
           TruthValue.new(self, false)
         end
 
+        # `IS NOT FALSE`.
+        # @return [AST::Predicate]
         def not_false?
           TruthValue.new(self, false, negated: true)
         end
 
+        # `IN (...)`: an array of values, a range, or a relation as a subquery.
+        # @param values [Array, Range, ActiveRecord::Relation]
+        # @return [AST::Predicate]
+        # @example
+        #   Author.where { :country.in?(%w[JP US]) }
+        #   Author.where { :id.in?(Post.select(:author_id)) }
         def in?(values)
           In.new(self, values)
         end
 
+        # `NOT IN (...)`.
+        # @return [AST::Predicate]
         def not_in?(values)
           In.new(self, values, negated: true)
         end
 
+        # `BETWEEN min AND max`, with either end a value, a column or an expression.
+        # @return [AST::Predicate]
+        # @example
+        #   Author.where { :age.between?(20, 40) }
+        #
+        # Not min..max: an endpoint may be an expression, which Range would
+        # refuse to hold, since expressions do not compare among themselves.
         def between?(min, max)
-          In.new(self, min..max)
+          In.new(self, In::QuotedRange.new(min, max, false))
         end
 
+        # `NOT BETWEEN min AND max`.
+        # @return [AST::Predicate]
         def not_between?(min, max)
-          In.new(self, min..max, negated: true)
+          In.new(self, In::QuotedRange.new(min, max, false), negated: true)
         end
 
+        # `CASE column WHEN value THEN ...`: a CASE with this as the operand, each `when` a value it is compared against, followed by `then` and finally `else`.
+        # @return [AST::Case::When]
+        # @example
+        #   Author.select { :country.when("JP").then("Japan").else("elsewhere").as(:where) }
+        #
         # CASE with this as the operand, compared against each `when`:
         # `:age.when(10).then(1).else(0)`.  The other shape, where each `when`
         # carries its own condition, starts at `case_when`.
@@ -137,22 +215,38 @@ module ActiveRecord
           Case.new(self).when(value, &block)
         end
 
+        # `LIKE pattern`, the pattern as written: `%` and `_` are its wildcards.
+        # @param pattern [String]
+        # @return [AST::Predicate]
+        # @example
+        #   Author.where { :name.like?("A%") }
         def like?(pattern)
           Like.new(self, pattern)
         end
 
+        # `NOT LIKE pattern`.
+        # @return [AST::Predicate]
         def not_like?(pattern)
           Like.new(self, pattern, negated: true)
         end
 
+        # A case-insensitive `LIKE`: `ILIKE` on PostgreSQL, and `LIKE` over both sides lower-cased elsewhere.
+        # @return [AST::Predicate]
         def ilike?(pattern)
           Like.new(self, pattern, nil, case_sensitive: false)
         end
 
+        # The negated case-insensitive `LIKE`.
+        # @return [AST::Predicate]
         def not_ilike?(pattern)
           Like.new(self, pattern, nil, case_sensitive: false, negated: true)
         end
 
+        # Case-insensitive equality: `LOWER(column) = LOWER(value)`.
+        # @return [AST::Predicate]
+        # @example
+        #   Author.where { :name.casecmp?("Alice") }
+        #
         # Case-insensitive equality, folded on both sides rather than left to
         # the collation, so it means the same thing on every adapter.
         def casecmp?(value)
@@ -163,34 +257,56 @@ module ActiveRecord
                          Function.new("LOWER", [value]))
         end
 
+        # `IS DISTINCT FROM`: `!=` that treats NULL as a value.  `IS NOT` on SQLite, `NOT <=>` on MySQL.
+        # @return [AST::Predicate]
+        #
         # Null-safe comparison: unlike = and <>, these treat NULL as a value,
         # so not_distinct_from? is the one equality that may take nil.
         def distinct_from?(value)
           DistinctFrom.new(self, value, negated: true)
         end
 
+        # `IS NOT DISTINCT FROM`: `=` that treats NULL as a value, so this is the one equality that takes `nil`.
+        # @return [AST::Predicate]
+        # @example
+        #   Author.where { :country.not_distinct_from?(nil) }
         def not_distinct_from?(value)
           DistinctFrom.new(self, value)
         end
 
+        # `LIKE 'prefix%'`, the prefix escaped so that a `%` or `_` in it is itself; several prefixes are `OR`ed.
+        # @return [AST::Predicate]
+        # @example
+        #   Author.where { :name.start_with?("A", "B") }
         def start_with?(*prefixes)
           if prefixes.empty?
             raise ArgumentError, "start_with? needs at least one prefix"
           end
-          Like.any(self, prefixes.map {|prefix| "#{Like.escape(prefix)}%" })
+          Like.any(self, prefixes.map { |prefix| "#{Like.escape(prefix)}%" })
         end
 
+        # `LIKE '%suffix'`, escaped as {#start_with?} escapes.
+        # @return [AST::Predicate]
         def end_with?(*suffixes)
           if suffixes.empty?
             raise ArgumentError, "end_with? needs at least one suffix"
           end
-          Like.any(self, suffixes.map {|suffix| "%#{Like.escape(suffix)}" })
+          Like.any(self, suffixes.map { |suffix| "%#{Like.escape(suffix)}" })
         end
 
+        # `LIKE '%substring%'`, escaped as {#start_with?} escapes.
+        # @return [AST::Predicate]
+        # @example
+        #   Post.where { :title.include?("ruby") }
         def include?(substring)
           Like.new(self, "%#{Like.escape(substring)}%", Like::ESCAPE)
         end
 
+        # Whether a PostgreSQL array column holds the element: `@> ARRAY[element]`.
+        # @return [AST::Predicate]
+        # @example
+        #   Post.where { :tags.member?("ruby") }
+        #
         # The array comparisons carry the meaning of their Ruby namesakes.
         # member? is Enumerable's element test, so an Array argument is
         # rejected rather than quietly meaning something Array#member? does
@@ -203,18 +319,32 @@ module ActiveRecord
           ArrayPredicate.new(self, :"@>", [element])
         end
 
+        # Whether an array column holds every element given: `@>`.
+        # @return [AST::Predicate]
         def superset?(elements)
           ArrayPredicate.new(self, :"@>", ArrayPredicate.elements(elements, "superset?"))
         end
 
+        # Whether every element of an array column is among those given: `<@`.
+        # @return [AST::Predicate]
         def subset?(elements)
           ArrayPredicate.new(self, :"<@", ArrayPredicate.elements(elements, "subset?"))
         end
 
+        # Whether an array column and the elements given share any: `&&`.
+        # @return [AST::Predicate]
+        # @example
+        #   Post.where { :tags.intersect?(%w[ruby sql]) }
         def intersect?(elements)
           ArrayPredicate.new(self, :"&&", ArrayPredicate.elements(elements, "intersect?"))
         end
 
+        # The JSON at a path into a JSON column, still JSON -- to be dug further, compared with a Ruby value, or asked {#key?} and the rest.  A string or a symbol steps into an object, an integer into an array.  `#>` on PostgreSQL, `JSON_EXTRACT` on MySQL, `->` on SQLite.
+        # @return [AST::JsonPath]
+        # @example
+        #   Doc.select { :meta.dig(:author).as(:author) }
+        #   Doc.where { :meta.dig(:author).key?(:name) }
+        #
         # Reading inside a JSON document, by the name of what Hash does.  A
         # string or symbol steps into an object, an integer into an array, and
         # what comes back is still JSON, the way Hash#dig hands back the
@@ -222,13 +352,22 @@ module ActiveRecord
         # the JSON questions.  dig_text gives the value as text instead,
         # which is what a comparison wants.
         def dig(*path)
-          JsonPath.new(self, path, as_json: true)
+          JsonPath.new(self, path)
         end
 
+        # The value at a path as text, which is what a comparison against a string wants where the JSON type would not do: `#>>` on PostgreSQL, `JSON_UNQUOTE(JSON_EXTRACT(...))` on MySQL, `->>` on SQLite.
+        # @return [AST::JsonPath]
+        # @example
+        #   Doc.where { :meta.dig_text(:author, :name) == "alice" }
         def dig_text(*path)
-          JsonPath.new(self, path)
+          JsonPath.new(self, path, json_value: false)
         end
 
+        # The document without the keys given, as Hash#except gives it; an expression, for `update_all` to write back.
+        # @return [AST::JsonExcept]
+        # @example
+        #   Doc.update_all { { meta: :meta.except(:draft) } }
+        #
         # Keys taken out of a JSON document, by the name of what Hash does,
         # and taking keys as Hash#except takes them.  Like bury it gives back
         # the document changed rather than writing it anywhere.
@@ -236,6 +375,11 @@ module ActiveRecord
           JsonExcept.new(self, keys)
         end
 
+        # The document with a value set at a path, as {#dig} reads one; an expression, for `update_all` to write back.
+        # @return [AST::JsonSet]
+        # @example
+        #   Doc.update_all { { meta: :meta.bury(:author, :name, "alice") } }
+        #
         # What dig reads, bury sets: the last argument is the value and the
         # rest are the path to it.  The document comes back changed rather
         # than being written anywhere, which update_all is for.
@@ -243,40 +387,78 @@ module ActiveRecord
           JsonSet.new(self, path, value)
         end
 
+        # Whether the document contains the Ruby document given, which SQL calls containment: `@>` on PostgreSQL, `JSON_CONTAINS` on MySQL.  SQLite and MariaDB have none.
+        # @return [AST::Predicate]
+        # @example
+        #   Doc.where { :meta.contains?(author: { name: "alice" }) }
+        #
         # Whether the document holds what is given, which SQL calls
         # containment.  SQLite has no equivalent.
         def contains?(value)
           JsonContains.new(self, value)
         end
 
+        # Whether the object has the key, as Hash#key? asks.
+        # @return [AST::Predicate]
+        # @example
+        #   Doc.where { :meta.key?(:author) }
+        #
         # Whether the key is there at all, as Hash#key? asks.  Hash has
         # has_key? too; one name is enough, and this is the one Ruby's own
         # style prefers.
         def key?(key)
           JsonHasKey.new(self, key)
         end
+
+        # The keys of the object as a JSON array, as Hash#keys gives them.  Oracle has none.
+        # @return [AST::JsonKeys]
+        #
+        # The keys of the document, as Hash#keys gives them: a JSON array.
+        def keys
+          JsonKeys.new(self)
+        end
       end
 
+      # The arithmetic and the bitwise operators on a column or an
+      # expression.  Ruby puts all of them above the comparisons, so
+      # `:price * :quantity > 100` groups the way it reads, and a number on
+      # the left -- `20 - :quantity` -- builds the same expression.
+      #
+      # @example
+      #   LineItem.where { :price * :quantity > 1000 }
+      #   LineItem.select { (:flags & 4).as(:featured) }
+      #
       # Arithmetic builders shared by symbols, qualified columns and
       # expressions.  Imported into the Symbol refinement like Predications,
       # so every method must be defined with def.
       module Arithmetics
+        # `+`; with an Active Support duration on the right, a date moved: `:due_on + 3.days`.
+        # @return [AST::Arithmetic]
         def +(other)
           Arithmetic.new(self, :+, other)
         end
 
+        # `-`; with a duration on the right, a date moved back.
+        # @return [AST::Arithmetic]
         def -(other)
           Arithmetic.new(self, :-, other)
         end
 
+        # `*`.
+        # @return [AST::Arithmetic]
         def *(other)
           Arithmetic.new(self, :*, other)
         end
 
+        # `/`.
+        # @return [AST::Arithmetic]
         def /(other)
           Arithmetic.new(self, :/, other)
         end
 
+        # Bitwise AND.  `&` between two conditions is AND, which leaves this free to mean the SQL operator.
+        # @return [AST::Bitwise]
+        #
         # SQL's bitwise operators.  & and | are AND and OR between conditions
         # and are defined there, which is what leaves them free to mean here
         # what SQL means by them.  Ruby's precedence puts all six above the
@@ -285,27 +467,90 @@ module ActiveRecord
           Bitwise.new(self, :&, other)
         end
 
+        # Bitwise OR.
+        # @return [AST::Bitwise]
         def |(other)
           Bitwise.new(self, :|, other)
         end
 
+        # Bitwise XOR: `#` on PostgreSQL, `^` on MySQL, and the two operations it is made of on SQLite.
+        # @return [AST::Bitwise]
         def ^(other)
           Bitwise.new(self, :^, other)
         end
 
+        # A shift left.
+        # @return [AST::Bitwise]
         def <<(other)
           Bitwise.new(self, :<<, other)
         end
 
+        # A shift right.
+        # @return [AST::Bitwise]
         def >>(other)
           Bitwise.new(self, :>>, other)
         end
 
+        # Bitwise NOT.
+        # @return [AST::BitwiseNot]
         def ~
           BitwiseNot.new(self)
         end
       end
 
+      # Arithmetic with the number on the left, imported into the numeric
+      # refinements: 20 - :quantity builds what :quantity + 20 builds.  Only
+      # a column or an expression on the right means a query; anything else
+      # goes back to the number through super, so 1 + 2 is 3 inside a block
+      # too.
+      # @private
+      module NumericArithmetics
+        def +(other)
+          return super unless other.is_a?(::Symbol) || other.is_a?(Node)
+          Arithmetic.new(self, :+, other)
+        end
+
+        def -(other)
+          return super unless other.is_a?(::Symbol) || other.is_a?(Node)
+          Arithmetic.new(self, :-, other)
+        end
+
+        def *(other)
+          return super unless other.is_a?(::Symbol) || other.is_a?(Node)
+          Arithmetic.new(self, :*, other)
+        end
+
+        def /(other)
+          return super unless other.is_a?(::Symbol) || other.is_a?(Node)
+          Arithmetic.new(self, :/, other)
+        end
+
+        def &(other)
+          return super unless other.is_a?(::Symbol) || other.is_a?(Node)
+          Bitwise.new(self, :&, other)
+        end
+
+        def |(other)
+          return super unless other.is_a?(::Symbol) || other.is_a?(Node)
+          Bitwise.new(self, :|, other)
+        end
+
+        def ^(other)
+          return super unless other.is_a?(::Symbol) || other.is_a?(Node)
+          Bitwise.new(self, :^, other)
+        end
+
+        def <<(other)
+          return super unless other.is_a?(::Symbol) || other.is_a?(Node)
+          Bitwise.new(self, :<<, other)
+        end
+
+        def >>(other)
+          return super unless other.is_a?(::Symbol) || other.is_a?(Node)
+          Bitwise.new(self, :>>, other)
+        end
+      end
+
       class Node
         # The model travels with the table because some SQL cannot be written
         # without knowing the adapter, and a node is built before anything
@@ -316,38 +561,86 @@ module ActiveRecord
           raise ScriptError, "subclass must override this method"
         end
 
+        # The expression under an alias, as {BlockSyntax#as} gives a column
+        # one.
+        # @return [AST::As]
         def as(alias_name, quote: true)
           As.new(self, alias_name, quote: quote)
         end
 
+        # An ascending ordering by the expression.
+        # @return [AST::Ordering]
         def asc
           Ordering.new(self, :asc)
         end
 
+        # A descending ordering by the expression.
+        # @return [AST::Ordering]
         def desc
           Ordering.new(self, :desc)
         end
 
+        # The expression under a collation, as {BlockSyntax#collate}.
+        # @return [AST::Collate]
+        def collate(name)
+          Collate.new(self, name)
+        end
+
         private
+          # Resolves an operand denoting a column or an expression.  A number
+          # rides along for Arel to write out, which it can do for Integer and
+          # Float alone: a BigDecimal is quoted, which the adapter spells as
+          # the exact decimal, and a Rational, which no decimal spells exactly,
+          # is refused.
+          def to_arel_operand(operand, table, model)
+            case operand
+            when Node then operand.to_arel(table, model)
+            when :* then Arel.star
+            when Symbol then table[operand]
+            when ::BigDecimal, ::Rational then quote_number(operand)
+            else operand
+            end
+          end
 
-        # Resolves an operand denoting a column or an expression.
-        def to_arel_operand(operand, table, model)
-          case operand
-          when Node then operand.to_arel(table, model)
-          when :* then Arel.star
-          when Symbol then table[operand]
-          else operand
+          # A bare symbol is a column in every position, the value side of a
+          # comparison included.  The name is checked against the model, since
+          # a name it has no column for is almost always an enum value spelled
+          # as a symbol -- which, taken as a column, would quietly compare
+          # against nothing anyone meant.
+          def column_operand(name, table, model)
+            unless model.column_names.include?(name.to_s)
+              raise ArgumentError,
+                "#{name.inspect} is no column of #{model.table_name}; an enum " \
+                "value is written as its string, a column of another table " \
+                "qualified"
+            end
+            table[name]
           end
-        end
 
-        # Resolves a function argument: a column or an expression as above,
-        # anything else a value to be quoted.
-        def to_arel_argument(arg, table, model)
-          case arg
-          when Node, Symbol then to_arel_operand(arg, table, model)
-          else Arel::Nodes.build_quoted(arg)
+          # A number compares as itself, the way a bound ? does: the typed path
+          # would cast 99.5 against an integer column to 99 and quietly move
+          # the boundary.  Everything else keeps the column's own
+          # serialization -- an enum's name, a time's zone, a custom type's
+          # scaling.
+          def quote_number(value)
+            case value
+            when ::Rational
+              raise ArgumentError,
+                "a Rational has no exact SQL spelling; to_d says the decimal meant"
+            when ::Integer, ::Float, ::BigDecimal
+              Arel::Nodes.build_quoted(value)
+            else value
+            end
+          end
+
+          # Resolves a function argument: a column or an expression as above,
+          # anything else a value to be quoted.
+          def to_arel_argument(arg, table, model)
+            case arg
+            when Node, Symbol, ::Rational then to_arel_operand(arg, table, model)
+            else Arel::Nodes.build_quoted(arg)
+            end
           end
-        end
       end
 
       class Predicate < Node
@@ -366,11 +659,11 @@ module ActiveRecord
 
       # A literal standing where an expression would: `select { value(0).as(:depth) }`.
       #
-      # Values reach the SQL quoted wherever they appear as an operand, but the
-      # top of a select list is Active Record's, and a bare string there is SQL
-      # rather than a string.  Saying `value` is how you ask for the other
-      # meaning, and it carries the predications with it, so a literal can be
-      # compared and combined like anything else.
+      # Values reach the SQL quoted wherever they appear as an operand, but a
+      # bare Ruby literal at the top of a select list is refused as saying
+      # nothing.  `value` is the spelling that quotes it there, and it carries
+      # the predications with it, so a literal can be compared and combined
+      # like anything else.
       class Value < Node
         include Predications
         include Arithmetics
@@ -386,6 +679,43 @@ module ActiveRecord
         end
       end
 
+      # SQL as written: `sql("length(name) > ?", 10)`.  The ? and :name
+      # placeholders take quoted values through sanitize_sql_array, which
+      # needs the connection, so the binds wait here until the model is
+      # known.  Without binds the statement passes untouched -- which is
+      # what leaves PostgreSQL's ? operators writable, since only the
+      # positional-bind rewrite reads ? as a placeholder.
+      #
+      # As an operand the statement is parenthesized: its precedence is
+      # whatever was written inside.  The top of a select list gets it bare,
+      # through field_arel, where parentheses would refuse an alias written
+      # into the string.
+      class Sql < Node
+        include Predications
+        include Arithmetics
+
+        attr_reader :statement, :binds
+
+        def initialize(statement, binds)
+          unless statement.is_a?(::String)
+            raise ArgumentError,
+              "sql takes the statement as a string, not #{statement.inspect}"
+          end
+          @statement = statement
+          @binds = binds
+        end
+
+        def to_arel(_table, model)
+          Arel::Nodes::Grouping.new(field_arel(model))
+        end
+
+        def field_arel(model)
+          return Arel.sql(statement) if binds.empty?
+
+          Arel.sql(model.sanitize_sql_array([statement, *binds]))
+        end
+      end
+
       # CASE, in both of the shapes SQL has for it.  With an operand, each
       # `when` is something to compare it against; without one, each `when` is
       # a condition of its own.
@@ -409,16 +739,23 @@ module ActiveRecord
           @default = default
         end
 
+        # The next `WHEN`: a value to compare the operand against, or a condition as a value or a block.
+        # @return [AST::Case::When]
         def when(value = nil, &block)
           Pending.new(self, Case.argument(:when, value, block))
         end
 
+        # `THEN`, which belongs after a `when`; here it says so.
+        # @raise [ArgumentError]
+        #
         # Kernel#then is on every object, so `then` in the wrong place would be
         # answered by it -- with no block, silently, with an Enumerator.
         def then(*)
           raise ArgumentError, "then follows a when, and there is none to follow here"
         end
 
+        # `ELSE value`, as a value or a block, closing the CASE.  Without one the CASE gives NULL where no `when` matched.
+        # @return [AST::Case]
         def else(value = nil, &block)
           Case.new(operand, whens, Case.argument(:else, value, block))
         end
@@ -457,6 +794,8 @@ module ActiveRecord
             @condition = condition
           end
 
+          # `THEN value`, as a value or a block, for the `when` before it.
+          # @return [AST::Case]
           def then(value = nil, &block)
             Case.new(@kase.operand,
                      @kase.whens + [[@condition, Case.argument(:then, value, block)]],
@@ -485,24 +824,24 @@ module ActiveRecord
         # quoted so that a comma or a brace in a key is part of it.  except
         # writes its keys the same way, which are steps of no one path.
         def steps_array(steps = path)
-          "{#{steps.map {|step| %("#{escape_step(step)}") }.join(',')}}"
+          "{#{steps.map { |step| %("#{escape_step(step)}") }.join(',')}}"
         end
 
         # MySQL and SQLite take a path expression instead, where an integer is
         # a subscript and a name that is not plain has to be quoted.
         def dollar_path
-          path.inject(+'$') {|so_far, step| so_far << dollar_step(step) }
+          path.inject(+"$") { |so_far, step| so_far << dollar_step(step) }
         end
 
         def dollar_step(step)
           return "[#{step}]" if step.is_a?(::Integer)
           name = step.to_s
-          '.' + (name.match?(/\A[[:alpha:]_][[:alnum:]_]*\z/) ?
+          "." + (name.match?(/\A[[:alpha:]_][[:alnum:]_]*\z/) ?
                  name : %("#{escape_step(step)}"))
         end
 
         def escape_step(step)
-          step.to_s.gsub('\\', '\\\\').gsub('"', '\\"')
+          step.to_s.gsub("\\", "\\\\").gsub('"', '\\"')
         end
       end
 
@@ -521,11 +860,12 @@ module ActiveRecord
       # `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 on SQLite, an
-      # error on PostgreSQL and true on MySQL.  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.
+      # dig, bury and except give JSON, and a JSON comparison belongs to the
+      # JSON types -- jsonb and MySQL's -- where numbers compare as numbers
+      # and documents structurally, key order and spelling aside.  The Ruby
+      # value goes in as a JSON literal, and the adapters without such a
+      # type refuse it from JsonLiteral when the SQL is written, which is
+      # when the adapter is known.
       #
       # A string against dig_text, and anything the block itself built -- a
       # column, a function, another dug value -- go through untouched.
@@ -537,15 +877,14 @@ module ActiveRecord
       module JsonComparable
         %i[== != < <= > >=].each do |operator|
           define_method(operator) do |other|
-            check_comparable(other)
-            super(other)
+            super(comparison_value(other))
           end
         end
 
-        def in?(values) = super(check_each(values))
-        def not_in?(values) = super(check_each(values))
-        def between?(min, max) = super(*check_each([min, max]))
-        def not_between?(min, max) = super(*check_each([min, max]))
+        def in?(values) = super(comparison_set(values))
+        def not_in?(values) = super(comparison_set(values))
+        def between?(min, max) = super(comparison_value(min), comparison_value(max))
+        def not_between?(min, max) = super(comparison_value(min), comparison_value(max))
 
         %i[+ - * / & | ^ << >>].each do |operator|
           define_method(operator) do |_other|
@@ -558,38 +897,71 @@ module ActiveRecord
         end
 
         private
+          # nil is left to the comparison itself, which says to use null?, and
+          # so is anything the block built rather than wrote as a literal.
+          def comparison_value(other)
+            return other if other.nil? || other.is_a?(Node) || other.is_a?(::Symbol) ||
+                            other.is_a?(Arel::Nodes::Node) ||
+                            other.is_a?(Arel::Attributes::Attribute) ||
+                            other.is_a?(ActiveRecord::Relation)
+            return json_literal(other) if json_value?
+            return other if other.is_a?(::String)
+
+            raise ArgumentError,
+              "dig_text gives text, and comparing it with #{other.inspect} means " \
+              "something different on every adapter; cast it to the type meant"
+          end
 
-        # nil is left to the comparison itself, which says to use null?, and
-        # so is anything the block built rather than wrote as a literal.
-        def check_comparable(other)
-          return if other.nil? || other.is_a?(Node) || other.is_a?(::Symbol) ||
-                    other.is_a?(Arel::Nodes::Node) ||
-                    other.is_a?(Arel::Attributes::Attribute) ||
-                    other.is_a?(ActiveRecord::Relation)
-          return if other.is_a?(::String) && !as_json
+          def json_literal(other)
+            case other
+            when ::String, ::Integer, ::Float, ::BigDecimal, true, false, ::Hash, ::Array
+              JsonLiteral.new(other)
+            when ::Rational
+              raise ArgumentError,
+                "a Rational has no exact SQL spelling; to_d says the decimal meant"
+            else
+              raise ArgumentError,
+                "#{json_source} gives JSON, and #{other.inspect} has no JSON " \
+                "spelling; dig_text gives the value"
+            end
+          end
 
-          raise ArgumentError, as_json ?
-            "#{json_source} gives JSON, and comparing it with #{other.inspect} " \
-            "means something different on every adapter; dig_text gives the value" :
-            "dig_text gives text, and comparing it with #{other.inspect} means " \
-            "something different on every adapter; cast it to the type meant"
-        end
+          def comparison_set(values)
+            case values
+            when ActiveRecord::Relation then values
+            when ::Range
+              In::QuotedRange.new(comparison_value(values.begin),
+                                  comparison_value(values.end), values.exclude_end?)
+            else values.map { |value| comparison_value(value) }
+            end
+          end
 
-        def check_each(values)
-          case values
-          when ActiveRecord::Relation then values
-          when ::Range then [values.begin, values.end].each {|v| check_comparable(v) }
-          else values.each {|value| check_comparable(value) }
+          def arithmetic_refusal(operator)
+            json_value? ?
+              "#{json_source} gives JSON, and #{operator} on it means something " \
+              "different on every adapter; cast dig_text to the type meant" :
+              "dig_text gives text, and #{operator} on it means something " \
+              "different on every adapter; cast it to the type meant"
           end
-          values
+      end
+
+      # A Ruby value on the JSON side of a comparison, which jsonb and
+      # MySQL's JSON type answer alike: numbers compare as numbers and
+      # documents structurally.  SQLite and MariaDB have only the text of
+      # each -- spelling and key order deciding what equality means -- and
+      # refuse here.  PostgreSQL needs no cast, an untyped literal beside a
+      # jsonb operand coercing to jsonb; MySQL is told CAST(... AS JSON),
+      # since a bare string beside JSON would be a JSON string, and every
+      # string outranks every number in its ordering.
+      class JsonLiteral < Node
+        attr_reader :value
+
+        def initialize(value)
+          @value = value
         end
 
-        def arithmetic_refusal(operator)
-          as_json ?
-            "#{json_source} gives JSON, and #{operator} on it means something " \
-            "different on every adapter; cast dig_text to the type meant" :
-            "dig_text gives text, and #{operator} on it means something " \
-            "different on every adapter; cast it to the type meant"
+        def to_arel(_table, model)
+          Dialect.for(model).json_literal(Arel::Nodes.build_quoted(JSON.generate(value)), model)
         end
       end
 
@@ -600,9 +972,9 @@ module ActiveRecord
       # again is where they part company: SQLite parses it back and MySQL
       # takes it as written, where PostgreSQL has no such function for text.
       module JsonDocument
-        %i[dig dig_text key? contains? bury except].each do |name|
+        %i[dig dig_text key? keys contains? bury except].each do |name|
           define_method(name) do |*args|
-            unless as_json
+            unless json_value?
               raise ArgumentError,
                 "dig_text gives text, and #{name} reads JSON; dig keeps it"
             end
@@ -611,6 +983,22 @@ module ActiveRecord
         end
       end
 
+      # JSON the query computes rather than reads out of a document: always
+      # a JSON value, with no dig_text counterpart for JsonComparable's
+      # advice to name.  Included after JsonComparable, whose own
+      # arithmetic_refusal it overrides.
+      module ComputedJson
+        def json_value?
+          true
+        end
+
+        private
+          def arithmetic_refusal(operator)
+            "#{json_source} gives JSON, and #{operator} on it means " \
+            "something different on every adapter"
+          end
+      end
+
       class JsonPath < Node
         include Predications
         include Arithmetics
@@ -618,40 +1006,28 @@ module ActiveRecord
         include JsonComparable
         include JsonDocument
 
-        attr_reader :operand, :path, :as_json
+        attr_reader :operand, :path
 
-        def initialize(operand, path, as_json: false)
+        def initialize(operand, path, json_value: true)
           @operand = operand
-          @path = check_steps(path, 'dig')
-          @as_json = as_json
+          @path = check_steps(path, "dig")
+          @json_value = json_value
+        end
+
+        def json_value?
+          @json_value
         end
 
         def to_arel(table, model)
-          document = to_arel_operand(operand, table, model)
-          case AST.adapter_family(model)
-          when :postgresql
-            Arel::Nodes::InfixOperation.new(
-              as_json ? :"#>" : :"#>>", document, Arel::Nodes.build_quoted(steps_array))
-          when :mysql
-            extracted = Arel::Nodes::NamedFunction.new(
-              'JSON_EXTRACT', [document, Arel::Nodes.build_quoted(dollar_path)])
-            as_json ? extracted : Arel::Nodes::NamedFunction.new('JSON_UNQUOTE', [extracted])
-          else
-            extracted = Arel::Nodes::InfixOperation.new(
-              as_json ? :"->" : :"->>", document, Arel::Nodes.build_quoted(dollar_path))
-            # SQLite's ->> gives back the value with its type, where the other
-            # two give text.  Cast so that `dig_text(:n) == '5'` means the
-            # same thing everywhere, and a number wants a cast everywhere too.
-            as_json ? extracted : Arel::Nodes::NamedFunction.new(
-              'CAST', [Arel::Nodes::As.new(extracted, Arel::Nodes::SqlLiteral.new('text'))])
-          end
+          Dialect.for(model).json_path(
+            to_arel_operand(operand, table, model),
+            dollar_path, steps_array, json_value?, model)
         end
 
         private
-
-        def json_source
-          'dig'
-        end
+          def json_source
+            "dig"
+          end
       end
 
       # Setting a value inside a JSON document, which is what bury does to what
@@ -666,67 +1042,30 @@ module ActiveRecord
 
         def initialize(operand, path, value)
           @operand = operand
-          @path = check_steps(path, 'bury')
+          @path = check_steps(path, "bury")
           @value = value
         end
 
         # Always JSON, which is what the comparison guard asks.
-        def as_json
+        def json_value?
           true
         end
 
         def to_arel(table, model)
-          document = to_arel_operand(operand, table, model)
-          if AST.adapter_family(model) == :postgresql
-            Arel::Nodes::NamedFunction.new(
-              'jsonb_set',
-              [document, Arel::Nodes.build_quoted(steps_array), postgresql_value(table, model)])
-          else
-            Arel::Nodes::NamedFunction.new(
-              'JSON_SET',
-              [document, Arel::Nodes.build_quoted(dollar_path), other_value(table, model)])
-          end
+          Dialect.for(model).json_set(
+            to_arel_operand(operand, table, model),
+            steps_array, dollar_path, value,
+            (to_arel_operand(value, table, model) if expression?), model)
         end
 
         private
-
-        # jsonb_set takes jsonb, so an expression is turned into it and a Ruby
-        # value goes in as the JSON that says it -- '"x"' rather than 'x',
-        # which is not a document at all.
-        def postgresql_value(table, model)
-          return Arel::Nodes::NamedFunction.new(
-            'to_jsonb', [to_arel_operand(value, table, model)]) if expression?
-          Arel::Nodes.build_quoted(JSON.generate(value))
-        end
-
-        # The others take the value as it is, except a whole document or a
-        # boolean, which go in as JSON: taken as they are, a document would
-        # be the string that spells it, and a boolean SQLite's own 1.
-        # SQLite's json() marks the literal for JSON_SET; the MySQL family,
-        # which has no json(), reads it with JSON_EXTRACT.
-        def other_value(table, model)
-          return to_arel_operand(value, table, model) if expression?
-          unless value.is_a?(::Hash) || value.is_a?(::Array) ||
-                 value == true || value == false
-            return Arel::Nodes.build_quoted(value)
-          end
-
-          json = Arel::Nodes.build_quoted(JSON.generate(value))
-          if AST.adapter_family(model) == :sqlite
-            Arel::Nodes::NamedFunction.new('json', [json])
-          else
-            Arel::Nodes::NamedFunction.new(
-              'JSON_EXTRACT', [json, Arel::Nodes.build_quoted('$')])
+          def expression?
+            value.is_a?(Node) || value.is_a?(::Symbol)
           end
-        end
-
-        def expression?
-          value.is_a?(Node) || value.is_a?(::Symbol)
-        end
 
-        def json_source
-          'bury'
-        end
+          def json_source
+            "bury"
+          end
       end
 
       # Keys taken out of a JSON document.  PostgreSQL subtracts them, the
@@ -743,52 +1082,33 @@ module ActiveRecord
           @keys = check_keys(keys)
         end
 
-        def as_json
+        def json_value?
           true
         end
 
         def to_arel(table, model)
-          document = to_arel_operand(operand, table, model)
-          if AST.adapter_family(model) == :postgresql
-            # Grouped because - binds tighter than #>: dug out of a document,
-            # the subtraction would otherwise take the path literal first.
-            return Arel::Nodes::InfixOperation.new(
-              :-, Arel::Nodes::Grouping.new(document), key_array)
-          end
-
-          Arel::Nodes::NamedFunction.new(
-            'JSON_REMOVE',
-            [document, *keys.map {|key| Arel::Nodes.build_quoted("$#{dollar_step(key)}") }])
+          Dialect.for(model).json_remove(
+            to_arel_operand(operand, table, model),
+            keys.map { |key| "$#{dollar_step(key)}" },
+            steps_array(keys), model)
         end
 
         private
-
-        # jsonb has three subtractions -- a key, an array of keys, an element
-        # by index -- and an array literal written without a type is read as
-        # the first of them: `meta - '{draft}'` takes out the key spelled
-        # {draft}, which is nothing, and says nothing about it.
-        def key_array
-          Arel::Nodes::NamedFunction.new(
-            'CAST',
-            [Arel::Nodes::As.new(Arel::Nodes.build_quoted(steps_array(keys)),
-                                 Arel::Nodes::SqlLiteral.new('text[]'))])
-        end
-
-        # Keys, as Hash#except takes them: an index into an array is not what
-        # the name says anywhere, and is bury's business through a path.
-        def check_keys(keys)
-          raise ArgumentError, 'except needs a key' if keys.empty?
-          keys.each do |key|
-            next if key.is_a?(::String) || key.is_a?(::Symbol)
-            raise ArgumentError,
-              "except takes keys of the document, not #{key.inspect}"
+          # Keys, as Hash#except takes them: an index into an array is not what
+          # the name says anywhere, and is bury's business through a path.
+          def check_keys(keys)
+            raise ArgumentError, "except needs a key" if keys.empty?
+            keys.each do |key|
+              next if key.is_a?(::String) || key.is_a?(::Symbol)
+              raise ArgumentError,
+                "except takes keys of the document, not #{key.inspect}"
+            end
+            keys
           end
-          keys
-        end
 
-        def json_source
-          'except'
-        end
+          def json_source
+            "except"
+          end
       end
 
       # JSON containment: whether the document holds what is given.
@@ -801,23 +1121,17 @@ module ActiveRecord
         end
 
         def to_arel(table, model)
-          document = to_arel_operand(operand, table, model)
-          json = Arel::Nodes.build_quoted(JSON.generate(value))
-          case AST.adapter_family(model)
-          when :postgresql then Arel::Nodes::Contains.new(document, json)
-          when :mysql
-            Arel::Nodes::NamedFunction.new('JSON_CONTAINS', [document, json])
-          else
-            # Later than the others, since the adapter is only known here.
-            raise NotImplementedError,
-              "contains? has no equivalent on #{model.connection_db_config.adapter}"
-          end
+          Dialect.for(model).json_contains(
+            to_arel_operand(operand, table, model),
+            Arel::Nodes.build_quoted(JSON.generate(value)), model)
         end
       end
 
-      # Whether a key is in the document.  PostgreSQL has an operator for it,
-      # ?, which is also what a bind parameter looks like to several drivers;
-      # the function it is shorthand for says the same thing and survives.
+      # Whether a key is in the document.  PostgreSQL's spelling is the ?
+      # operator rather than jsonb_exists, the function it is shorthand for,
+      # because a GIN index matches the operator and never the function.  A
+      # ? is a bind placeholder only to sanitize_sql, which none of the SQL
+      # written here passes through.
       class JsonHasKey < Predicate
         attr_reader :operand, :key
 
@@ -827,28 +1141,111 @@ module ActiveRecord
         end
 
         def to_arel(table, model)
-          document = to_arel_operand(operand, table, model)
-          name = Arel::Nodes.build_quoted(key.to_s)
-          path = Arel::Nodes.build_quoted("$.#{key}")
-          case AST.adapter_family(model)
-          when :postgresql
-            Arel::Nodes::NamedFunction.new('jsonb_exists', [document, name])
-          when :mysql
-            Arel::Nodes::NamedFunction.new(
-              'JSON_CONTAINS_PATH', [document, Arel::Nodes.build_quoted('one'), path])
+          Dialect.for(model).json_has_key(
+            to_arel_operand(operand, table, model),
+            Arel::Nodes.build_quoted(key.to_s),
+            Arel::Nodes.build_quoted("$.#{key}"), model)
+        end
+      end
+
+      # The keys of a JSON document, as Hash#keys gives them: a JSON array.
+      # Only the MySQL family has a function for it; the other two reach the
+      # same array through a subquery over their key-listing functions.  The
+      # type guard is what makes all four answer alike: the keys of what 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, jsonb_agg over no rows.
+      class JsonKeys < Node
+        include Predications
+        include JsonComparable
+        include ComputedJson
+
+        attr_reader :operand
+
+        def initialize(operand)
+          @operand = operand
+        end
+
+        def to_arel(table, model)
+          Dialect.for(model).json_keys(to_arel_operand(operand, table, model), model)
+        end
+
+        private
+          def json_source
+            "keys"
+          end
+      end
+
+      # A JSON document built in the row: json_array from the values given,
+      # json_object from a Ruby hash.  SQLite and the MySQL family both say
+      # the standard names; PostgreSQL is asked to build jsonb, whose
+      # documents the other JSON operations here read.
+      class JsonBuild < Node
+        include Predications
+        include JsonComparable
+        include ComputedJson
+
+        attr_reader :kind, :values
+
+        def initialize(kind, values)
+          @kind = kind
+          @values = kind == :object ? check_pairs(values) : values
+        end
+
+        def to_arel(table, model)
+          dialect = Dialect.for(model)
+          if kind == :array
+            dialect.json_build(:array, nil,
+              values.map { |value| build_argument(value, dialect, table, model) }, model)
           else
-            Arel::Nodes::NamedFunction.new('json_type', [document, path]).not_eq(nil)
+            dialect.json_build(:object, values.keys.map(&:to_s),
+              values.values.map { |value| build_argument(value, dialect, table, model) }, model)
           end
         end
+
+        private
+          # An expression is itself and a bare scalar is quoted; a document or
+          # a boolean the dialect embeds as JSON, as bury takes it.
+          def build_argument(value, dialect, table, model)
+            case value
+            when Node, ::Symbol then to_arel_operand(value, table, model)
+            when ::Hash, ::Array, true, false then dialect.json_build_argument(value, model)
+            when ::Rational then quote_number(value)
+            else Arel::Nodes.build_quoted(value)
+            end
+          end
+
+          # The keys come from Ruby as Hash keys rather than alternating with
+          # the values as SQL has them, which is what keeps a bare symbol
+          # free to mean a column on the value side.  Anything but a name is
+          # refused here, before the adapters answer a NULL key three ways.
+          def check_pairs(pairs)
+            unless pairs.is_a?(::Hash)
+              raise ArgumentError,
+                "json_object takes a hash of keys to values, not #{pairs.inspect}"
+            end
+            pairs.each_key do |key|
+              next if key.is_a?(::String) || key.is_a?(::Symbol)
+              raise ArgumentError,
+                "a key of json_object is a string or a symbol, not #{key.inspect}"
+            end
+            pairs
+          end
+
+          def json_source
+            "json_#{kind}"
+          end
       end
 
       # GROUP BY GROUPING SETS / ROLLUP / CUBE: several groupings asked for at
       # once, the totals of each coming back beside the rows.  PostgreSQL has
-      # all three; the block raises for the others before it gets this far.
+      # all three and the MySQL family rollup alone; the block raises for the
+      # rest before it gets this far.
       #
       # Each set is a list of its own, so grouping_sets takes lists and rollup
       # and cube take the columns themselves.
       class GroupingSets < Node
+        # @private
         KINDS = {
           grouping_sets: Arel::Nodes::GroupingSet,
           rollup: Arel::Nodes::RollUp,
@@ -864,16 +1261,32 @@ module ActiveRecord
         end
 
         def to_arel(table, model)
+          return with_rollup(table, model) if Dialect.for(model).grouping_by_with_rollup?
+
           KINDS.fetch(kind).new(
             if kind == :grouping_sets
               sets.map do |set|
                 Arel::Nodes::GroupingElement.new(
-                  Array(set).map {|column| to_arel_operand(column, table, model) })
+                  Array(set).map { |column| to_arel_operand(column, table, model) })
               end
             else
-              sets.map {|column| to_arel_operand(column, table, model) }
+              sets.map { |column| to_arel_operand(column, table, model) }
             end)
         end
+
+        private
+          # The MySQL family spells rollup WITH ROLLUP, trailing the whole
+          # group list rather than wrapping a list of its own -- which is also
+          # why a rollup cannot stand beside other group entries there.  The
+          # columns are compiled by the connection's own visitor, so their
+          # quoting is the adapter's.
+          def with_rollup(table, model)
+            columns = sets.map { |column| to_arel_operand(column, table, model) }
+            sql = model.with_connection do |connection|
+              columns.map { |column| connection.visitor.compile(column) }.join(", ")
+            end
+            Arel.sql("#{sql} WITH ROLLUP")
+          end
       end
 
       class Column < Node
@@ -895,10 +1308,25 @@ module ActiveRecord
       # Arithmetic on columns and expressions.  Ruby's precedence puts these
       # above the comparison operators, so :price * :quantity > 100 groups the
       # way it reads.
+      #
+      # A Duration on the right moves a date: `:due_on + 3.days`.  No two
+      # families spell the move alike, so the dialect writes it, a part of the
+      # duration at a time.
       class Arithmetic < Node
         include Predications
         include Arithmetics
 
+        # Active Support's parts, as the units the SQL takes.  A week is seven
+        # days: SQLite and Oracle have no week.
+        # @private
+        UNITS = {
+          years: :year, months: :month, weeks: :day, days: :day,
+          hours: :hour, minutes: :minute, seconds: :second,
+        }.freeze
+
+        # @private
+        DATE_UNITS = %i[year month day].freeze
+
         attr_reader :left, :operator, :right
 
         def initialize(left, operator, right)
@@ -908,9 +1336,54 @@ module ActiveRecord
         end
 
         def to_arel(table, model)
-          to_arel_operand(left, table, model).
-            public_send(operator, to_arel_operand(right, table, model))
+          arel_left = to_arel_operand(left, table, model)
+          return move_date(arel_left, model) if right.is_a?(::ActiveSupport::Duration)
+          # The operator dispatches Arel's Math, which a bare number carries
+          # none of; quoted, it is a node with the same methods.
+          arel_left = Arel::Nodes.build_quoted(arel_left) if arel_left.is_a?(::Numeric)
+          arel_left.public_send(operator, to_arel_operand(right, table, model))
+        end
+
+        # SQLite has no date type, and its datetime() gives whatever it is
+        # handed a time of day, so a date column moved by a day would come
+        # back a midnight and sort past the same day written bare.  Its
+        # dialect has date() for what is a date to begin with, and this is
+        # what says so: a column the model declares a date, CURRENT_DATE, or
+        # one of those already moved by a date's units.  The other families
+        # keep the type themselves and never ask.
+        def self.date_operand?(operand, model)
+          case operand
+          when ::Symbol then model.type_for_attribute(operand).type == :date
+          when DatetimeValueFunction then operand.name == "CURRENT_DATE"
+          when Arithmetic
+            operand.right.is_a?(::ActiveSupport::Duration) &&
+              date_operand?(operand.left, model) &&
+              operand.right.parts.keys.all? { |part| DATE_UNITS.include?(UNITS[part]) }
+          else false
+          end
         end
+
+        private
+          # Each amount is written into the SQL as a number, and a fraction
+          # of a unit is not one every family takes, so it has to be a whole
+          # one.
+          def move_date(date, model)
+            unless operator == :+ || operator == :-
+              raise ArgumentError,
+                "a duration is added to a date or subtracted from it, not #{operator}"
+            end
+            dialect = Dialect.for(model)
+            date_only = Arithmetic.date_operand?(left, model)
+            right.parts.reduce(date) do |arel, (part, amount)|
+              unless amount.is_a?(::Integer)
+                raise ArgumentError, "#{amount.inspect} #{part} is not a whole number of them"
+              end
+              unit = UNITS.fetch(part)
+              amount *= 7 if part == :weeks
+              dialect.add_interval(arel, amount, unit, operator == :-,
+                                   date_only && DATE_UNITS.include?(unit))
+            end
+          end
       end
 
       # What the bitwise operators refuse.  Both refusals are there because
@@ -920,23 +1393,22 @@ module ActiveRecord
       # PostgreSQL has no such operator and would say so.
       module BitwiseOperands
         private
+          def check_operand(operand, operator)
+            return operand unless operand.is_a?(Predicate)
+            raise ArgumentError,
+              "a condition cannot be an operand of #{operator}; " \
+              "& and | between conditions are AND and OR"
+          end
 
-        def check_operand(operand, operator)
-          return operand unless operand.is_a?(Predicate)
-          raise ArgumentError,
-            "a condition cannot be an operand of #{operator}; " \
-            "& and | between conditions are AND and OR"
-        end
-
-        # Only the unqualified column can be checked, since that is the one
-        # the model is known to have.
-        def check_not_boolean(operand, operator, model)
-          return unless operand.is_a?(::Symbol)
-          return unless model.type_for_attribute(operand).type == :boolean
-          raise ArgumentError,
-            "#{operand.inspect} is a boolean column, which #{operator} does " \
-            "not take; #{operand.inspect}.true? is the condition"
-        end
+          # Only the unqualified column can be checked, since that is the one
+          # the model is known to have.
+          def check_not_boolean(operand, operator, model)
+            return unless operand.is_a?(::Symbol)
+            return unless model.type_for_attribute(operand).type == :boolean
+            raise ArgumentError,
+              "#{operand.inspect} is a boolean column, which #{operator} does " \
+              "not take; #{operand.inspect}.true? is the condition"
+          end
       end
 
       # SQL's bitwise operators.  Each parenthesises itself, which is what
@@ -947,6 +1419,7 @@ module ActiveRecord
         include Arithmetics
         include BitwiseOperands
 
+        # @private
         NODES = {
           :& => Arel::Nodes::BitwiseAnd,
           :| => Arel::Nodes::BitwiseOr,
@@ -976,22 +1449,14 @@ module ActiveRecord
         end
 
         private
-
-        # Arel has a node for XOR, but it writes ^ on every adapter, and ^ is
-        # exponentiation to PostgreSQL -- a wrong answer rather than an error.
-        # PostgreSQL's own spelling, #, is where a comment starts on MySQL, so
-        # it cannot be the portable one either.  SQLite has no XOR at all;
-        # (a | b) - (a & b) is it, at the cost of naming each operand twice.
-        def xor(left, right, model)
-          case AST.adapter_family(model)
-          when :postgresql then Arel::Nodes::InfixOperation.new('#', left, right)
-          when :mysql then Arel::Nodes::BitwiseXor.new(left, right)
-          else
-            Arel::Nodes::Subtraction.new(
-              Arel::Nodes::Grouping.new(Arel::Nodes::BitwiseOr.new(left, right)),
-              Arel::Nodes::Grouping.new(Arel::Nodes::BitwiseAnd.new(left, right)))
+          # Arel has a node for XOR, but it writes ^ on every adapter, and ^ is
+          # exponentiation to PostgreSQL -- a wrong answer rather than an error.
+          # PostgreSQL's own spelling, #, is where a comment starts on MySQL, so
+          # it cannot be the portable one either.  SQLite has no XOR at all;
+          # (a | b) - (a & b) is it, at the cost of naming each operand twice.
+          def xor(left, right, model)
+            Dialect.for(model).bitwise_xor(left, right)
           end
-        end
       end
 
       # ~, which every adapter has.  MySQL answers with the unsigned 64-bit
@@ -1018,6 +1483,12 @@ module ActiveRecord
       # OVER, on the two things that can carry a window: an aggregate, and a
       # function.
       module Windowing
+        # `OVER ()`, an empty window to be filled by {Over#partition},
+        # {Over#order}, {Over#rows} and {Over#range}.
+        # @return [AST::Over]
+        # @example
+        #   Author.select { avg(:age).over.partition(:country).as(:country_average) }
+        #   Post.select { sum(:likes).over.order(:created_at).rows(..0).as(:running) }
         def over
           Over.new(self)
         end
@@ -1039,30 +1510,44 @@ module ActiveRecord
           @frame = frame
         end
 
+        # `PARTITION BY`, the columns or expressions given.
+        # @return [AST::Over]
         def partition(*exprs)
           raise ArgumentError, "partition needs an expression" if exprs.empty?
           Over.new(function, partitions + exprs, orders, frame)
         end
 
+        # `ORDER BY` within the window: columns, or orderings such as `:age.desc`.
+        # @return [AST::Over]
         def order(*exprs)
           raise ArgumentError, "order needs an expression" if exprs.empty?
           Over.new(function, partitions, orders + exprs, frame)
         end
 
+        # `ROWS BETWEEN`, as a range of rows counted from the current one: negative before it, positive after, `0` the row itself, an open end unbounded.  `rows(..0)` is a running total, `rows(-1..1)` the row and its neighbours.
+        # @param bounds [Range]
+        # @return [AST::Over]
         def rows(bounds)
           Over.new(function, partitions, orders, framing(:rows, bounds))
         end
 
+        # `RANGE BETWEEN`, with the bounds as {#rows} takes them.
+        # @param bounds [Range]
+        # @return [AST::Over]
         def range(bounds)
           Over.new(function, partitions, orders, framing(:range, bounds))
         end
 
         def to_arel(table, model)
           window = Arel::Nodes::Window.new
-          partitions.each {|expr| window.partition(to_arel_operand(expr, table, model)) }
-          orders.each {|expr| window.order(to_arel_operand(expr, table, model)) }
+          partitions.each { |expr| window.partition(to_arel_operand(expr, table, model)) }
+          orders.each { |expr| window.order(to_arel_operand(expr, table, model)) }
           frame_arel(window) if frame
 
+          # Not every aggregate can ride a window everywhere; the node itself
+          # says where, once the adapter is known.
+          function.check_window(model) if function.respond_to?(:check_window)
+
           # A window-only function refuses to build on its own; here is where
           # it is asked for the call itself.
           arel_function =
@@ -1072,43 +1557,42 @@ module ActiveRecord
         end
 
         private
-
-        # The frame is a range of rows counted from the current one: negative
-        # before it, positive after, 0 the row itself, and an open end for
-        # unbounded.  `rows(..0)` is what a running total wants.
-        def framing(kind, bounds)
-          raise ArgumentError, "a window has one frame" if frame
-          unless bounds.is_a?(::Range)
-            raise ArgumentError, "#{kind} takes a range of rows, as in rows(..0)"
-          end
-          if bounds.exclude_end?
-            raise ArgumentError, "a frame ends on a row rather than before one; use .."
-          end
-          [bounds.begin, bounds.end].each do |bound|
-            next if bound.nil? || bound.is_a?(::Integer)
-            raise ArgumentError,
-              "a frame bound is a number of rows, or nothing for unbounded"
+          # The frame is a range of rows counted from the current one: negative
+          # before it, positive after, 0 the row itself, and an open end for
+          # unbounded.  `rows(..0)` is what a running total wants.
+          def framing(kind, bounds)
+            raise ArgumentError, "a window has one frame" if frame
+            unless bounds.is_a?(::Range)
+              raise ArgumentError, "#{kind} takes a range of rows, as in rows(..0)"
+            end
+            if bounds.exclude_end?
+              raise ArgumentError, "a frame ends on a row rather than before one; use .."
+            end
+            [bounds.begin, bounds.end].each do |bound|
+              next if bound.nil? || bound.is_a?(::Integer)
+              raise ArgumentError,
+                "a frame bound is a number of rows, or nothing for unbounded"
+            end
+            [kind, bounds.begin, bounds.end]
           end
-          [kind, bounds.begin, bounds.end]
-        end
 
-        # Arel wants the keyword itself on the left of the BETWEEN, which is
-        # what window.rows with no argument hands back.
-        def frame_arel(window)
-          kind, from, to = frame
-          window.frame(
-            Arel::Nodes::Between.new(
-              window.public_send(kind),
-              Arel::Nodes::And.new([bound(from, Arel::Nodes::Preceding.new),
-                                    bound(to, Arel::Nodes::Following.new)])))
-        end
+          # Arel wants the keyword itself on the left of the BETWEEN, which is
+          # what window.rows with no argument hands back.
+          def frame_arel(window)
+            kind, from, to = frame
+            window.frame(
+              Arel::Nodes::Between.new(
+                window.public_send(kind),
+                Arel::Nodes::And.new([bound(from, Arel::Nodes::Preceding.new),
+                                      bound(to, Arel::Nodes::Following.new)])))
+          end
 
-        def bound(rows, unbounded)
-          return unbounded if rows.nil?
-          return Arel::Nodes::CurrentRow.new if rows.zero?
-          rows.negative? ? Arel::Nodes::Preceding.new(-rows)
-                         : Arel::Nodes::Following.new(rows)
-        end
+          def bound(rows, unbounded)
+            return unbounded if rows.nil?
+            return Arel::Nodes::CurrentRow.new if rows.zero?
+            rows.negative? ? Arel::Nodes::Preceding.new(-rows)
+                           : Arel::Nodes::Following.new(rows)
+          end
       end
 
       class Aggregate < Node
@@ -1116,11 +1600,17 @@ module ActiveRecord
         include Arithmetics
         include Windowing
 
+        # The aggregates DISTINCT changes: over each value once, count counts
+        # fewer and sum and avg reckon less.  min and max give the same
+        # either way, so a DISTINCT there is refused as saying nothing.
+        # @private
+        DISTINCT_FUNCTIONS = %i[count sum average].freeze
+
         attr_reader :operand, :function, :distinct, :condition
 
         def initialize(operand, function, distinct: false, condition: nil)
-          if distinct && function != :count
-            raise ArgumentError, "#{function} does not take distinct"
+          if distinct && !DISTINCT_FUNCTIONS.include?(function)
+            raise ArgumentError, "#{function} does not take distinct; it would give the same"
           end
           if distinct && operand == :*
             raise ArgumentError, "count(:*) does not take distinct; name a column"
@@ -1131,8 +1621,12 @@ module ActiveRecord
           @condition = condition
         end
 
-        # FILTER (WHERE ...): the aggregate is taken over the rows the
-        # condition holds for.  A value or a block, as `when` takes them.
+        # `FILTER (WHERE condition)`: the aggregate taken over the rows the
+        # condition holds for, as a value or a block.  Where there is no
+        # FILTER clause -- MySQL, SQL Server -- the CASE that means the same.
+        # @return [AST::Aggregate]
+        # @example
+        #   Author.select { [count(:*).as(:all), count(:*).filter { :age < 50 }.as(:young)] }
         def filter(condition = nil, &block)
           Aggregate.new(operand, function, distinct: distinct,
                         condition: Case.argument(:filter, condition, block))
@@ -1141,11 +1635,11 @@ module ActiveRecord
         def to_arel(table, model)
           return aggregate(operand, table, model) unless condition
 
-          # MySQL has no FILTER clause.  An aggregate passes over a NULL, so
-          # the case that yields nothing for the rows the condition misses is
-          # the same aggregate over the same rows -- count(*) has no operand to
-          # keep, and counts a 1 instead.
-          if AST.adapter_family(model) == :mysql
+          # A family without a FILTER clause gets the CASE that means the same.
+          # An aggregate passes over a NULL, so the case that yields nothing for
+          # the rows the condition misses is the same aggregate over the same
+          # rows -- count(*) has no operand to keep, and counts a 1 instead.
+          unless Dialect.for(model).filter_supported?
             kept = Case.new.when(condition).then(operand == :* ? 1 : operand)
             return aggregate(kept, table, model)
           end
@@ -1154,15 +1648,136 @@ module ActiveRecord
         end
 
         private
+          def aggregate(over, table, model)
+            arel_operand = to_arel_operand(over, table, model)
+            return arel_operand.count(distinct) if function == :count
+            call = arel_operand.public_send(function)
+            call.distinct = distinct
+            call
+          end
+      end
 
-        def aggregate(over, table, model)
-          arel_operand = to_arel_operand(over, table, model)
-          if function == :count
-            arel_operand.count(distinct)
-          else
-            arel_operand.public_send(function)
+      # Rows gathered into one JSON document: json_arrayagg collects a value
+      # from each row into an array, json_objectagg a key and a value into an
+      # object.  Every adapter has the pair under a name of its own; what
+      # PostgreSQL gets is the jsonb one, whose documents the other JSON
+      # operations here read.
+      class JsonAggregate < Node
+        include Predications
+        include JsonComparable
+        include ComputedJson
+        include Windowing
+
+        attr_reader :kind, :operands, :condition
+
+        def initialize(kind, operands, condition: nil)
+          @kind = kind
+          @operands = operands
+          @condition = condition
+        end
+
+        # `FILTER (WHERE condition)`, as {Aggregate#filter}; refused on the
+        # MySQL family, where the CASE that stands in would leave a JSON null
+        # for every row it drops.
+        # @return [AST::JsonAggregate]
+        def filter(condition = nil, &block)
+          JsonAggregate.new(kind, operands,
+                            condition: Case.argument(:filter, condition, block))
+        end
+
+        # Over asks here before writing a window, since a family may take
+        # every other aggregate as one but not these two.
+        def check_window(model)
+          Dialect.for(model).check_json_aggregate_window(json_source, model)
+        end
+
+        def to_arel(table, model)
+          dialect = Dialect.for(model)
+          call = Arel::Nodes::NamedFunction.new(
+            dialect.json_aggregate_name(kind),
+            operands.map { |operand| to_arel_argument(operand, table, model) })
+          return call unless condition
+
+          # The CASE that stands in for FILTER elsewhere hands the aggregate a
+          # NULL for every row the condition misses, and these two keep a NULL
+          # -- as JSON null -- rather than passing over it, so it is refused.
+          unless dialect.json_aggregate_filter_supported?
+            raise NotImplementedError,
+              "#{json_source}.filter has no equivalent on " \
+              "#{model.connection_db_config.adapter}; a CASE would leave a " \
+              "null in the document for every row it drops"
+          end
+          call.filter(condition.to_arel(table, model))
+        end
+
+        private
+          def json_source
+            "json_#{kind}"
+          end
+      end
+
+      # The strings of a group joined into one, a separator between:
+      # `string_agg(:title, ", ")`, with `.order` for the order they are
+      # joined in.  Every family has it under a name of its own with the
+      # ORDER BY in a place of its own, and Arel has no node for an ORDER BY
+      # inside a call, so the dialect writes the call.  A NULL is passed
+      # over as by any aggregate, so the CASE that stands in for FILTER
+      # means the same here and is not refused as the JSON aggregates' is.
+      class StringAggregate < Node
+        include Predications
+        include Windowing
+
+        attr_reader :operand, :separator, :orders, :condition
+
+        def initialize(operand, separator, orders: [], condition: nil)
+          unless separator.is_a?(::String)
+            raise ArgumentError, "#{separator.inspect} is not a String separator"
           end
+          @operand = operand
+          @separator = separator
+          @orders = orders
+          @condition = condition
+        end
+
+        # The order the strings are joined in: columns, or orderings such as
+        # `:title.desc`.
+        # @return [AST::StringAggregate]
+        def order(*exprs)
+          raise ArgumentError, "order needs an expression" if exprs.empty?
+          StringAggregate.new(operand, separator, orders: orders + exprs, condition: condition)
+        end
+
+        # `FILTER (WHERE condition)`, as {Aggregate#filter}.
+        # @return [AST::StringAggregate]
+        def filter(condition = nil, &block)
+          StringAggregate.new(operand, separator, orders: orders,
+                              condition: Case.argument(:filter, condition, block))
+        end
+
+        def check_window(model)
+          Dialect.for(model).check_string_aggregate_window(model)
+        end
+
+        def to_arel(table, model)
+          dialect = Dialect.for(model)
+          kept = condition && !dialect.filter_supported? ?
+            Case.new.when(condition).then(operand) : operand
+          call = dialect.string_agg(
+            to_arel_argument(kept, table, model), separator,
+            orders.map { |expr| to_arel_operand(expr, table, model) },
+            string_operand?(model), model)
+          return call unless condition && dialect.filter_supported?
+          Arel::Nodes::Filter.new(call, condition.to_arel(table, model))
         end
+
+        private
+          # Whether the operand is a column the model declares a string.
+          # PostgreSQL asks, its STRING_AGG taking text and nothing else; the
+          # others convert for themselves.
+          def string_operand?(model)
+            operand.is_a?(::Symbol) &&
+              %i[string text].include?(model.type_for_attribute(operand).type)
+          end
       end
 
       # A column alias, quoted by the adapter, so that the name asked for is
@@ -1191,11 +1806,33 @@ module ActiveRecord
         end
 
         private
+          def alias_sql(model)
+            name = alias_name.to_s
+            return name unless quote
+            model.with_connection { |connection| connection.quote_column_name(name) }
+          end
+      end
 
-        def alias_sql(model)
-          name = alias_name.to_s
-          return name unless quote
-          model.with_connection {|connection| connection.quote_column_name(name) }
+      # A collation named for a comparison or an ordering: `:name.collate(:ci)`.
+      # It stands as an expression -- compared, ordered by, selected -- and
+      # gives back one of its own, so the collation carries through.
+      #
+      # The name follows COLLATE as a bare identifier with no Arel node of its
+      # own.  What names are safe turns on whether the family quotes it -- only
+      # PostgreSQL does -- so the dialect checks the name as it builds the
+      # clause, rather than this node holding one rule for all of them.
+      class Collate < Node
+        include Predications
+
+        attr_reader :operand, :name
+
+        def initialize(operand, name)
+          @name = name.to_s
+          @operand = operand
+        end
+
+        def to_arel(table, model)
+          Dialect.for(model).collate(to_arel_operand(operand, table, model), name, model)
         end
       end
 
@@ -1208,12 +1845,18 @@ module ActiveRecord
           @nulls = nulls
         end
 
+        # `NULLS FIRST`; portable, since Arel emulates it where MySQL has
+        # none.
+        # @return [AST::Ordering]
+        #
         # MySQL has no NULLS FIRST/LAST, but Arel emulates it there with a
         # leading IS NULL ordering, so these are portable.
         def nulls_first
           Ordering.new(operand, direction, :nulls_first)
         end
 
+        # `NULLS LAST`.
+        # @return [AST::Ordering]
         def nulls_last
           Ordering.new(operand, direction, :nulls_last)
         end
@@ -1237,11 +1880,54 @@ module ActiveRecord
         end
 
         def to_arel(table, model)
-          arel_args = args.map {|arg| to_arel_argument(arg, table, model) }
+          arel_args = args.map { |arg| to_arel_argument(arg, table, model) }
           Arel::Nodes::NamedFunction.new(name, arel_args)
         end
       end
 
+      # Escape hatch for operators without a spelling of their own, the way
+      # fn is for functions.  The operator is emitted as written -- whether
+      # the adapter has it is the caller's assertion, as fn's names are --
+      # and the values ride as quoted literals, so on PostgreSQL an untyped
+      # one takes the type of the operand beside it.
+      class Operation < Node
+        include Predications
+        include Arithmetics
+
+        attr_reader :operator, :left, :right
+
+        def initialize(operator, left, right)
+          @operator = AST.check_name(operator, OPERATOR, "operator").to_s
+          @left = check_side(left)
+          @right = check_side(right)
+        end
+
+        def to_arel(table, model)
+          Arel::Nodes::Grouping.new(
+            Arel::Nodes::InfixOperation.new(
+              operator, side(left, table, model), side(right, table, model)))
+        end
+
+        private
+          # An expression operand is parenthesized: an unknown operator's
+          # precedence is unknown too, and PostgreSQL reads its named
+          # operators from the left, so a bare infix on the right would take
+          # the new operator's left side into its own.
+          def side(operand, table, model)
+            arel = to_arel_argument(operand, table, model)
+            operand.is_a?(Node) ? Arel::Nodes::Grouping.new(arel) : arel
+          end
+
+          def check_side(operand)
+            if operand.is_a?(::Hash) || operand.is_a?(::Array) || operand.is_a?(::Set)
+              raise ArgumentError,
+                "#{operand.inspect} has no one SQL spelling; a string says it " \
+                "in the adapter's own, to_json for a document"
+            end
+            operand
+          end
+      end
+
       # ROW_NUMBER and its kind: functions that say nothing without a window.
       # On its own this refuses rather than reaching the database as an error
       # there; over asks it for call_arel instead.
@@ -1326,6 +2012,7 @@ module ActiveRecord
       # or an Array compares against a PostgreSQL range or array column, the way
       # Active Record's own force_equality? types do.
       class Comparison < Predicate
+        # @private
         OPERATOR_MAP = {
           :== => :eq, :!= => :not_eq,
           :> => :gt, :>= => :gteq, :< => :lt, :<= => :lteq
@@ -1344,24 +2031,24 @@ module ActiveRecord
           arel_value =
             case value
             when Node then value.to_arel(table, model)
+            when ::Symbol then column_operand(value, table, model)
             when ActiveRecord::Relation then scalar_subquery(value)
-            else value
+            else quote_number(value)
             end
           arel_column.public_send(OPERATOR_MAP.fetch(operator), arel_value)
         end
 
         private
-
-        # A relation compared against a column has to yield a single value, so
-        # unlike In there is no sensible default select list to fall back on.
-        def scalar_subquery(relation)
-          if relation.select_values.empty?
-            raise ArgumentError,
-              "#{operator} needs a subquery selecting one value; add a select"
+          # A relation compared against a column has to yield a single value, so
+          # unlike In there is no sensible default select list to fall back on.
+          def scalar_subquery(relation)
+            if relation.select_values.empty?
+              raise ArgumentError,
+                "#{operator} needs a subquery selecting one value; add a select"
+            end
+            relation = relation.send(:apply_join_dependency) if relation.eager_loading?
+            relation.arel
           end
-          relation = relation.send(:apply_join_dependency) if relation.eager_loading?
-          relation.arel
-        end
       end
 
       # IS TRUE, IS FALSE and their negations, which every adapter spells the
@@ -1376,9 +2063,8 @@ module ActiveRecord
         end
 
         def to_arel(table, model)
-          literal = value ? Arel::Nodes::True.new : Arel::Nodes::False.new
-          Arel::Nodes::InfixOperation.new(negated ? 'IS NOT' : 'IS',
-            to_arel_operand(operand, table, model), literal)
+          Dialect.for(model).truth_value(
+            to_arel_operand(operand, table, model), value, negated, model)
         end
       end
 
@@ -1388,19 +2074,18 @@ module ActiveRecord
       # selects the model's primary key.
       module SetSubquery
         private
-
-        def set_subquery(relation, spelling)
-          relation = relation.send(:apply_join_dependency) if relation.eager_loading?
-          if relation.select_values.empty?
-            model = relation.model
-            if model.composite_primary_key?
-              raise ArgumentError,
-                "Cannot map composite primary key #{model.primary_key} to #{spelling}"
+          def set_subquery(relation, spelling)
+            relation = relation.send(:apply_join_dependency) if relation.eager_loading?
+            if relation.select_values.empty?
+              model = relation.model
+              if model.composite_primary_key?
+                raise ArgumentError,
+                  "Cannot map composite primary key #{model.primary_key} to #{spelling}"
+              end
+              relation = relation.select(relation.table[model.primary_key])
             end
-            relation = relation.select(relation.table[model.primary_key])
+            relation.arel
           end
-          relation.arel
-        end
       end
 
       # IN for a list of values, BETWEEN for a range, IN (SELECT ...) for a
@@ -1408,6 +2093,12 @@ module ActiveRecord
       class In < Predicate
         include SetSubquery
 
+        # Range holds its endpoints to Comparable, which a quoted node is
+        # not, so this quacks the three methods Arel's between reads.
+        QuotedRange = Struct.new(:begin, :end, :exclude_end) do
+          def exclude_end? = exclude_end
+        end
+
         attr_reader :operand, :values, :negated
 
         def initialize(operand, values, negated: false)
@@ -1418,13 +2109,67 @@ module ActiveRecord
 
         def to_arel(table, model)
           arel_operand = to_arel_operand(operand, table, model)
-          if values.is_a?(Range)
-            arel_operand.public_send(negated ? :not_between : :between, values)
+          case values
+          when Range, QuotedRange
+            lower = quote_value(values.begin, table, model)
+            upper = quote_value(values.end, table, model)
+            if json_between?(model) && lower && upper && !negated
+              return arel_operand.gteq(lower).and(
+                values.exclude_end? ? arel_operand.lt(upper) : arel_operand.lteq(upper))
+            end
+            range = QuotedRange.new(lower, upper, values.exclude_end?)
+            arel_operand.public_send(negated ? :not_between : :between, range)
+          when ActiveRecord::Relation
+            arel_operand.public_send(negated ? :not_in : :in, set_subquery(values, "IN"))
           else
-            arg = values.is_a?(ActiveRecord::Relation) ? set_subquery(values, 'IN') : values
+            arg = values
+            if arg.is_a?(::Array)
+              arg = arg.map { |value| quote_value(value, table, model) }
+              return json_list(arel_operand, arg) if json_list?(model)
+            end
             arel_operand.public_send(negated ? :not_in : :in, arg)
           end
         end
+
+        private
+          # An element that is already an expression resolves, a symbol is a
+          # column here as everywhere, a number is quoted as itself, and the
+          # rest ride for Arel to cast by the column.
+          def quote_value(value, table, model)
+            case value
+            when Node then value.to_arel(table, model)
+            when ::Symbol then column_operand(value, table, model)
+            else quote_number(value)
+            end
+          end
+
+          # MySQL leaves IN and BETWEEN out of its JSON comparisons -- they
+          # fall back to another comparison entirely -- so on it a JSON set is
+          # spelled as the comparisons it means: the closed range as its two
+          # bounds, the list as one equality per element.  That names the dug
+          # value once per element, the price SQLite's XOR pays per operand;
+          # a negated range needs nothing, Arel writing it as two comparisons
+          # everywhere.  MariaDB never gets this far: the endpoints refuse as
+          # they resolve.
+          def json_between?(model)
+            (values.begin.is_a?(JsonLiteral) || values.end.is_a?(JsonLiteral)) &&
+              Dialect.for(model).json_list_by_element?
+          end
+
+          def json_list?(model)
+            values.any? { |value| value.is_a?(JsonLiteral) } &&
+              Dialect.for(model).json_list_by_element?
+          end
+
+          def json_list(arel_operand, elements)
+            comparisons = elements.map do |element|
+              negated ? arel_operand.not_eq(element) : arel_operand.eq(element)
+            end
+            joined = comparisons.inject do |so_far, piece|
+              negated ? so_far.and(piece) : so_far.or(piece)
+            end
+            negated ? Arel::Nodes::Grouping.new(joined) : joined
+          end
       end
 
       # ANY and ALL, which stand on the right of a comparison and say how many
@@ -1472,7 +2217,8 @@ module ActiveRecord
       end
 
       class Like < Predicate
-        ESCAPE = "\\".freeze
+        # @private
+        ESCAPE = "\\"
 
         # Escapes % and _ so that they match literally. The pattern built from
         # the result must be used with ESCAPE, since SQLite has no default
@@ -1484,8 +2230,8 @@ module ActiveRecord
         # ORs one LIKE per pattern, for the shortcuts that accept several
         # literals the way String#start_with? does.
         def self.any(operand, patterns)
-          patterns.map {|pattern| new(operand, pattern, ESCAPE) }.
-            inject {|left, right| Or.new(left, right) }
+          patterns.map { |pattern| new(operand, pattern, ESCAPE) }.
+            inject { |left, right| Or.new(left, right) }
         end
 
         attr_reader :operand, :pattern, :escape, :case_sensitive, :negated
@@ -1569,21 +2315,20 @@ module ActiveRecord
         end
 
         private
-
-        # PostgreSQL array input syntax: elements joined by commas inside
-        # braces, and an element is double-quoted whenever it is empty, spells
-        # NULL, or contains a character the parser treats specially.
-        def array_literal
-          encoded = elements.map do |value|
-            s = value.to_s
-            if s.empty? || s.casecmp?("null") || s.match?(/[\s{},"\\]/)
-              "\"#{s.gsub(/["\\]/) {|c| "\\#{c}" }}\""
-            else
-              s
+          # PostgreSQL array input syntax: elements joined by commas inside
+          # braces, and an element is double-quoted whenever it is empty, spells
+          # NULL, or contains a character the parser treats specially.
+          def array_literal
+            encoded = elements.map do |value|
+              s = value.to_s
+              if s.empty? || s.casecmp?("null") || s.match?(/[\s{},"\\]/)
+                "\"#{s.gsub(/["\\]/) { |c| "\\#{c}" }}\""
+              else
+                s
+              end
             end
+            "{#{encoded.join(',')}}"
           end
-          "{#{encoded.join(',')}}"
-        end
       end
 
       # Regular expression match: REGEXP on MySQL, ~ on PostgreSQL.  SQLite has
@@ -1607,19 +2352,18 @@ module ActiveRecord
         end
 
         private
-
-        # A Regexp literal reads naturally with =~, but only its source crosses
-        # over; the database has its own dialect and no notion of Ruby's flags.
-        # Dropping a flag would silently change what the query matches, so
-        # anything beyond a plain literal is refused rather than ignored.
-        def regexp_source(regexp)
-          unless regexp.options.zero?
-            raise ArgumentError,
-              "#{regexp.inspect} has options that SQL cannot express; " \
-              "pass the pattern as a string instead"
+          # A Regexp literal reads naturally with =~, but only its source crosses
+          # over; the database has its own dialect and no notion of Ruby's flags.
+          # Dropping a flag would silently change what the query matches, so
+          # anything beyond a plain literal is refused rather than ignored.
+          def regexp_source(regexp)
+            unless regexp.options.zero?
+              raise ArgumentError,
+                "#{regexp.inspect} has options that SQL cannot express; " \
+                "pass the pattern as a string instead"
+            end
+            regexp.source
           end
-          regexp.source
-        end
       end
 
       class And < Predicate