elasticsearch_record 2.0.0 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 27f0d74b39e373493b56511cb08e07ed2fc447da5f33cf5a23a8a080072f3d4e
-  data.tar.gz: 52f5843b03ea19f3f236910f2268aadb1eba5b7eae48c59734d162fdd2bc6000
+  metadata.gz: b3d4d1dd73be19114191e80cba0ec2844ab3049e380998f8ba48fed78f5c5837
+  data.tar.gz: 252d5abb68af3199c73850337aac6d6ce2c6e379a9fd5f2bea1656447da29995
 SHA512:
-  metadata.gz: '07733791c4f29ed331631d6ede8ba83b23ebad2af68afffda6e998eca7d09f4aad4a57a83c87e10dbd866a98bb8f77a6d4fffc905b1dd214d13f48313d603955'
-  data.tar.gz: 4f3e9ffb52a06c4db77fb698b7e715eac3ad77aa259df5f66905890f69646b35e4f6ee809c52feae3180544de8e47943f6cff95faeff12c43bfaecc9d0e01cb4
+  metadata.gz: 635066f96fb6713a4719ac6fc2a4338dd967b7ca990c9d2c1e644ca05a749be4932f9a07277a42da5340530f0291d7a2bd06edcfdaf89cdcda844339ede6b4fa
+  data.tar.gz: 324d987c404a4dd0069d48c30866c6b854719eec91e3051321396ecf457b160dd16dfc29d47427c4e4a7193fc5d82e721f89013ae692ca9cc4642bb005503cb8

data/README.md

