activerecord-refined 0.5.0 → 0.6.0

data/lib/active_record/refined.rb

@@ -4,10 +4,9 @@ module ActiveRecord
       refine Symbol do
         import_methods AST::Predications
         import_methods AST::Arithmetics
-        import_methods AST::Aggregations
 
-        def as(alias_name)
-          AST::As.new(self, alias_name)
+        def as(alias_name, quote: true)
+          AST::As.new(self, alias_name, quote: quote)
         end
 
         def asc
@@ -22,6 +21,18 @@ module ActiveRecord
           AST::Column.new(self, column_name)
         end
       end
+
+      # Shorthand for `value(0).as(:depth)` and the like.  Numbers only: a
+      # string in a select list already means SQL rather than a string, so
+      # giving String this would make the same literal mean two things
+      # depending on whether it had been sent a message.
+      [Integer, Float].each do |klass|
+        refine klass do
+          def as(alias_name, quote: true)
+            AST::As.new(AST::Value.new(self), alias_name, quote: quote)
+          end
+        end
+      end
     end
 
     class BlockContext
@@ -70,6 +81,9 @@ module ActiveRecord
         # default it to zero; SQLite's trunc takes only the one.
         trunc: {mysql: 'TRUNCATE'},
         now: {sqlite: nil},
+        # The bit aggregates, which PostgreSQL and MySQL spell alike and
+        # SQLite has none of.  PostgreSQL gained bit_xor in 14.
+        bit_and: {sqlite: nil}, bit_or: {sqlite: nil}, bit_xor: {sqlite: nil},
         date_trunc: {sqlite: nil, mysql: nil},
         # Named for Kernel#rand, which it also takes back: a block calling
         # rand would otherwise get Ruby's and never reach the database.
@@ -81,14 +95,6 @@ module ActiveRecord
         format: {mysql: nil},
       }.freeze
 
-      ADAPTER_FAMILIES = {
-        'sqlite3' => :sqlite,
-        'postgresql' => :postgresql,
-        'postgis' => :postgresql,
-        'mysql2' => :mysql,
-        'trilogy' => :mysql,
-      }.freeze
-
       SCALAR_FUNCTIONS.each_key do |name|
         define_method(name) do |*args|
           AST::Function.new(function_name(name, SCALAR_FUNCTIONS), args)
@@ -144,6 +150,26 @@ module ActiveRecord
         node
       end
 
+      # GROUP BY GROUPING SETS / ROLLUP / CUBE, which PostgreSQL has and the
+      # others do not -- MySQL's WITH ROLLUP says one of the three and says it
+      # somewhere else in the clause.  Arel has the nodes and writes them for
+      # PostgreSQL alone, so what it would raise elsewhere says nothing; this
+      # says it here, as extract does, while the block is being read.
+      #
+      #   Sale.group { grouping_sets([:region], [:product], []) }
+      #   Sale.group { rollup(:region, :product) }
+      def grouping_sets(*sets)
+        grouping(:grouping_sets, sets)
+      end
+
+      def rollup(*columns)
+        grouping(:rollup, columns)
+      end
+
+      def cube(*columns)
+        grouping(:cube, columns)
+      end
+
       # CAST(expr AS type).  The type is the adapter's own name for it,
       # checked for shape by the node; whether it exists is the database's to
       # say.
@@ -151,6 +177,32 @@ module ActiveRecord
         AST::Cast.new(expr, type)
       end
 
