clickhouse-activerecord 1.6.6 → 1.7.0

data/lib/active_record/connection_adapters/clickhouse/statement/response_processor.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'tempfile'
+
 module ActiveRecord
   module ConnectionAdapters
     module Clickhouse
@@ -52,7 +54,7 @@ module ActiveRecord
 
           # @return [String, Hash, Array]
           def process_successful_response
-            raise_generic!(@sql) if @body.include?('DB::Exception') && @body.match?(DB_EXCEPTION_REGEXP)
+            raise_database_error!(@sql) if @body.include?('DB::Exception') && @body.match?(DB_EXCEPTION_REGEXP)
 
             format_body_response
           end
@@ -101,14 +103,17 @@ module ActiveRecord
             JSON.parse(payload, decimal_class: BigDecimal)
           end
 
-          def raise_database_error!
+          def raise_database_error!(sql = nil)
             case @body
             when /DB::Exception:.*\(UNKNOWN_DATABASE\)/
               raise ActiveRecord::NoDatabaseError
             when /DB::Exception:.*\(DATABASE_ALREADY_EXISTS\)/
               raise ActiveRecord::DatabaseAlreadyExists
+            when /DB::Exception:.*\(TIMEOUT_EXCEEDED\)/
+              # server-side cancellation, vs. ActiveRecord::AdapterTimeout (client gave up)
+              raise ActiveRecord::StatementTimeout, "Response code: #{@raw_response.code}:\n#{@body}#{"\nQuery: #{sql}" if sql}"
             else
-              raise_generic!
+              raise_generic!(sql)
             end
           end
 

data/lib/active_record/connection_adapters/clickhouse/table_definition.rb

@@ -41,7 +41,7 @@ module ActiveRecord
           unsigned = options[:unsigned]
           unsigned = true if unsigned.nil?
 
-          kind = :uint32 # default
+          kind = unsigned ? :uint32 : :int32 # default
 
           if options[:limit]
             if unsigned
@@ -63,6 +63,12 @@ module ActiveRecord
           args.each { |name| column(name, kind, **options.except(:limit, :unsigned)) }
         end
 
+        def float(*args, **options)
+          kind = options[:limit] == 8 ? :float64 : :float
+
+          args.each { |name| column(name, kind, **options.except(:limit)) }
+        end
+
         def datetime(*args, **options)
           kind = :datetime
 

data/lib/active_record/connection_adapters/clickhouse_adapter.rb

@@ -2,6 +2,7 @@
 
 require 'arel/visitors/clickhouse'
 require 'arel/nodes/final'
+require 'arel/nodes/final_table'
 require 'arel/nodes/grouping_sets'
 require 'arel/nodes/settings'
 require 'arel/nodes/using'
@@ -11,6 +12,7 @@ require 'active_record/connection_adapters/clickhouse/oid/date'
 require 'active_record/connection_adapters/clickhouse/oid/date_time'
 require 'active_record/connection_adapters/clickhouse/oid/big_integer'
 require 'active_record/connection_adapters/clickhouse/oid/map'
+require 'active_record/connection_adapters/clickhouse/oid/json'
 require 'active_record/connection_adapters/clickhouse/oid/uuid'
 require 'active_record/connection_adapters/clickhouse/column'
 require 'active_record/connection_adapters/clickhouse/quoting'
@@ -20,6 +22,7 @@ require 'active_record/connection_adapters/clickhouse/statement'
 require 'active_record/connection_adapters/clickhouse/table_definition'
 require 'net/http'
 require 'openssl'
+require 'uri'
 
 module ActiveRecord
   class Base
@@ -28,10 +31,22 @@ module ActiveRecord
       def clickhouse_connection(config)
         config = config.symbolize_keys
 
+        if config[:url]
+          url_config = ConnectionAdapters::ClickhouseAdapter.parse_clickhouse_url(config.delete(:url))
+          config = url_config.merge(config)
+        end
+
         unless config.key?(:database)
           raise ArgumentError, 'No database specified. Missing argument: database.'
         end
 