@@ -6,6 +6,8 @@
 [![Gem Version](https://badge.fury.io/rb/elasticsearch_record.svg)](https://badge.fury.io/rb/elasticsearch_record)
 [![License](https://img.shields.io/github/license/ruby-smart/elasticsearch_record)](docs/LICENSE)
 
+[![Coverage Status](https://coveralls.io/repos/github/ruby-smart/elasticsearch_record/badge.svg?branch=main&kill_cache=1)](https://coveralls.io/github/ruby-smart/elasticsearch_record?branch=main)
+
 ActiveRecord adapter for Elasticsearch
 
 _ElasticsearchRecord is a ActiveRecord adapter and provides similar functionality for Elasticsearch._
@@ -14,9 +16,9 @@ _ElasticsearchRecord is a ActiveRecord adapter and provides similar functionalit
 
 **PLEASE NOTE:**
 
-- This is the `main`-branch, which currently supports rails **7.1** _(see section 'Rails_Versions' for supported versions)_
-- supports ActiveRecord ~> 7.1 + Elasticsearch >= 7.17
-- added features up to Elasticsearch `8.17.1`
+- This is the `main`-branch, which supports rails **8.0** _(see section 'Rails_Versions' for supported versions)_
+- supports ActiveRecord ~> 7.2 + Elasticsearch >= 7.17
+- added features up to Elasticsearch `8.17.1` _(tested against `8.19.14`)_
 - _ES|QL_ queries _(`TYPE_ESQL` / the `esql.query` gate)_ require **Elasticsearch >= 8.11**, where the feature became
   generally available. All other features remain available from Elasticsearch `7.17`.
 
@@ -26,8 +28,23 @@ _ElasticsearchRecord is a ActiveRecord adapter and provides similar functionalit
 
 Supported rails versions:
 
+### Rails 8.0:
+_(since gem version 4.0)_
+
+https://github.com/ruby-smart/elasticsearch_record/tree/rails-8-0-stable
+
+[![rails-7-1-stable](https://img.shields.io/badge/rails-8.0.stable-orange.svg)](https://github.com/ruby-smart/elasticsearch_record/tree/rails-8-0-stable)
+
+
+### Rails 7.2:
+_(since gem version 3.0)_
+
+https://github.com/ruby-smart/elasticsearch_record/tree/rails-7-2-stable
+
+[![rails-7-1-stable](https://img.shields.io/badge/rails-7.2.stable-orange.svg)](https://github.com/ruby-smart/elasticsearch_record/tree/rails-7-2-stable)
+
 ### Rails 7.1:
-_(since gem version 1.8)_
+_(since gem version 2.0)_
 
 https://github.com/ruby-smart/elasticsearch_record/tree/rails-7-1-stable
 
@@ -47,7 +64,7 @@ https://github.com/ruby-smart/elasticsearch_record/tree/rails-7-0-stable
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'elasticsearch_record', '~> 1.8'
+gem 'elasticsearch_record'
 
 # alternative
 gem 'elasticsearch_record', git: 'https://github.com/ruby-smart/elasticsearch_record', branch: 'rails-7-1-stable'
@@ -63,6 +80,78 @@ Or install it yourself as:
 
     $ gem install elasticsearch_record
 
+-----
+
+## Upgrading to 2.0
+
+Version **2.0** contains breaking changes. Coming from **1.8.x**, check the following:
+
+### 1. Table (index) names are resolved by default
+
+Every table statement now resolves its name through `#_env_table_name`, so the
+`table_name_prefix` / `table_name_suffix` no longer have to be applied by hand in migrations or database statements
+_(which silently wrote into another environment's index)_.
+
+```ruby
+# 1.8.x - the prefix / suffix had to be applied manually
+drop_table _env_table_name("settings")
+
+# 2.0 - resolved on its own
+drop_table "settings"
+```
+
+Existing migrations keep working - `_env_table_name` is idempotent and still public, so a
+hand-resolved name resolves to the very same index. A new `decorate:`-argument opts out per
+call, and `ElasticsearchRecord.decorate_table_names` acts as a global kill-switch.
+
+_see @ [environment-related-table-name](#environment-related-table-name), [opting out with `decorate: false`](#opting-out-with-decorate-false) & [global kill-switch](#global-kill-switch)_
+
+### 2. `select` raises on metadata fields
+
+Metadata fields _(`_id`, `_score`, `_index`, ...)_ are not part of the `_source` node, so they
+could never be resolved through the `_source`-filter this method builds - providing them
+silently created a filter that never matched.
+
+```ruby
+Search.select(:_id)
+# => ActiveRecord::UnknownAttributeReference
+```
+
+They are returned anyway and accessible on each record _(`Search.first._id`)_. To resolve the
+metadata **without** transferring the `_source`, use the new `#meta_only!` method.
+
+### 3. `restore_table` replaces its `open:`-argument with `unblock:`
+
+A restore runs through a `clone`, so the restored table **inherits** the 'write'-block of its
+source - the table was open, but read-only. `unblock:` _(default: `true`)_ releases it again.
+`ModelApi#restore!` follows along.
+
+```ruby
+# 1.8.x
+restore_table 'settings', from: 'settings-snapshot-2024', open: true
+
+# 2.0
+restore_table 'settings', from: 'settings-snapshot-2024', unblock: true
+```
+
+### 4. The plural table statements no longer skip AR-internal indices
+
+`#open_tables`, `#close_tables`, `#refresh_tables` & `#truncate_tables` no longer subtract the
+ActiveRecord-internal indices _(`schema_migrations` & `ar_internal_metadata`)_ - an explicitly
+named index was silently dropped from the list. They now return an `Array` with an entry for
+**every** provided name.
+
+### 5. `truncate_table` raises for AR-internal indices
+
+The statement runs a `drop` & `create` and would wipe the migration state.
+`#drop_table` stays unguarded by design _(ActiveRecord resets both tables through it)_.
+
+### 6. `esql` & `msearch` dropped their `async:`-argument
+
+Both dispatch through the public `exec_query` now, since rails 7.1 made `internal_exec_query`
+private - the `async:`-argument was dropped along with it.
+
+-----
 
 ## Features
 * ActiveRecord's `create, read, update & delete` behaviours
@@ -72,6 +161,8 @@ Or install it yourself as:
   * additional relation methods to find records with `filter, must, must_not, should`
   * aggregated queries with Elasticsearch `aggregation` methods
   * resolve search response `hits`, `aggregations`, `buckets`, ... instead of ActiveRecord objects
+  * `SQL` & `ES|QL` queries resolve their **tabular** response into records _(`find_by_sql` with a String query, `find_by_esql`)_
+  * table (index) names are resolved within the current environment _(`table_name_prefix` / `table_name_suffix`)_
 * Third-party gem support
   * access `elasticsearch-dsl` query builder through `model.search{ ... }`
 * Schema
@@ -255,6 +346,11 @@ buckets = Search.where(name: 'A nice object').aggregate(:total, {sum: {field: :a
 results = Search.where(name: 'A nice object').pit_results
 # > [{ "_id": "abc123", "name": "A nice object", ...
 
+# resolves ONLY the metadata nodes of each hit - the '_source' is not transferred at all.
+# (this is the replacement for a - no longer supported - 'select(:_id)')
+metas = Search.where(name: 'A nice object').meta_only!.results
+# > [{ "_id": "abc123", "_index": "search", "_score": 1.0 }, ...
+
 # returns the total value of the query without querying again (it uses the total value from the response)
 scope = Search.where(name: 'A nice object').limit(5)
 results_count = scope.count
@@ -288,10 +384,7 @@ _(also see @ [github](https://github.com/ruby-smart/elasticsearch_record/blob/ma
 - must
 - should
 - aggregate
-- restrict 
-- hits_only!
-- aggs_only!
-- total_only!
+- select _(raises on metadata fields - see @ [Upgrading to 2.0](#2-select-raises-on-metadata-fields))_
 
 _see simple documentation about these methods @ {ElasticsearchRecord::Relation::QueryMethods rubydoc}_
 
@@ -308,7 +401,7 @@ _(also see @ [github](https://github.com/ruby-smart/elasticsearch_record/blob/ma
 - boxplot
 - stats
 - string_stats
-- matrix_stats
+- matrix_stats _(requires at least two columns)_
 - median_absolute_deviation
 - calculate
 
@@ -316,6 +409,13 @@ _see simple documentation about these methods @ {ElasticsearchRecord::Relation::
 
 _(also see @ [github](https://github.com/ruby-smart/elasticsearch_record/blob/main/lib/elasticsearch_record/relation/calculation_methods.rb) )_
 
+### Available query configuration methods
+
+- hits_only! _(prevents to resolve aggs)_
+- aggs_only! _(prevents to resolve hits / source data)_
+- total_only! _(prevents to resolve aggs, hits / source data)_
+- meta_only! _(resolves the metadata nodes (`_id`, `_score`, ...) of each hit without transferring the `_source`)_
+
 ### Available result methods
 - aggregations
 - buckets
@@ -544,7 +644,7 @@ Access these methods through the model's connection or within any `Migration`.
 **Example migration:**
 
 ```ruby
-class AddTests < ActiveRecord::Migration[7.0]
+class AddTests < ActiveRecord::Migration[7.1]
   def up
     create_table "assignments", if_not_exists: true do |t|
       t.string :key, primary_key: true
@@ -647,7 +747,7 @@ A single migration can be created to be used within each environment:
 
 ```ruby
 # Example migration
-class AddSettings < ActiveRecord::Migration[7.0]
+class AddSettings < ActiveRecord::Migration[7.1]
   def up
     # creates 'settings-pro' on production & 'settings-dev' on development
     create_table "settings", force: true do |t|

data/docs/CHANGELOG.md

@@ -1,5 +1,31 @@
 # ElasticsearchRecord - CHANGELOG
 
+## [4.0.0] - 2026-09-08
+* [add] **BREAKING**: requires `activerecord ~> 8.0.0`
+* [add] `ElasticsearchRecord::Result#indexed_rows` - rails 8.0 instantiates records through this method instead of iterating the result set itself.
+* [ref] `ElasticsearchAdapter#log` resolves the instrumenter through `#instrumenter` instead of the former `@instrumenter` ivar
+* [ref] `ActiveRecord::ConnectionAdapters::Elasticsearch::SchemaDumper` remove redundant blank lines
+
+## [3.0.0] - 2026-09-08
+* [add] **BREAKING**: requires `activerecord ~> 7.2.0`
+* [add] `Quoting::ClassMethods#quote_column_name` & `#quote_table_name` - identifier quoting is class-level & mandatory now
+* [add] `ElasticsearchRecord::InternalMetadata` - always disabled _(the flag moved from the adapter to the database config)_
+* [add] `patches/active_record/connection_pool_patch` - routes `#migrations_paths`, `#schema_migration` & `#internal_metadata` back to the adapter
+* [add] specs for `ElasticsearchAdapter#translate_exception`
+* [add] specs for `Relation::ValueMethods#limit_value=`
+* [add] specs for `Core#id=`, `#id_was`, `#write_attribute` & `#read_attribute`
+* [add] specs for `TableSettingDefinition`
+* [add] specs for `InternalMetadata#enabled?`
+* [ref] the adapter registers itself through `ActiveRecord::ConnectionAdapters.register` - `ConnectionHandling#elasticsearch_connection` removed
+* [ref] the adapter provides `#internal_metadata` & `#migration_context` again; `#schema_migration` builds from the **pool**
+* [ref] `SchemaMigration#integer_versions` resolves through `pool.with_connection`
+* [ref] `#find_by_sql`, `#find_by_query` & `#find_by_esql` resolve through `with_connection`; `allow_retry:` forwarded down to `#internal_exec_query`
+* [ref] `#_insert_record`, `#_insert_with_auto_increment` & `#cached_find_by_statement` take the connection as first argument
+* [ref] `Arel::Collectors::ElasticsearchQuery#retryable` accessor added _(rails marks idempotent queries as retryable)_
+* [ref] `assert_mutability!` -> `assert_modifiable!` & `ImmutableRelation` -> `UnmodifiableRelation`
+* [ref] `Arel::Nodes::Or` is a nary node now - takes its children as a single `Array`
+* [fix] `Querying::ClassMethods#search` to nest the `Elasticsearch::DSL` block result into the `body` and to only enter the DSL branch **if a block was provided**
+
 ## [2.0.0] - 2026-08-10
 * [add] `ElasticsearchRecord.decorate_table_names` _(default: `true`)_ as global kill-switch for the table name decoration - only provides the default for an omitted `decorate:`-argument, `#_env_table_name` stays unaffected
 * [add] `TableStatements#truncate_table` raises an `ArgumentError` for AR-internal indices - the statement runs a `drop` & `create` and would wipe the migration state. `#drop_table` stays unguarded by design _(AR resets both tables through it)_

data/elasticsearch_record.gemspec

@@ -14,7 +14,7 @@ DESC
 
   spec.homepage              = "https://github.com/ruby-smart/elasticsearch_record"
   spec.license               = "MIT"
-  spec.required_ruby_version = ">= 2.7.0"
+  spec.required_ruby_version = ">= 3.1.0"
 
   spec.metadata["allowed_push_host"] = "https://rubygems.org"
   spec.metadata["homepage_uri"]      = spec.homepage
@@ -32,7 +32,7 @@ DESC
 
   spec.require_paths = ["lib"]
 
-  spec.add_dependency 'activerecord', '~> 7.1.0'
+  spec.add_dependency 'activerecord', '~> 8.0.0'
   spec.add_dependency 'elasticsearch', '>= 7.17'
 
   spec.add_development_dependency 'coveralls_reborn', '~> 0.25'

data/lib/active_record/connection_adapters/elasticsearch/database_statements.rb

@@ -137,10 +137,11 @@ module ActiveRecord
           # @param [Array] binds - not supported on the top-level and therefore ignored!
           # @param [Boolean] prepare - used by the default AbstractAdapter - but not supported and therefore never ignored!
           # @param [Boolean] async
+          # @param [Boolean] allow_retry
           # @return [ElasticsearchRecord::Result]
-          def internal_exec_query(query, name = "QUERY", binds = [], prepare: false, async: false)
+          def internal_exec_query(query, name = "QUERY", binds = [], prepare: false, async: false, allow_retry: false)
             build_result(
-              internal_execute(query, name, async: async),
+              internal_execute(query, name, async: async, allow_retry: allow_retry),
               columns: query.columns
             )
           end

data/lib/active_record/connection_adapters/elasticsearch/quoting.rb

@@ -4,6 +4,22 @@ module ActiveRecord
   module ConnectionAdapters
     module Elasticsearch
       module Quoting # :nodoc:
+        extend ActiveSupport::Concern
+
+        module ClassMethods # :nodoc:
+          # since rails 7.2 identifier quoting is class-level & mandatory (the abstract
+          # implementation raises a +NotImplementedError+). Elasticsearch fields & indices are
+          # plain JSON keys - so they pass through unquoted.
+          def quote_column_name(column_name)
+            column_name.to_s
+          end
+
+          # Quotes the table (index) name. Defaults to column name quoting.
+          def quote_table_name(table_name)
+            quote_column_name(table_name)
+          end
+        end
+
         def quoted_true
           'true'
         end

data/lib/active_record/connection_adapters/elasticsearch/schema_dumper.rb

@@ -151,14 +151,12 @@ module ActiveRecord
             end
 
             tbl.puts "  end"
-            tbl.puts
 
             tbl.rewind
             stream.print tbl.read
           rescue => e
             stream.puts "# Could not dump table #{table.inspect} because of following #{e.class}"
             stream.puts "#   #{e.message}"
-            stream.puts
           ensure
             self.table_name = nil
           end

data/lib/active_record/connection_adapters/elasticsearch_adapter.rb

@@ -22,16 +22,6 @@ gem 'elasticsearch'
 require 'elasticsearch'
 
 module ActiveRecord # :nodoc:
-  module ConnectionHandling # :nodoc:
-    def elasticsearch_adapter_class
-      ConnectionAdapters::ElasticsearchAdapter
-    end
-
-    def elasticsearch_connection(config)
-      elasticsearch_adapter_class.new(config)
-    end
-  end
-
   module ConnectionAdapters # :nodoc:
     class ElasticsearchAdapter < AbstractAdapter
       include Elasticsearch::UnsupportedImplementation
@@ -168,7 +158,17 @@ module ActiveRecord # :nodoc:
       end
 
       def schema_migration # :nodoc:
-        ElasticsearchRecord::SchemaMigration.new(self)
+        ElasticsearchRecord::SchemaMigration.new(pool)
+      end
+
+      def internal_metadata # :nodoc:
+        ElasticsearchRecord::InternalMetadata.new(pool)
+      end
+
+      # since rails 7.2 the migration context is resolved through the connection pool -
+      # provided here as connection method again (used by +#assume_migrated_upto_version+)
+      def migration_context # :nodoc:
+        pool.migration_context
       end
 
       # provide a table_name_prefix from the configuration to create & restrict schema creation
@@ -384,7 +384,9 @@ module ActiveRecord # :nodoc:
       # @raise [Exception] any exception encountered during execution, after translation.
       # @return [void]
       def log(gate, arguments, name = 'QUERY', async: false, statistics: nil, &block)
-        @instrumenter.instrument(
+        # +instrumenter+ instead of the former +@instrumenter+ ivar - the abstract adapter
+        # resolves it per execution context now
+        instrumenter.instrument(
           "query.elasticsearch_record",
           gate: gate,
           name: name,
@@ -429,4 +431,12 @@ module ActiveRecord # :nodoc:
       ::ActiveRecord::Type.register(:range, ::ActiveRecord::ConnectionAdapters::Elasticsearch::Type::Range, adapter: :elasticsearch)
     end
   end
-end
+end
+
+# since rails 7.2 an adapter has to register itself - the former load-by-convention
+# through +ConnectionHandling#elasticsearch_connection+ is gone
+ActiveRecord::ConnectionAdapters.register(
+  'elasticsearch',
+  'ActiveRecord::ConnectionAdapters::ElasticsearchAdapter',
+  'active_record/connection_adapters/elasticsearch_adapter'
+)

data/lib/arel/collectors/elasticsearch_query.rb

@@ -9,6 +9,9 @@ module Arel # :nodoc: all
       # required for ActiveRecord
       attr_accessor :preparable
 
+      # required for ActiveRecord (rails 7.2 marks idempotent queries as retryable)
+      attr_accessor :retryable
+
       # returns the current bind index (default: 1)
       attr_reader :bind_index
 

data/lib/elasticsearch_record/core.rb

@@ -96,7 +96,7 @@ module ElasticsearchRecord
       # used to create a cacheable statement.
       # This is a 1:1 copy, except that we use our own class +ElasticsearchRecord::StatementCache+
       # see @ ActiveRecord::Core::ClassMethods#cached_find_by_statement
-      def cached_find_by_statement(key, &block)
+      def cached_find_by_statement(connection, key, &block)
         cache = @find_by_statement_cache[connection.prepared_statements]
         cache.compute_if_absent(key) { ElasticsearchRecord::StatementCache.create(connection, &block) }
       end

data/lib/elasticsearch_record/gem_version.rb

@@ -7,7 +7,7 @@ module ElasticsearchRecord
   end
 
   module VERSION
-    MAJOR = 2
+    MAJOR = 4
     MINOR = 0
     TINY  = 0
     PRE   = nil

data/lib/elasticsearch_record/internal_metadata.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "active_record/internal_metadata"
+
+module ElasticsearchRecord
+  class InternalMetadata < ::ActiveRecord::InternalMetadata
+
+    # overwrite method to always disable the internal metadata index.
+    #
+    # Elasticsearch cannot serve the internal metadata table
+    # (see +ElasticsearchAdapter#use_metadata_table?+) - but since rails 7.2 the flag is
+    # resolved through the database config (default: enabled) instead of the adapter,
+    # so a default configuration would suddenly create & write a 'ar_internal_metadata'
+    # index on the cluster.
+    def enabled?
+      false
+    end
+  end
+end

data/lib/elasticsearch_record/patches/active_record/connection_pool_patch.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require 'active_record/connection_adapters/abstract/connection_pool'
+
+module ElasticsearchRecord
+  module Patches
+    module ActiveRecord
+      # Since rails 7.2 the migration plumbing is resolved through the connection POOL
+      # (+ConnectionPool#migration_context+ builds from +#migrations_paths+, +#schema_migration+ &
+      # +#internal_metadata+) instead of the connection - so the adapters own implementations are
+      # no longer consulted. Without this patch a Elasticsearch pool would migrate with the generic
+      # +ActiveRecord::SchemaMigration+ (which resolves the index name through +ActiveRecord::Base+
+      # and only ever sees the first ten migrations - Elasticsearch default search size), enable the
+      # internal metadata index (the adapter cannot serve it) and fall back to the default
+      # 'db/migrate' path.
+      #
+      # The patch simply routes those factories back to the adapter class, which keeps the
+      # Elasticsearch-specific implementations in one place.
+      module ConnectionPoolPatch
+        def self.included(base)
+          base.send(:prepend, PrependMethods)
+        end
+
+        module PrependMethods
+          def migrations_paths
+            return super unless elasticsearch_pool?
+
+            db_config.migrations_paths || ['db/migrate_elasticsearch']
+          end
+
+          def schema_migration
+            return super unless elasticsearch_pool?
+
+            ElasticsearchRecord::SchemaMigration.new(self)
+          end
+
+          def internal_metadata
+            return super unless elasticsearch_pool?
+
+            ElasticsearchRecord::InternalMetadata.new(self)
+          end
+
+          private
+
+          # returns true, if the pools config resolves to the Elasticsearch adapter
+          # @return [Boolean]
+          def elasticsearch_pool?
+            db_config.adapter_class <= ::ActiveRecord::ConnectionAdapters::ElasticsearchAdapter
+          end
+        end
+      end
+    end
+  end
+end
+
+# include once only!
+::ActiveRecord::ConnectionAdapters::ConnectionPool.include(ElasticsearchRecord::Patches::ActiveRecord::ConnectionPoolPatch) unless ::ActiveRecord::ConnectionAdapters::ConnectionPool.included_modules.include?(ElasticsearchRecord::Patches::ActiveRecord::ConnectionPoolPatch)

data/lib/elasticsearch_record/persistence.rb

@@ -5,14 +5,15 @@ module ElasticsearchRecord
     module ClassMethods
       # insert a new record into the Elasticsearch index
       # NOTICE: We don't want to mess up with the Arel-builder - so we send new data directly to the API
+      # @param [ActiveRecord::ConnectionAdapters::ElasticsearchAdapter] connection
       # @param [ActiveModel::Attribute] values
       # @return [Object] id
-      def _insert_record(values, returning)
+      def _insert_record(connection, values, returning)
         # values is not a "key=>values"-Hash, but a +ActiveModel::Attribute+ - so the casted values gets resolved here
         values = values.transform_values(&:value)
 
         # resolve & update a auto_increment value, if configured
-        _insert_with_auto_increment(values) do |arguments|
+        _insert_with_auto_increment(connection, values) do |arguments|
           # build new query
           query = ElasticsearchRecord::Query.new(
             index: table_name,
@@ -62,7 +63,7 @@ module ElasticsearchRecord
       private
 
       # Resolves the +auto_increment+ status from the tables +_meta+ attributes.
-      def _insert_with_auto_increment(values)
+      def _insert_with_auto_increment(connection, values)
         # check, if the primary_key's value is provided.
         # so, no need to resolve a +auto_increment+ value, but provide the id directly
         if (id = values[self.primary_key]).present?

data/lib/elasticsearch_record/querying.rb

@@ -42,8 +42,9 @@ module ElasticsearchRecord
       # @param [String, Hash, ElasticsearchRecord::Query] sql
       # @param [Array] binds
       # @param [nil] preparable
+      # @param [Boolean] allow_retry
       # @param [Proc] block
-      def find_by_sql(sql, binds = [], preparable: nil, &block)
+      def find_by_sql(sql, binds = [], preparable: nil, allow_retry: false, &block)
         query = case sql
                 when String # really find by SQL
                   ElasticsearchRecord::Query.new(
@@ -61,7 +62,11 @@ module ElasticsearchRecord
                   sql
                 end
 
-        _load_from_sql(_query_by_sql(query, binds), &block)
+        result = with_connection do |c|
+          _query_by_sql(c, query, binds, preparable: preparable, allow_retry: allow_retry)
+        end
+
+        _load_from_sql(result, &block)
       end
 
       # finds records by query arguments
@@ -74,7 +79,11 @@ module ElasticsearchRecord
           # IMPORTANT: Always provide all columns to prevent unknown attributes that should be nil ...
           columns: source_column_names)
 
-        _load_from_sql(_query_by_sql(query), &block)
+        result = with_connection do |c|
+          _query_by_sql(c, query)
+        end
+
+        _load_from_sql(result, &block)
       end
 
       # ES|QL query API
@@ -90,7 +99,11 @@ module ElasticsearchRecord
           # IMPORTANT: Always provide all columns
           columns: source_column_names)
 
-        _load_from_sql(_query_by_sql(query), &block)
+        result = with_connection do |c|
+          _query_by_sql(c, query)
+        end
+
+        _load_from_sql(result, &block)
       end
 
       # executes a +esql+ by provided *ES|SL* query
@@ -123,17 +136,28 @@ module ElasticsearchRecord
         connection.exec_query(query, "#{name} Msearch")
       end
 
-      # executes a search by provided +RAW+ query - supports +Elasticsearch::DSL+ gem if loaded
+      # executes a search by provided +RAW+ query - supports +Elasticsearch::DSL+ gem if loaded.
+      #
+      # Without a block the trailing options-hash is used as query arguments.
+      # With a block the +Elasticsearch::DSL+ gem builds the query - if the gem is not
+      # available (or the block fails), the block is SILENTLY ignored and the
+      # options-hash is used instead.
       def search(*args, &block)
-        begin
-          # require the Elasticsearch::DSL gem, if loaded
-          require 'elasticsearch/dsl'
-          query = ::Elasticsearch::DSL::Search::Search.new(*args, &block).to_hash
-        rescue LoadError
-          query = args.extract_options!
-        rescue
-          query = args.extract_options!
-        end
+        query = if block_given?
+                  begin
+                    # require the Elasticsearch::DSL gem, if loaded
+                    require 'elasticsearch/dsl'
+                    # PLEASE NOTE: +Search#to_hash+ returns the request BODY - it must be nested
+                    # into the query arguments, otherwise it is sent as (invalid) URL parameters.
+                    { body: ::Elasticsearch::DSL::Search::Search.new(*args, &block).to_hash }
+                  rescue LoadError
+                    args.extract_options!
+                  rescue
+                    args.extract_options!
+                  end
+                else
+                  args.extract_options!
+                end
 
         find_by_query(query)
       end

data/lib/elasticsearch_record/relation/core_methods.rb

@@ -10,7 +10,7 @@ module ElasticsearchRecord
       # transforms the current relation into arel, compiles it to query and executes the query.
       # returns the result object.
       #
-      # PLEASE NOTE: This makes the query +immutable+ and raises a +ActiveRecord::ImmutableRelation+
+      # PLEASE NOTE: This makes the query +immutable+ and raises a +ActiveRecord::UnmodifiableRelation+
       # if you try to change it's values.
       #
       # PLEASE NOTE: resolving records _(instantiate)_ is never possible after calling this method!

data/lib/elasticsearch_record/relation/query_clause_tree.rb

@@ -109,7 +109,8 @@ module ElasticsearchRecord # :nodoc:
           left = left[key]
           right = right[key]
 
-          or_clause = Arel::Nodes::Or.new(left, right)
+          # since rails 7.2 +Arel::Nodes::Or+ is a nary node and takes its children as a single Array
+          or_clause = Arel::Nodes::Or.new([left, right])
 
           common.predicates[key] = ElasticsearchRecord::Relation::QueryClause.new(key, [Arel::Nodes::Grouping.new(or_clause)])
           common

data/lib/elasticsearch_record/relation/query_methods.rb

@@ -260,7 +260,7 @@ module ElasticsearchRecord
             unless _valid_unscoping_values.include?(scope)
               raise ArgumentError, "Called unscope() with invalid unscoping argument ':#{scope}'. Valid arguments are :#{_valid_unscoping_values.to_a.join(", :")}."
             end
-            assert_mutability!
+            assert_modifiable!
             @values.delete(scope)
           when Hash
             scope.each do |key, target_value|

data/lib/elasticsearch_record/relation/value_methods.rb

@@ -8,7 +8,7 @@ module ElasticsearchRecord
 
       def kind_value=(value)
         # checks if records are already loaded - in this case we cannot mutate the query anymore
-        assert_mutability!
+        assert_modifiable!
 
         @values[:kind] = value.to_sym
       end
@@ -18,7 +18,7 @@ module ElasticsearchRecord
       end
 
       def configure_value=(value)
-        assert_mutability!
+        assert_modifiable!
 
         @values[:configure] = value
       end
@@ -28,7 +28,7 @@ module ElasticsearchRecord
       end
 
       def query_clause=(value)
-        assert_mutability!
+        assert_modifiable!
 
         @values[:query] = value
       end
@@ -38,7 +38,7 @@ module ElasticsearchRecord
       end
 
       def aggs_clause=(value)
-        assert_mutability!
+        assert_modifiable!
 
         @values[:aggs] = value
       end

data/lib/elasticsearch_record/result.rb

@@ -172,6 +172,16 @@ module ElasticsearchRecord
       n ? computed_results.last(n) : computed_results.last
     end
 
+    # Returns the rows to instantiate records from - ActiveRecord resolves them through this
+    # method instead of iterating the result set itself.
+    # Each element is a Hash keyed by column / metadata name and therefore already provides the
+    # read surface of +ActiveRecord::Result::IndexedRow+ (+key?+, +[]+, +fetch+, +keys+, ...).
+    # used by +ActiveRecord+
+    # @return [Array<Hash>]
+    def indexed_rows # :nodoc:
+      computed_results
+    end
+
     # used by ActiveRecord
     def cancel # :nodoc:
       self

data/lib/elasticsearch_record/schema_migration.rb

@@ -14,9 +14,12 @@ module ElasticsearchRecord
       sm = Arel::SelectManager.new(arel_table)
       sm.project(arel_table[primary_key])
       sm.order(arel_table[primary_key].asc)
-      sm.take(connection.max_result_window(table_name))
 
-      connection.select_values(sm, "#{self.class} Load")
+      @pool.with_connection do |connection|
+        sm.take(connection.max_result_window(table_name))
+
+        connection.select_values(sm, "#{self.class} Load")
+      end
     end
   end
 end

data/lib/elasticsearch_record.rb

@@ -22,6 +22,7 @@ module ElasticsearchRecord
   eager_autoload do
     autoload :Base
     autoload :Core
+    autoload :InternalMetadata
     autoload :ModelSchema
     autoload :ModelApi
     autoload :Persistence
@@ -84,6 +85,7 @@ end
 
 ActiveSupport.on_load(:active_record) do
   # load patches
+  require 'elasticsearch_record/patches/active_record/connection_pool_patch'
   require 'elasticsearch_record/patches/active_record/relation_merger_patch'
   require 'elasticsearch_record/patches/arel/select_core_patch'
   require 'elasticsearch_record/patches/arel/select_manager_patch'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: elasticsearch_record
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 4.0.0
 platform: ruby
 authors:
 - Tobias Gonsior
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 7.1.0
+        version: 8.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 7.1.0
+        version: 8.0.0
 - !ruby/object:Gem::Dependency
   name: elasticsearch
   requirement: !ruby/object:Gem::Requirement
@@ -186,8 +186,10 @@ files:
 - lib/elasticsearch_record/instrumentation/controller_runtime.rb
 - lib/elasticsearch_record/instrumentation/log_subscriber.rb
 - lib/elasticsearch_record/instrumentation/railtie.rb
+- lib/elasticsearch_record/internal_metadata.rb
 - lib/elasticsearch_record/model_api.rb
 - lib/elasticsearch_record/model_schema.rb
+- lib/elasticsearch_record/patches/active_record/connection_pool_patch.rb
 - lib/elasticsearch_record/patches/active_record/relation_merger_patch.rb
 - lib/elasticsearch_record/patches/arel/select_core_patch.rb
 - lib/elasticsearch_record/patches/arel/select_manager_patch.rb
@@ -226,7 +228,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.7.0
+      version: 3.1.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="