+      # The functions that only mean anything with a window.  Every adapter
+      # that has window functions at all spells these the same -- PostgreSQL,
+      # MySQL 8, SQLite 3.25 -- so unlike the scalar functions there is nothing
+      # here to translate.  Each says so if `over` never arrives.
+      %i[row_number rank dense_rank percent_rank cume_dist].each do |name|
+        define_method(name) { AST::WindowFunction.new(name.to_s.upcase, []) }
+      end
+
+      %i[ntile first_value last_value].each do |name|
+        define_method(name) {|arg| AST::WindowFunction.new(name.to_s.upcase, [arg]) }
+      end
+
+      def nth_value(expr, nth)
+        AST::WindowFunction.new('NTH_VALUE', [expr, nth])
+      end
+
+      # The offset is written out rather than left to default, so that a
+      # default value cannot end up where the offset belongs.
+      def lag(expr, offset = 1, default = nil)
+        AST::WindowFunction.new('LAG', default.nil? ? [expr, offset] : [expr, offset, default])
+      end
+
+      def lead(expr, offset = 1, default = nil)
+        AST::WindowFunction.new('LEAD', default.nil? ? [expr, offset] : [expr, offset, default])
+      end
+
       # Escape hatch for functions without a method of their own.  The name is
       # emitted as written, so a case-sensitive one can be spelled exactly,
       # and for that reason it has to be a plain name, optionally qualified by
@@ -160,12 +212,101 @@ module ActiveRecord
           AST.check_name(name, AST::FUNCTION_NAME, "function name").to_s, args)
       end
 
+      # BIT_COUNT.  MySQL counts the bits of a number; PostgreSQL counts those
+      # of a bit string, so the argument is cast, and to bit(64) because that
+      # is what makes a negative come back as MySQL has it -- 64 bits of two's
+      # complement rather than as many as the column happens to be wide.
+      def bit_count(expr)
+        case adapter_family
+        when :mysql then AST::Function.new('BIT_COUNT', [expr])
+        when :postgresql
+          AST::Function.new('BIT_COUNT', [AST::Cast.new(expr, 'bit(64)')])
+        else
+          raise NotImplementedError,
+            "bit_count has no equivalent on #{@model.connection_db_config.adapter}"
+        end
+      end
+
       def exists?(relation)
         AST::Exists.new(relation)
       end
 
+      # ANY and ALL quantify a comparison over a subquery, which is what a
+      # scalar subquery cannot do: it has to return the one row.
+      #
+      #   Post.where { :likes > any(Post.published.select(:likes)) }
+      #   Post.where { :likes >= all(Post.select(:likes)) }
+      #
+      # `== any` is IN and `!= all` is NOT IN, so what these add is the four
+      # comparisons IN has no spelling for.
+      def any(relation)
+        quantified('ANY', relation)
+      end
+
+      def all(relation)
+        quantified('ALL', relation)
+      end
+
+      # A literal where an expression is expected, quoted like any other value:
+      #
+      #   select { [:id, value(0).as(:depth)] }
+      #
+      # Needed because the top of a select list is ActiveRecord's, and a bare
+      # string there is SQL rather than a string.  Numbers have a shorthand --
+      # `0.as(:depth)` -- since nothing else could be meant by one.
+      def value(literal)
+        AST::Value.new(literal)
+      end
+
+      # The row an upsert could not insert, for the block upsert_all takes.
+      # PostgreSQL and SQLite give it a name; MySQL spells the same thing
+      # VALUES(column), which takes the column bare.
+      def excluded(column)
+        return AST::Column.new(:excluded, column) unless adapter_family == :mysql
+
+        quoted = @model.with_connection {|c| c.quote_column_name(column) }
+        AST::Function.new('VALUES', [Arel::Nodes::SqlLiteral.new(quoted)])
+      end
+
+      # CASE.  `case` is a keyword, so Ruby only reaches this one through the
+      # receiver -- `self.case` -- which is why the two shapes have shorthands
+      # that do not need it: `:age.when(...)` for the form with an operand, and
+      # `case_when` for the form where each when carries its own condition.
+      #
+      #   self.case(:age).when(10).then(1).else(0)
+      #   self.case.when { :age >= 60 }.then { :age - 60 }
+      def case(operand = nil)
+        AST::Case.new(operand)
+      end
+
+      # The searched CASE, started at its first when:
+      #
+      #   case_when { :age >= 60 }.then { :age - 60 }.else(0)
+      def case_when(value = nil, &block)
+        AST::Case.new.when(value, &block)
+      end
+
       private
 