+        if config[:http_auth]
+          unless ConnectionAdapters::Clickhouse::SchemaStatements::HTTP_AUTH_TYPES.include?(config[:http_auth]&.to_sym)
+            raise ArgumentError, "Unknown :http_auth mode #{config[:http_auth].inspect}. " \
+              + "Use one of #{ConnectionAdapters::Clickhouse::SchemaStatements::HTTP_AUTH_TYPES}."
+          end
+        end
+
         ConnectionAdapters::ClickhouseAdapter.new(config)
       end
     end
@@ -52,6 +67,8 @@ module ActiveRecord
   module ModelSchema
     module ClassMethods
       delegate :final, :final!,
+               :joins_final, :joins_final!,
+               :left_joins_final, :left_joins_final!,
                :group_by_grouping_sets, :group_by_grouping_sets!,
                :settings, :settings!,
                :window, :window!,
@@ -90,6 +107,7 @@ module ActiveRecord
         integer: { name: 'UInt32' },
         big_integer: { name: 'UInt64' },
         float: { name: 'Float32' },
+        float64: { name: 'Float64' },
         decimal: { name: 'Decimal' },
         datetime: { name: 'DateTime' },
         datetime64: { name: 'DateTime64' },
@@ -119,8 +137,16 @@ module ActiveRecord
 
       include Clickhouse::SchemaStatements
 
+      # our `execute` shadows the wrapper `QueryCache` installs on `AbstractAdapter`
+      ActiveRecord::ConnectionAdapters::QueryCache.dirties_query_cache(self, :execute)
+
       # Initializes and connects a Clickhouse adapter.
       def initialize(config_or_deprecated_connection, deprecated_logger = nil, deprecated_connection_options = nil, deprecated_config = nil)
