activerecord-refined 0.9.0 → 0.10.0

data/lib/active_record/refined/dialect.rb

@@ -0,0 +1,340 @@
+# frozen_string_literal: true
+
+require "concurrent/map"
+
+module ActiveRecord
+  module Refined
+    # One class per family of SQL spellings, resolved from the model's adapter
+    # and asked, rather than branched on, for whatever a query builds
+    # differently from one database to the next.  The base is the standard
+    # spelling an unclassified adapter keeps; each subclass overrides only
+    # where its family departs from it.
+    #
+    # The families are loaded as they are met: an application on PostgreSQL
+    # never loads the Oracle class, whose adapter it will never resolve to.
+    class Dialect
+      autoload :Sqlite, "active_record/refined/dialect/sqlite"
+      autoload :Postgresql, "active_record/refined/dialect/postgresql"
+      autoload :MysqlCompat, "active_record/refined/dialect/mysql_compat"
+      autoload :Mysql, "active_record/refined/dialect/mysql"
+      autoload :Mariadb, "active_record/refined/dialect/mariadb"
+      autoload :Oracle, "active_record/refined/dialect/oracle"
+      autoload :SqlServer, "active_record/refined/dialect/sql_server"
+
+      # One instance per family, shared across threads.  The dialect carries no
+      # state, so sharing is safe; the map is a concurrent one so that building
+      # the instance the first time is too, on a Ruby whose threads run in
+      # parallel as much as on one whose do not.
+      @instances = Concurrent::Map.new
+
+      @registry = Concurrent::Map.new
+
+      class << self
+        # Names an adapter's dialect.  An adapter's gem, or an application,
+        # registers its own -- a Dialect subclass overriding only where its
+        # family departs from the standard:
+        #
+        #   ActiveRecord::Refined::Dialect.register("exampledb", ExampleDialect)
+        #
+        # A block registers an adapter whose dialect only the connection can
+        # name, as mysql2's is either MySQL's or MariaDB's: it receives the
+        # model and returns the class.  The built-in families register with
+        # blocks too, which is what leaves each autoloaded until an adapter
+        # first resolves to it.
+        def register(adapter, dialect = nil, &block)
+          unless dialect || block
+            raise ArgumentError, "register takes a dialect class or a block"
+          end
+          @registry[adapter.to_s] = dialect || block
+        end
+
+        # The dialect a model's queries are built for.  An adapter nobody has
+        # registered keeps the standard spellings and is left to say for
+        # itself what it cannot do.  The instances are cached by class rather
+        # than by adapter, so a re-registration takes effect on the next
+        # query.
+        def for(model)
+          klass = class_for(model.connection_db_config.adapter, model)
+          @instances.compute_if_absent(klass) { klass.new }
+        end
+
+        private
+          def class_for(adapter, model)
+            entry = @registry[adapter] or return Dialect
+            entry.is_a?(Proc) ? entry.call(model) : entry
+          end
+      end
+
+      register("sqlite3") { Sqlite }
+      register("postgresql") { Postgresql }
+      register("postgis") { Postgresql }
+      register("pglite") { Postgresql }
+      # MariaDB and MySQL answer to one adapter apiece and part company only
+      # at the connection, so those two are told apart by asking it.
+      %w[mysql2 trilogy].each do |adapter|
+        register(adapter) do |model|
+          model.with_connection { |connection| connection.mariadb? } ? Mariadb : Mysql
+        end
+      end
+      register("oracle_enhanced") { Oracle }
+      register("sqlserver") { SqlServer }
+
+      # --- Capabilities.  The standard has them; a family without one says so
+      #     by overriding to false, and the block raises where it is asked for.
+
+      # The scalar and datetime functions a family spells differently, or has
+      # none of.  A name it does not list it spells like the method, upper
+      # cased; a nil says it has no equivalent, and the block raises.  The base
+      # -- an unclassified adapter -- keeps every standard name.
+      FUNCTIONS = {}.freeze
+
+      def function_name(name, model)
+        functions = self.class::FUNCTIONS
+        return name.to_s.upcase unless functions.key?(name)
+        functions.fetch(name) ||
+          raise(NotImplementedError,
+                "#{name} has no equivalent on #{model.connection_db_config.adapter}")
+      end
+
+      def datetime_precision_supported? = true
+      def extract_supported? = true
+      def quantifiers_supported? = true
+      def full_outer_join_supported? = true
+
+      # The FILTER clause, which restricts an aggregate to the rows a condition
+      # holds for.  A family without it gets the CASE that means the same,
+      # built by the aggregate node.
+      def filter_supported? = true
+
+      # A lateral join is allowed to stand unless the family refuses it here.
+      def check_lateral(_model); end
+
+      # --- Expressions built differently per family.
+
+      # BIT_COUNT of a number.  The standard has no equivalent; the families
+      # that do override.
+      def bit_count(_expr, model)
+        raise NotImplementedError,
+          "bit_count has no equivalent on #{model.connection_db_config.adapter}"
+      end
+
+      # The row an upsert could not insert.  PostgreSQL and SQLite name it;
+      # MySQL spells the same thing VALUES(column) and overrides.
+      def excluded(column, _model)
+        AST::Column.new(:excluded, column)
+      end
+
+      # true? / false? and their negations.  The standard spells them with the
+      # boolean IS [NOT] TRUE/FALSE, which keeps a NULL out of the plain form
+      # and in of the negation; a family without a boolean type overrides.
+      def truth_value(operand, value, negated, _model)
+        literal = value ? Arel::Nodes::True.new : Arel::Nodes::False.new
+        Arel::Nodes::InfixOperation.new(negated ? "IS NOT" : "IS", operand, literal)
+      end
+
+      # COLLATE, which every family spells `expr COLLATE name` -- the name a
+      # bare identifier, no Arel node for it.  Written bare it has to be a
+      # plain one, so it is checked here; PostgreSQL quotes it and widens what
+      # it takes, overriding.  PostgreSQL also folds an unquoted name to lower
+      # case, where its built-in names are upper -- "C", "POSIX" -- another
+      # reason it quotes rather than inheriting this.
+      def collate(operand, name, _model)
+        AST.check_name(name, AST::COLLATION_NAME, "collation name")
+        Arel::Nodes::InfixOperation.new(
+          "COLLATE", operand, Arel::Nodes::SqlLiteral.new(name))
+      end
+
+      # A date moved by a duration: `:due_on + 3.days`.  The standard adds an
+      # interval literal, `x + INTERVAL '3' DAY`, which PostgreSQL and the
+      # MySQL family both read; SQLite, SQL Server and Oracle each spell the
+      # move their own way and override.  The amount is a whole number and
+      # the unit one of six names, both checked by the node, so both are
+      # written into the SQL as they are.  date_only says the operand is a
+      # date rather than a datetime, which only SQLite has to be told.
+      def add_interval(date, amount, unit, subtract, _date_only)
+        interval = Arel::Nodes::SqlLiteral.new("INTERVAL '#{amount}' #{unit.to_s.upcase}")
+        Arel::Nodes::Grouping.new(
+          Arel::Nodes::InfixOperation.new(subtract ? :- : :+, date, interval))
+      end
+
+      # XOR, which no two families spell alike.  The standard is the two
+      # operations it is made of, naming each operand twice, as SQLite needs;
+      # PostgreSQL and the MySQL family have an operator and override.
+      def bitwise_xor(left, right)
+        Arel::Nodes::Subtraction.new(
+          Arel::Nodes::Grouping.new(Arel::Nodes::BitwiseOr.new(left, right)),
+          Arel::Nodes::Grouping.new(Arel::Nodes::BitwiseAnd.new(left, right)))
+      end
+
+      # --- Reading JSON.  The defaults are what an unclassified adapter gets,
+      #     which is SQLite's operators for a path and its functions elsewhere.
+
+      # dig / dig_text.  The standard is SQLite's -> and ->>, whose ->> keeps
+      # the value's type, so dig_text casts to text for a portable comparison.
+      def json_path(document, dollar_path, _steps, json_value, _model)
+        extracted = Arel::Nodes::InfixOperation.new(
+          json_value ? :"->" : :"->>", document, Arel::Nodes.build_quoted(dollar_path))
+        return extracted if json_value
+        Arel::Nodes::NamedFunction.new(
+          "CAST", [Arel::Nodes::As.new(extracted, Arel::Nodes::SqlLiteral.new("text"))])
+      end
+
+      # A Ruby value on the JSON side of a comparison belongs to a JSON type;
+      # a family without one refuses it.
+      def json_literal(_json, model)
+        raise NotImplementedError,
+          "a JSON comparison has no equivalent on " \
+          "#{model.connection_db_config.adapter}; dig_text gives the value"
+      end
+
+      def json_contains(_document, _json, model)
+        raise NotImplementedError,
+          "contains? has no equivalent on #{model.connection_db_config.adapter}"
+      end
+
+      def json_has_key(document, _name, path, _model)
+        Arel::Nodes::NamedFunction.new("json_type", [document, path]).not_eq(nil)
+      end
+
+      def json_keys(document, _model)
+        Arel::Nodes::NamedFunction.new("JSON_KEYS", [document])
+      end
+
+      # --- Writing JSON.  A Ruby document or boolean has to be told apart from
+      #     a bare scalar, and embedded as the JSON it spells.
+
+      def json_document_value?(value)
+        value.is_a?(::Hash) || value.is_a?(::Array) || value == true || value == false
+      end
+
+      # A Ruby document or boolean written where one of the JSON functions
+      # wants JSON.  The standard marks the literal with JSON_EXTRACT($);
+      # SQLite has json() and Oracle FORMAT JSON, and both override.
+      def json_argument(value, _model)
+        json = Arel::Nodes.build_quoted(JSON.generate(value))
+        Arel::Nodes::NamedFunction.new("JSON_EXTRACT", [json, Arel::Nodes.build_quoted("$")])
+      end
+
+      # bury: setting a value at a path.  The standard is JSON_SET; PostgreSQL
+      # has jsonb_set and Oracle JSON_TRANSFORM, and both override.
+      def json_set(document, _steps, dollar_path, value, expression, model)
+        Arel::Nodes::NamedFunction.new(
+          "JSON_SET",
+          [document, Arel::Nodes.build_quoted(dollar_path),
+           json_set_value(value, expression, model)])
+      end
+
+      # except: removing keys.  The standard removes a path apiece with
+      # JSON_REMOVE; PostgreSQL subtracts an array of keys and Oracle removes
+      # through JSON_TRANSFORM, and both override.
+      def json_remove(document, dollar_paths, _steps, _model)
+        Arel::Nodes::NamedFunction.new(
+          "JSON_REMOVE",
+          [document, *dollar_paths.map { |path| Arel::Nodes.build_quoted(path) }])
+      end
+
+      # json_array / json_object built in the row.  The standard says JSON_ARRAY
+      # and JSON_OBJECT with the values (and keys alternating); PostgreSQL has
+      # the jsonb_build_* pair and Oracle a keyword syntax, and both override.
+      def json_build(kind, keys, args, _model)
+        Arel::Nodes::NamedFunction.new(
+          kind == :array ? "JSON_ARRAY" : "JSON_OBJECT", json_build_body(kind, keys, args))
+      end
+
+      # A document or boolean built into json_array/json_object.  The standard
+      # marks it JSON as bury does; PostgreSQL casts to jsonb and overrides.
+      def json_build_argument(value, model)
+        json_argument(value, model)
+      end
+
+      # json_arrayagg / json_objectagg gather rows into a document.  The
+      # standard names are JSON_ARRAYAGG and JSON_OBJECTAGG; SQLite and
+      # PostgreSQL have their own and override.
+      def json_aggregate_name(kind)
+        kind == :arrayagg ? "JSON_ARRAYAGG" : "JSON_OBJECTAGG"
+      end
+
+      # These two keep a NULL as JSON null rather than passing over it, so the
+      # CASE that stands in for FILTER would leave one in the document; a
+      # family without FILTER for them refuses it.
+      def json_aggregate_filter_supported? = true
+
+      # A family that cannot take these two as window functions refuses one.
+      def check_json_aggregate_window(_source, _model); end
+
+      # string_agg: the strings of a group joined into one.  The standard's is
+      # LISTAGG(x, ', ') WITHIN GROUP (ORDER BY ...), which Oracle reads, and
+      # the ORDER BY is not optional there: an aggregate asked for no order
+      # is given the values' own, which costs the caller nothing to have.
+      # PostgreSQL and SQLite carry the ORDER BY inside the call, SQL Server
+      # takes the WITHIN GROUP only when there is an order, and the MySQL
+      # family has GROUP_CONCAT; every one of them overrides.  `string` says
+      # the operand is a column declared one, which PostgreSQL alone asks.
+      def string_agg(operand, separator, orders, _string, model)
+        orders = [operand] if orders.empty?
+        Arel.sql("LISTAGG(#{compile(operand, model)}, #{quote(separator, model)}) " \
+                 "WITHIN GROUP (ORDER BY #{compile_list(orders, model)})")
+      end
+
+      # A family that cannot take string_agg as a window function refuses one.
+      def check_string_aggregate_window(_model); end
+
+      # A JSON value in an IN list or a range is compared per element on the
+      # MySQL family, which overrides; the standard leaves it to the IN.
+      def json_list_by_element? = false
+
+      # --- Grouping.  GROUPING SETS, ROLLUP and CUBE, which the standard has
+      #     none of; PostgreSQL has all three and the MySQL family rollup alone.
+
+      def grouping_supported?(_kind) = false
+
+      # The MySQL family spells rollup WITH ROLLUP, trailing the group list
+      # rather than wrapping a list of its own, and overrides.
+      def grouping_by_with_rollup? = false
+
+      protected
+        # The value beside a path in JSON_SET: an expression as it is, a
+        # document or boolean as JSON, a bare scalar quoted.
+        def json_set_value(value, expression, model)
+          return expression if expression
+          return Arel::Nodes.build_quoted(value) unless json_document_value?(value)
+          json_argument(value, model)
+        end
+
+        # The arguments to JSON_ARRAY/JSON_OBJECT: an array's values as they
+        # are, an object's keys alternating with them.
+        def json_build_body(kind, keys, args)
+          return args if kind == :array
+          keys.zip(args).flat_map { |key, arg| [Arel::Nodes.build_quoted(key), arg] }
+        end
+
+        # The name(x, ', ' ORDER BY ...) shape of string_agg, PostgreSQL's and
+        # SQLite's; a node while there is no order, since Arel has one for
+        # that much.
+        def string_agg_call(name, operand, separator, orders, model)
+          if orders.empty?
+            return Arel::Nodes::NamedFunction.new(
+              name, [operand, Arel::Nodes.build_quoted(separator)])
+          end
+          Arel.sql("#{name}(#{compile(operand, model)}, #{quote(separator, model)} " \
+                   "ORDER BY #{compile_list(orders, model)})")
+        end
+
+        # The connection's own visitor and quoting, for the families that write
+        # a call out because its grammar no Arel node carries.
+        def compile(node, model)
+          model.with_connection { |connection| connection.visitor.compile(node) }
+        end
+
+        def compile_list(nodes, model)
+          model.with_connection do |connection|
+            nodes.map { |node| connection.visitor.compile(node) }.join(", ")
+          end
+        end
+
+        def quote(value, model)
+          model.with_connection { |connection| connection.quote(value) }
+        end
+    end
+  end
+end