+      # SQLite is the one adapter with no quantifier at all, and what it says
+      # when it meets one is a syntax error at the SELECT.
+      def quantified(kind, relation)
+        if adapter_family == :sqlite
+          raise NotImplementedError,
+            "#{kind} has no equivalent on #{@model.connection_db_config.adapter}"
+        end
+        AST::Quantified.new(kind, relation)
+      end
+
+      def grouping(kind, sets)
+        node = AST::GroupingSets.new(kind, sets)
+        unless adapter_family == :postgresql
+          raise NotImplementedError,
+            "#{kind} has no equivalent on #{@model.connection_db_config.adapter}"
+        end
+        node
+      end
+
       def function_name(name, functions)
         spellings = functions.fetch(name)
         return name.to_s.upcase unless spellings.key?(adapter_family)
@@ -174,18 +315,15 @@ module ActiveRecord
                 "#{name} has no equivalent on #{@model.connection_db_config.adapter}")
       end
 
-      # An adapter nobody has classified keeps the standard spellings, and is
-      # left to say for itself what it cannot do.
       def adapter_family
-        @adapter_family ||=
-          ADAPTER_FAMILIES[@model.connection_db_config.adapter] || :unknown
+        @adapter_family ||= AST.adapter_family(@model)
       end
     end
 
     module QueryMethods
       def where(opts = nil, *rest, &block)
         if block
-          super(evaluate_block(&block).to_arel(table))
+          super(evaluate_block(&block).to_arel(table, klass))
         else
           super
         end
@@ -203,7 +341,7 @@ module ActiveRecord
 
       def having(opts = nil, *rest, &block)
         if block
-          super(evaluate_block(&block).to_arel(table))
+          super(evaluate_block(&block).to_arel(table, klass))
         else
           super
         end
@@ -230,9 +368,8 @@ module ActiveRecord
       end
 
       # A symbol names a table, which ActiveRecord's own from only takes as a
-      # string.  With `as` it is selected under another name, which is how a
-      # CTE stands in for the model's own table:
-      # with_recursive(tree: [...]).from(:tree, as: :nodes)
+      # string.  With `as` it is selected under another name; when that name
+      # is the model's own, from_cte says the same thing without repeating it.
       def from(value, subquery_name = nil, as: nil)
         unless value.is_a?(Symbol)
           if as
@@ -245,10 +382,76 @@ module ActiveRecord
         super(arel_table, subquery_name)
       end
 
+      # Selects a CTE in place of the model's own table.  The alias is not a
+      # choice -- ActiveRecord keeps qualifying columns with the table name,
+      # so the model's is the only name that works -- which is why it is
+      # taken from the model rather than asked for:
+      # with_recursive(tree: [...]).from_cte(:tree)
+      #
+      # The name is checked against what `with` declares, so that a typo is
+      # not a query against a table nobody has.  Checked when the SQL is
+      # built, since the CTE may be declared after this in the chain, or by a
+      # scope merged into it.
+      def from_cte(name)
+        unless name.is_a?(Symbol)
+          raise ArgumentError, "from_cte takes the CTE's name as a symbol"
+        end
+        relation = from(name, as: klass.table_name)
+        relation.from_cte_value = name
+        relation
+      end
+
+      def from_cte_value
+        @values[:from_cte]
+      end
+
+      def from_cte_value=(name)
+        assert_modifiable!
+        @values[:from_cte] = name
+      end
+
+      # DISTINCT ON (...), which keeps the first row of each group the order
+      # brings up.  PostgreSQL has it and the others do not; Arel carries the
+      # node and refuses to write it elsewhere, the way it does a regexp, so
+      # there is nothing for this to check:
+      #
+      #   Post.distinct_on { :author }.order { [:author, :likes.desc] }
+      #
+      # The portable shape is a row_number window in a subquery, which the
+      # README shows.
+      def distinct_on(*columns, &block)
+        spawn.distinct_on!(*columns, &block)
+      end
+
+      def distinct_on!(*columns, &block)
+        columns = Array(evaluate_block(&block)) if block
+        if columns.empty?
+          raise ArgumentError, "distinct_on needs a column or an expression"
+        end
+        self.distinct_on_values += columns
+        self
+      end
+
+      # ActiveRecord generates these for the values it knows about; this one
+      # is ours, and lives in the same place so that it survives a spawn.
+      def distinct_on_values
+        @values.fetch(:distinct_on, ActiveRecord::QueryMethods::FROZEN_EMPTY_ARRAY)
+      end
+
+      def distinct_on_values=(columns)
+        assert_modifiable!
+        @values[:distinct_on] = columns
+      end
+
       # `as` names the table within the query, which is what makes a self
       # join expressible: joins(:employees, as: :managers) { ... }.