+        if config_or_deprecated_connection.is_a?(Hash) && config_or_deprecated_connection[:url]
+          config_or_deprecated_connection = config_or_deprecated_connection.dup
+          url_config = self.class.parse_clickhouse_url(config_or_deprecated_connection.delete(:url))
+          config_or_deprecated_connection = url_config.merge(config_or_deprecated_connection)
+        end
         super
         if @config[:connection]
           connection = {
@@ -132,7 +158,9 @@ module ActiveRecord
             host: @config[:host] || 'localhost',
             port: port,
             ssl: @config[:ssl].present? ? @config[:ssl] : port == 443,
+            insecure: @config.fetch(:insecure, true),
             sslca: @config[:sslca],
+            open_timeout: @config[:open_timeout],
             read_timeout: @config[:read_timeout],
             write_timeout: @config[:write_timeout],
             keep_alive_timeout: @config[:keep_alive_timeout]
@@ -140,9 +168,16 @@ module ActiveRecord
         end
         @connection_parameters = connection
 
-        @connection_config = { user: @config[:username], password: @config[:password], database: @config[:database] }.compact
+        @connection_config = {
+          user: @config[:username],
+          password: @config[:password],
+          database: @config[:database],
+          max_execution_time: @config[:max_execution_time],
+          cancel_http_readonly_queries_on_client_close: @config[:cancel_http_readonly_queries_on_client_close],
+        }.compact
         @debug = @config[:debug] || false
-        @response_format = @config[:format] || DEFAULT_RESPONSE_FORMAT
+        @default_response_format = @config[:format] || DEFAULT_RESPONSE_FORMAT
+        @http_auth = @config[:http_auth]&.to_sym
 
         @prepared_statements = false
 
@@ -185,11 +220,55 @@ module ActiveRecord
         !native_database_types[type].nil?
       end
 
+      # Rails appends the limit to the native type name (e.g. "Float32(8)"), which is not valid in ClickHouse.
+      # Resolve the float width by limit here so that add_column / change_column behave like TableDefinition#float.
+      def type_to_sql(type, limit: nil, precision: nil, scale: nil, **)
+        return native_database_types[limit == 8 ? :float64 : :float][:name] if type.to_s == 'float'
+
+        super
+      end
+
       def supports_indexes_in_create?
         true
       end
 
       class << self
+        def parse_clickhouse_url(url)
+          uri = URI.parse(url)
+          config = {}
+
+          config[:host]     = uri.host                                    if uri.host
+          config[:port]     = uri.port                                    if uri.port
+          config[:username] = URI.decode_www_form_component(uri.user)     if uri.user
+          config[:password] = URI.decode_www_form_component(uri.password) if uri.password
+
+          if uri.path && uri.path.length > 1
+            config[:database] = uri.path.delete_prefix('/')
+          end
+
+          if uri.query
+            URI.decode_www_form(uri.query).each do |key, value|
+              case key
+              when 'ssl'                then config[:ssl]                = (value == 'true')
+              when 'debug'              then config[:debug]              = (value == 'true')
+              when 'insecure'           then config[:insecure]           = (value == 'true')
+              when 'open_timeout'       then config[:open_timeout]       = value.to_i
+              when 'read_timeout'       then config[:read_timeout]       = value.to_i
+              when 'write_timeout'      then config[:write_timeout]      = value.to_i
+              when 'keep_alive_timeout' then config[:keep_alive_timeout] = value.to_i
+              when 'http_auth'          then config[:http_auth]          = value
+              when 'cluster_name'       then config[:cluster_name]       = value
+              when 'sslca'              then config[:sslca]              = value
+              when 'max_execution_time' then config[:max_execution_time] = value.to_i
+              when 'cancel_http_readonly_queries_on_client_close'
+                config[:cancel_http_readonly_queries_on_client_close] = (value == 'true')
+              end
+            end
+          end
+
+          config
+        end
+
         def extract_limit(sql_type) # :nodoc:
           case sql_type
             when /(Nullable)?\(?String\)?/
@@ -204,6 +283,10 @@ module ActiveRecord
               8
             when /(Nullable)?\(?U?Int128\)?/
               16
+            when /(Nullable)?\(?Float32\)?/
+              nil
+            when /(Nullable)?\(?Float64\)?/
+              8
             else
               super
           end
@@ -254,7 +337,7 @@ module ActiveRecord
             Clickhouse::OID::Map.new(sql_type)
           end
 
-          m.register_type %r(JSON)i, ActiveRecord::Type::Json.new
+          m.register_type(%r(JSON)) { Clickhouse::OID::Json.new }
         end
       end
 
@@ -304,7 +387,7 @@ module ActiveRecord
         end
 
         pk = table_structure(table_name).first
-        return ['id'] if pk.present? && pk[0] == 'id'
+        return ['id'] if pk.present? && pk.name == 'id'
         []
       end
 
@@ -426,9 +509,9 @@ module ActiveRecord
       end
 
       def change_column_null(table_name, column_name, null, default = nil)
-        structure = table_structure(table_name).select{|v| v[0] == column_name.to_s}.first
+        structure = table_structure(table_name).find { |col| col.name == column_name.to_s }
         raise "Column #{column_name} not found in table #{table_name}" if structure.nil?
-        change_column table_name, column_name, structure[1].gsub(/(Nullable\()?(.*?)\)?/, '\2'), {null: null, default: default}.compact
+        change_column table_name, column_name, structure.sql_type.gsub(/(Nullable\()?(.*?)\)?/, '\2'), {null: null, default: default}.compact
       end
 
       def change_column_default(table_name, column_name, default)
@@ -539,8 +622,13 @@ module ActiveRecord
 
       protected
 
-      def last_inserted_id(result)
-        result
+      def last_inserted_id(_result)
+        # Rails 7.1 persistence.rb:1258:
+        # _write_attribute(column, value)  # wrote true directly — ugly but no crash
+
+        # Rails 8.0 persistence.rb:933:
+        # _write_attribute(column, type_for_attribute(column).deserialize(value))  # now deserializes first
+        nil
       end
 
       def change_column_for_alter(table_name, column_name, type, **options)
@@ -552,9 +640,15 @@ module ActiveRecord
       private
 
       def connect
-        @connection = @connection_parameters[:connection] || Net::HTTP.start(@connection_parameters[:host], @connection_parameters[:port], use_ssl: @connection_parameters[:ssl], verify_mode: OpenSSL::SSL::VERIFY_NONE)
-
-        @connection.ca_file = @connection_parameters[:ca_file] if @connection_parameters[:ca_file]
+        @connection = @connection_parameters[:connection] || Net::HTTP.start(
+          @connection_parameters[:host],
+          @connection_parameters[:port],
+          use_ssl: @connection_parameters[:ssl],
+          verify_mode: @connection_parameters[:insecure] ? OpenSSL::SSL::VERIFY_NONE : OpenSSL::SSL::VERIFY_PEER,
+          **{ open_timeout: @connection_parameters[:open_timeout] }.compact
+        )
+
+        @connection.ca_file = @connection_parameters[:sslca] if @connection_parameters[:sslca]
         @connection.read_timeout = @connection_parameters[:read_timeout] if @connection_parameters[:read_timeout]
         @connection.write_timeout = @connection_parameters[:write_timeout] if @connection_parameters[:write_timeout]
 

data/lib/arel/nodes/final_table.rb

@@ -0,0 +1,10 @@
+module Arel # :nodoc: all
+  module Nodes
+    # Wraps the table source of a JOIN so the ClickHouse visitor renders
+    # `<table> FINAL ON ...` for that join. Built by
+    # ActiveRecord::Relation#joins_final, which marks the matching join
+    # sources after Arel has been constructed.
+    class FinalTable < Arel::Nodes::Unary
+    end
+  end
+end

data/lib/arel/visitors/clickhouse.rb

@@ -10,8 +10,7 @@ module Arel
       end
 
       def aggregate(name, o, collector)
-        # replacing function name for materialized view
-        if o.expressions.first && o.expressions.first != '*' && !o.expressions.first.is_a?(String) && o.expressions.first.relation&.is_view
+        if o.expressions.first && o.expressions.first != '*' && !o.expressions.first.is_a?(String) && o.expressions.first.respond_to?(:relation) && o.expressions.first.relation&.is_view
           super("#{name.downcase}Merge", o, collector)
         else
           super
@@ -89,6 +88,16 @@ module Arel
         collector
       end
 
+      # Renders the FINAL modifier for a single JOIN source, e.g.
+      # `INNER JOIN espm_binaries FINAL ON ...`. The join visitors inherited
+      # from ToSql all emit their table via `visit o.left`, so wrapping that
+      # table in a FinalTable node is enough to add FINAL to any join type.
+      def visit_Arel_Nodes_FinalTable(o, collector)
+        collector = visit o.expr, collector
+        collector << ' FINAL'
+        collector
+      end
+
       def visit_Arel_Nodes_GroupingSets(o, collector)
         collector << 'GROUPING SETS '
         grouping_array_or_grouping_element(o.expr, collector)
@@ -100,7 +109,7 @@ module Arel
         collector << "SETTINGS "
         o.expr.each_with_index do |(key, value), i|
           collector << ", " if i > 0
-          collector << key.to_s.gsub(/\W+/, "")
+          collector << sanitize_as_setting_name(key).to_s
           collector << " = "
           collector << sanitize_as_setting_value(value)
         end
@@ -146,7 +155,7 @@ module Arel
 
       def sanitize_as_setting_name(value)
         return value if Arel::Nodes::SqlLiteral === value
-        @connection.sanitize_as_setting_name(value)
+        value.to_s.gsub(/\W+/, "")
       end
 
       private

data/lib/clickhouse-activerecord/rspec.rb

@@ -5,7 +5,7 @@ RSpec.configure do |config|
     original_connection_config = ActiveRecord::Base.connection_db_config
     ActiveRecord::Base.configurations.configurations.select { |x| x.env_name == Rails.env && x.adapter == 'clickhouse' }.each do |db_config|
       ActiveRecord::Base.establish_connection(db_config)
-      ActiveRecord::Base.connection.truncate_tables(*ActiveRecord::Base.connection.tables)
+      ActiveRecord::Base.connection.execute("TRUNCATE ALL TABLES FROM #{db_config.database}")
     end
     ActiveRecord::Base.establish_connection(original_connection_config)
   end

data/lib/clickhouse-activerecord/schema_dumper.rb

@@ -99,7 +99,7 @@ module ClickhouseActiverecord
             end
           end
 
-          indexes = sql.scan(/INDEX \S+ \S+ TYPE .*? GRANULARITY \d+/)
+          indexes = sql.scan(/INDEX \S+ .+? TYPE .*? GRANULARITY \d+/)
           if indexes.any?
             tbl.puts ''
             indexes.flatten.map!(&:strip).each do |index|
@@ -154,22 +154,17 @@ module ClickhouseActiverecord
       end
     end
 
-    def schema_limit(column)
-      return nil if column.type == :float
-      super
-    end
-
     def schema_unsigned(column)
       return nil unless column.type == :integer && !simple
       (column.sql_type =~ /(Nullable)?\(?UInt\d+\)?/).nil? ? false : nil
     end
 
     def schema_array(column)
-      (column.sql_type =~ /Array\(/).nil? ? nil : true
+      column.array ? true : nil
     end
 
     def schema_map(column)
-      if column.sql_type =~ /Map\(([^,]+),\s*(Array)\)/
+      if column.sql_type =~ /Map\([^,]+,\s*Array\(/
         return :array
       end
 

data/lib/clickhouse-activerecord/tasks.rb

@@ -34,28 +34,32 @@ module ClickhouseActiverecord
       create
     end
 
-    def structure_dump(*args)
+    def structure_dump(path, *)
       establish_master_connection
 
+      # get all functions
+      functions = connection.execute("SELECT create_query FROM system.functions WHERE origin = 'SQLUserDefined' ORDER BY name")['data']
+                            .flatten
+                            .map { |function| function.gsub('\\n', "\n") }
+
       # get all tables
-      tables = connection.execute("SHOW TABLES FROM #{@configuration.database} WHERE name NOT LIKE '.inner_id.%'")['data'].flatten.map do |table|
-        connection.show_create_table(table, single_line: false).gsub("#{@configuration.database}.", '')
-      end.compact
+      table_defs = connection.execute("SHOW TABLES FROM #{@configuration.database} WHERE name NOT LIKE '.inner_id.%'")['data']
+                             .flatten
+                             .map { |name| connection.show_create_table(name, single_line: false).gsub("#{@configuration.database}.", '') }
 
-      # sort view to last
-      tables.sort_by! {|table| table.match(/^CREATE\s+(MATERIALIZED\s+)?VIEW/) ? 1 : 0}
+      # separate views from tables
+      views, tables = table_defs.partition { |sql| sql.match(/^CREATE\s+(MATERIALIZED\s+)?VIEW/) }
 
-      # get all functions
-      functions = connection.execute("SELECT create_query FROM system.functions WHERE origin = 'SQLUserDefined' ORDER BY name")['data'].flatten
+      # separate materialized from regular views
+      mat_views, views = views.partition { |sql| sql.match(/^CREATE\s+MATERIALIZED\s+VIEW/) }
 
-      # put to file
-      File.open(args.first, 'w:utf-8') do |file|
-        functions.each do |function|
-          file.puts function.gsub('\\n', "\n") + ";\n\n"
-        end
+      # sort: UDFs -> tables -> materialized views -> views
+      ordered_definitions = functions.sort + tables.sort + mat_views.sort + views.sort
 
-        tables.each do |table|
-          file.puts table + ";\n\n"
+      # puts to file
+      File.open(path, 'w:utf-8') do |file|
+        ordered_definitions.each do |sql|
+          file.puts "#{sql};\n\n"
         end
       end
     end

data/lib/clickhouse-activerecord/version.rb

@@ -1,3 +1,3 @@
 module ClickhouseActiverecord
-  VERSION = '1.6.6'
+  VERSION = '1.7.0'
 end

data/lib/clickhouse-activerecord.rb

@@ -30,5 +30,15 @@ module ClickhouseActiverecord
     Arel::Nodes::SelectStatement.prepend(CoreExtensions::Arel::Nodes::SelectStatement)
     Arel::SelectManager.prepend(CoreExtensions::Arel::SelectManager)
     Arel::Table.prepend(CoreExtensions::Arel::Table)
+
+    # Prevent TimeZoneConverter wrapping for Map OID with DateTime subtype.
+    # Map(String, DateTime) would crash with "Hash values are not supported"
+    # when TimeZoneConverter tries to convert Hash values.
+    ActiveRecord::AttributeMethods::TimeZoneConversion::ClassMethods.prepend(Module.new do
+      def create_time_zone_conversion_attribute?(name, cast_type)
+        return false if cast_type.is_a?(ActiveRecord::ConnectionAdapters::Clickhouse::OID::Map)
+        super
+      end
+    end)
   end
 end

data/lib/core_extensions/active_record/relation.rb

@@ -3,11 +3,12 @@ module CoreExtensions
     module Relation
 
       def self.prepended(base)
-        base::VALID_UNSCOPING_VALUES << :final << :settings
+        base::VALID_UNSCOPING_VALUES << :final << :settings << :joins_final
       end
 
       def reverse_order!
-        return super unless connection.is_a?(::ActiveRecord::ConnectionAdapters::ClickhouseAdapter)
+        conn = respond_to?(:lease_connection) ? lease_connection : connection
+        return super unless conn.is_a?(::ActiveRecord::ConnectionAdapters::ClickhouseAdapter)
 
         orders = order_values.uniq.reject(&:blank?)
         return super unless orders.empty? && !primary_key
@@ -90,6 +91,79 @@ module CoreExtensions
         @values.fetch(:final, nil)
       end
 
+      # Apply the FINAL modifier to one or more joined tables. Unlike #final,
+      # which only adds FINAL to the query's primary FROM table, #joins_final
+      # adds the join(s) and renders FINAL on the joined table so ClickHouse
+      # merges those rows before joining.
+      # For example:
+      #
+      #   AppControlEvent.final.joins_final(:espm_binary)
+      #   # SELECT ... FROM espm_app_control_events FINAL
+      #   #   INNER JOIN espm_binaries FINAL ON ...
+      #
+      # Each argument is an association name and is added as a join (like
+      # #joins); FINAL is then rendered on the joined table. Joins are matched
+      # by table name, so if the same table is joined more than once every join
+      # of that table receives FINAL. An
+      # <tt>ActiveRecord::ActiveRecordError</tt> will be raised if the database
+      # is not ClickHouse.
+      #
+      # @param [Array] args
+      def joins_final(*args)
+        spawn.joins_final!(*args)
+      end
+
+      # @param [Array] args
+      def joins_final!(*args)
+        check_command!('FINAL')
+        joins!(*args)
+        self.joins_final_values |= args
+        self
+      end
+
+      # Like #joins_final, but adds the join(s) as LEFT OUTER JOINs (via
+      # #left_outer_joins) and renders FINAL on the joined table. Use this when
+      # the joined rows must be preserved even with no match (e.g. an optional
+      # catalog lookup) while still merging the joined table with FINAL.
+      # For example:
+      #
+      #   AppControlEvent.left_joins_final(:espm_binary)
+      #   # SELECT ... FROM espm_app_control_events
+      #   #   LEFT OUTER JOIN espm_binaries FINAL ON ...
+      #
+      # Each argument is an association name and is added as a left outer join
+      # (like #left_outer_joins); FINAL is then rendered on the joined table.
+      # Joins are matched by table name, so if the same table is joined more
+      # than once every join of that table receives FINAL. An
+      # <tt>ActiveRecord::ActiveRecordError</tt> will be raised if the database
+      # is not ClickHouse.
+      #
+      # @param [Array] args
+      def left_joins_final(*args)
+        spawn.left_joins_final!(*args)
+      end
+
+      # @param [Array] args
+      def left_joins_final!(*args)
+        check_command!('FINAL')
+        left_outer_joins!(*args)
+        self.joins_final_values |= args
+        self
+      end
+
+      def joins_final_values
+        @values.fetch(:joins_final, ::ActiveRecord::QueryMethods::FROZEN_EMPTY_ARRAY)
+      end
+
+      def joins_final_values=(value)
+        if ::ActiveRecord::version >= Gem::Version.new('7.2')
+          assert_modifiable!
+        else
+          assert_mutability!
+        end
+        @values[:joins_final] = value
+      end
+
       # GROUPING SETS allows you to specify multiple groupings in the GROUP BY clause.
       # Whereas GROUP BY CUBE generates all possible groupings, GROUP BY GROUPING SETS generates only the specified groupings.
       # For example:
@@ -175,6 +249,50 @@ module CoreExtensions
         raise ::ActiveRecord::ActiveRecordError, cmd + ' is a ClickHouse specific query clause' unless connection.is_a?(::ActiveRecord::ConnectionAdapters::ClickhouseAdapter)
       end
 
+      # Wrap the left (table) side of every join source that matches a
+      # requested #joins_final argument in an Arel::Nodes::FinalTable so the
+      # ClickHouse visitor renders FINAL on that join. Called before
+      # +arel.final!+ so the join source is still the plain JoinSource (and not
+      # yet wrapped in the FROM-level Final node).
+      def mark_final_joins!(arel)
+        names = final_join_table_names
+        return if names.empty?
+
+        arel.join_sources.each do |join|
+          next unless join.respond_to?(:left) && join.respond_to?(:left=)
+
+          left = join.left
+          next if left.is_a?(::Arel::Nodes::FinalTable)
+          next unless final_join_match?(left, names)
+
+          join.left = ::Arel::Nodes::FinalTable.new(left)
+        end
+      end
+
+      # Resolve the #joins_final arguments to the set of table names that
+      # should carry FINAL. Association names are mapped to their table;
+      # anything else is treated as a literal table name.
+      def final_join_table_names
+        joins_final_values.flatten.filter_map do |arg|
+          case arg
+          when Symbol, String
+            reflection = klass.reflect_on_association(arg.to_sym)
+            reflection ? reflection.table_name : arg.to_s
+          end
+        end.to_set
+      end
+
+      # Does the join's table source match one of the requested FINAL names?
+      # Handles both Arel::Table (name) and Arel::Nodes::TableAlias (alias name
+      # plus the underlying relation's name).
+      def final_join_match?(left, names)
+        candidates = []
+        candidates << left.name if left.respond_to?(:name)
+        candidates << left.table_alias if left.respond_to?(:table_alias) && left.table_alias
+        candidates << left.relation.name if left.respond_to?(:relation) && left.relation.respond_to?(:name)
+        candidates.any? { |c| names.include?(c.to_s) }
+      end
+
       def build_arel(connection_or_aliases = nil, aliases = nil)
         requirement = Gem::Requirement.new('>= 7.2', '< 8.1')
 
@@ -184,6 +302,7 @@ module CoreExtensions
           arel = super(connection_or_aliases)
         end
 
+        mark_final_joins!(arel) if joins_final_values.present?
         arel.final! if final_value
         arel.limit_by(*@values[:limit_by]) if @values[:limit_by].present?
         arel.settings(settings_values) unless settings_values.empty?