-      def joins(*args, as: nil, &block)
-        if block
+      #
+      # `lateral` joins a relation instead of a table, and lets it see the row
+      # being joined to -- the top few rows of each group, and the like.
+      def joins(*args, as: nil, lateral: false, &block)
+        if lateral
+          super(build_lateral_join(args.first, Arel::Nodes::InnerJoin, as, &block))
+        elsif block
           super(build_join_node(args.first, Arel::Nodes::InnerJoin, as, &block))
         else
           reject_join_alias(as)
@@ -256,8 +459,10 @@ module ActiveRecord
         end
       end
 
-      def left_outer_joins(*args, as: nil, &block)
-        if block
+      def left_outer_joins(*args, as: nil, lateral: false, &block)
+        if lateral
+          joins(build_lateral_join(args.first, Arel::Nodes::OuterJoin, as, &block))
+        elsif block
           joins(build_join_node(args.first, Arel::Nodes::OuterJoin, as, &block))
         else
           reject_join_alias(as)
@@ -267,6 +472,31 @@ module ActiveRecord
 
       private
 
+      def build_arel(...)
+        check_from_cte
+        arel = super
+        unless distinct_on_values.empty?
+          arel.distinct_on(distinct_on_values.map {|column| to_arel_field(column) })
+        end
+        arel
+      end
+
+      # Only when every `with` is one this can read the names out of; anything
+      # else and there is nothing to be sure about, so nothing is said.
+      def check_from_cte
+        name = from_cte_value
+        return unless name
+        return unless with_values.all? {|value| value.is_a?(::Hash) }
+
+        declared = with_values.flat_map {|value| value.keys.map(&:to_sym) }
+        return if declared.include?(name)
+
+        raise ArgumentError,
+          "from_cte(#{name.inspect}) names no CTE; " +
+          (declared.empty? ? "this query declares none" :
+                             "this query declares #{declared.map(&:inspect).join(', ')}")
+      end
+
       def evaluate_block(&block)
         refined_block = block.refined(ActiveRecord::Refined::BlockSyntax)
         BlockContext.new(klass).instance_exec(&refined_block)
@@ -274,7 +504,7 @@ module ActiveRecord
 
       def to_arel_field(node)
         case node
-        when AST::Node then node.to_arel(table)
+        when AST::Node then node.to_arel(table, klass)
         when Symbol then table[node]
         else node
         end
@@ -285,11 +515,106 @@ module ActiveRecord
         raise ArgumentError, "as: needs a block to write the ON clause with"
       end
 
+      # The subquery is written out rather than handed over as a tree: Arel has
+      # a LATERAL node but only PostgreSQL's visitor writes it, and MySQL can
+      # read what it will not write.  Without a block the join is ON TRUE,
+      # which is the usual shape -- what the subquery is allowed to see is
+      # what makes it lateral, and that is said inside it.
+      def build_lateral_join(relation, join_class, alias_name, &block)
+        unless relation.is_a?(ActiveRecord::Relation)
+          raise ArgumentError, "a lateral join takes a relation to join against"
+        end
+        unless alias_name
+          raise ArgumentError, "a lateral join needs a name: joins(..., as: :top)"
+        end
+        check_lateral_support
+
+        aliased = Arel::Nodes::TableAlias.new(
+          Arel::Nodes::SqlLiteral.new("LATERAL (#{relation.to_sql})"), alias_name)
+        on = block ? evaluate_block(&block).to_arel(table, klass) : Arel::Nodes::True.new
+        join_class.new(aliased, Arel::Nodes::On.new(on))
+      end
+
+      # PostgreSQL has LATERAL and so does MySQL, from 8.0.14.  SQLite has
+      # none, and neither has MariaDB, which answers to the same adapter as
+      # MySQL.  An adapter nobody has classified is left to say for itself.
+      def check_lateral_support
+        case AST.adapter_family(klass)
+        when :sqlite
+          refuse_lateral('sqlite3')
+        when :mysql
+          refuse_lateral('MariaDB') if klass.with_connection {|c| c.mariadb? }
+        end
+      end
+
+      def refuse_lateral(database)
+        raise NotImplementedError, "a lateral join has no equivalent on #{database}"
+      end
+
       def build_join_node(target_table, join_class, alias_name, &block)
         ast = evaluate_block(&block)
         arel_table = Arel::Table.new(target_table)
         arel_table = arel_table.alias(alias_name) if alias_name
-        join_class.new(arel_table, Arel::Nodes::On.new(ast.to_arel(table)))
+        join_class.new(arel_table, Arel::Nodes::On.new(ast.to_arel(table, klass)))
+      end
+    end
+
+    # The writing statements, which live on Relation rather than in
+    # QueryMethods.  What a block adds here is the one thing their arguments
+    # cannot carry: a value worked out from the row rather than given.
+    module Writes
+      # `update_all(likes: :likes)` sets the column to the symbol; the block
+      # reads a symbol as the column it names, as every other block here does,
+      # which is what lets the new value be built from the old:
+      #
+      #   Post.where { ... }.update_all { { likes: :likes + 1 } }
+      def update_all(updates = nil, &block)
+        return super(updates) unless block
+        if updates
+          raise ArgumentError, "update_all takes updates or a block, not both"
+        end
+        result = evaluate_block(&block)
+        unless result.is_a?(::Hash)
+          raise ArgumentError, "the block gives update_all a hash of column => value"
+        end
+        super(result.transform_values {|value| to_arel_field(value) })
+      end
+
+      # upsert_all's on_duplicate takes SQL text and nothing else, so this is
+      # the one place the DSL writes the SQL out itself rather than handing
+      # Arel a tree.  `excluded` is the row that could not be inserted:
+      #
+      #   Post.upsert_all(rows, unique_by: :title) {
+      #     { likes: :likes + excluded(:likes) }
+      #   }
+      def upsert_all(attributes, **options, &block)
+        return super(attributes, **options) unless block
+        if options.key?(:on_duplicate)
+          raise ArgumentError, "upsert_all takes on_duplicate: or a block, not both"
+        end
+        result = evaluate_block(&block)
+        unless result.is_a?(::Hash)
+          raise ArgumentError, "the block gives upsert_all a hash of column => value"
+        end
+        if result.empty?
+          raise ArgumentError, "the block gives upsert_all at least one column to set"
+        end
+        super(attributes, on_duplicate: Arel.sql(set_clause(result)), **options)
+      end
+
+      private
+
+      # The left of each assignment is the column being written, which is bare
+      # -- the statement is already about one table -- and the right is the
+      # expression, compiled here because a string is what on_duplicate reads.
+      def set_clause(updates)
+        klass.with_connection do |connection|
+          updates.map do |column, value|
+            expression = connection.visitor.compile(
+              to_arel_field(value), Arel::Collectors::SQLString.new)
+            "#{connection.quote_column_name(column)}=#{expression}"
+          end.join(', ')
+        end
       end
     end
   end

data/lib/activerecord-refined/version.rb

@@ -1,5 +1,5 @@
 module Activerecord
   module Refined
-    VERSION = '0.5.0'
+    VERSION = '0.6.0'
   end
 end

data/lib/activerecord-refined.rb

@@ -5,3 +5,10 @@ require 'active_record/refined/ast'
 require 'active_record/refined'
 
 ActiveRecord::QueryMethods.prepend ActiveRecord::Refined::QueryMethods
+
+# update_all and its kind are Relation's own rather than QueryMethods'.
+ActiveRecord::Relation.prepend ActiveRecord::Refined::Writes
+
+# The methods above are ActiveRecord's own, so a model already forwards them
+# to its relation.  These two are new, and have to be added to that list.
+ActiveRecord::Base.singleton_class.delegate :from_cte, :distinct_on, to: :all