active_record_proxy_adapters 0.4.6 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4ed0b02df3f4b3700b42b1e89b4449470cec256cf2657276c9584aab3dc8165d
-  data.tar.gz: e041a155d835a4a5f0919e8883fba2e863e68ec713c92e8759d362c22d667ac1
+  metadata.gz: 7884786c370072543b8702a379b372ffa878e281e88e8e96ba603cec78a01523
+  data.tar.gz: 80141eaa2a1e1bbd9c4eb985136140acf006c16e5749497a114574f809325e98
 SHA512:
-  metadata.gz: 0e41b26de72871a04777ecd533c2172531fa32d0718a641f640aab5b6eda0bc1adfa3b255fca31d0d961a25994bf51409e1c0cbd87044d77447be62dd779afde
-  data.tar.gz: a6f0ede11a734a907999a597bc9d538742bc26830e1b4d9e0191fd7577e803c388a8c91220f4562c457f957c92dde5208defa2a0b0cd8d01a02fdddba00f2fb0
+  metadata.gz: 7f89bd7a1edf1e8813a9b70610c0153603958b64dbcecd5a00cc506301819e774b45ff291b06cfe01d8f25d2db6763853cb2bac4462d98836c33fbada30231b5
+  data.tar.gz: b7db70493adab591fd31c4294a630ff976e7cefac58a2e466f2e5cb6511102b1900054fbbc6d632a59cac8875f1f047d4ad0c78a5385f669987ec48bc8420651

data/README.md

@@ -40,9 +40,7 @@ Currently supported adapters:
 - `postgresql`
 - `mysql2`
 - `trilogy`
-
-Coming soon:
-- `sqlite`
+- `sqlite3`
 
 
 #### PostgreSQL
@@ -73,6 +71,34 @@ development:
     # your replica credentials here
 ```
 
+#### Trilogy
+```yaml
+# config/database.yml
+development:
+  primary:
+    adapter: trilogy_proxy
+    # your primary credentials here
+
+  primary_replica:
+    adapter: trilogy
+    replica: true
+    # your replica credentials here
+```
+
+#### SQLite
+```yaml
+# config/database.yml
+development:
+  primary:
+    adapter: sqlite3_proxy
+    # your primary credentials here
+
+  primary_replica:
+    adapter: sqlite3
+    replica: true
+    # your replica credentials here
+```
+
 ```ruby
 # app/models/application_record.rb
 class ApplicationRecord < ActiveRecord::Base
@@ -93,7 +119,7 @@ require "active_record_proxy_adapters/connection_handling"
 class ApplicationRecord << ActiveRecord::Base
     establish_connection(
         {
-            adapter: 'postgresql_proxy',
+            adapter: 'postgresql_proxy', # or any of the following: mysql2_proxy, trilogy_proxy, sqlite3_proxy
             # your primary credentials here
         },
         role: :writing
@@ -101,7 +127,7 @@ class ApplicationRecord << ActiveRecord::Base
 
     establish_connection(
         {
-            adapter: 'postgresql',
+            adapter: 'postgresql',  # or any of the following: mysql2, trilogy, sqlite3
             # your replica credentials here
         },
         role: :reading
@@ -195,7 +221,7 @@ production:
 Then set `PRIMARY_DATABASE_ADAPTER=postgresql_proxy` to enable the proxy.
 That way you can redeploy your application disabling the proxy completely, without any code change.
 
-### Sticking to the primary database manually
+### Sticking to a database manually
 
 The proxy respects ActiveRecord's `#connected_to_stack` and will use it if present.
 You can use that to force connection to the primary or replica and bypass the proxy entirely.
@@ -240,6 +266,84 @@ class SayHelloJob < ApplicationJob
 end
 ```
 
+## Caching Configuration
+
+ActiveRecordProxyAdapters supports caching of SQL pattern matching results to improve performance for frequently executed queries.
+
+### Enabling Caching
+
+By default, caching is disabled (using `NullStore`). To enable caching:
+
+```ruby
+ActiveRecordProxyAdapters.configure do |config|
+  # Configure the cache store
+  config.cache do |cache|
+    # Use a specific cache implementation
+    # Notice that if using a Memcached or a Redis store, the network latency may outweigh the benefits you would get from caching the pattern matching
+    cache.store = ActiveSupport::Cache::MemoryStore.new(size: 64.megabytes)
+
+    # Optional: Customize the cache key prefix (default: "arpa_")
+    cache.key_prefix = "custom_prefix_"
+
+    # Optional: Customize the cache key generation (default: SHA2 hexdigest)
+    cache.key_builder = ->(sql) { "sql_#{Digest::MD5.hexdigest(sql)}" }
+  end
+end
+```
+
+### How Caching Works
+The caching system stores the results of SQL pattern matching operations to determine whether a query should be routed to a primary or replica database. This improves performance by avoiding repeated pattern matching on identical SQL strings.
+
+- Cache keys are generated using the configured `key_builder` (SHA2 digest by default).
+- All keys are prefixed with the configured `key_prefix` ("arpa_" by default).
+- Cache misses are instrumented with the `active_record_proxy_adapters.cache_miss` notification. They can be monitored by subscribing to that topic:
+  ```ruby
+  ActiveSupport::Notifications.subscribe("active_record_proxy_adapters.cache_miss") do |event|
+    cache_key, sql = event[:payload].values_at(:cache_key, :sql)
+
+    logger.info("Cache miss for SQL: #{sql.inspect} with cache key: #{cache_key.inspec}")
+  end
+  ```
+
+### Busting the cache
+
+If you ever need to manually clear the cached SQL patterns:
+
+```ruby
+# This will clear all cached entries with the configured prefix
+ActiveRecordProxyAdapters.bust_query_cache
+```
+
+### Performance Considerations
+For applications with a high volume of repetitive queries, enabling caching can significantly reduce CPU overhead from SQL parsing. However, this comes with the tradeoff of increased memory usage in your cache store.
+
+For optimal results:
+- Consider enabling prepared statements as that will increase cache hit rate, and decrease cache growth rate
+  ```ruby
+  irb(main):001> (1..10).each { |i| User.where(id: i).exists? }
+  ```
+  _Without_ Prepared statements yields
+  ```
+  Cache miss for SQL: "SELECT 1 AS one FROM \"users\" WHERE \"users\".\"id\" = 1 LIMIT 1" with cache key: "arpa_9fa3972e45b27985eef6bfb4aa6269c12d43363c60e7aa67fb290ec317503710"
+  Cache miss for SQL: "SELECT 1 AS one FROM \"users\" WHERE \"users\".\"id\" = 2 LIMIT 1" with cache key: "arpa_0e51756270138442ad26087dffcfb53c21df4a430961f1ca3b4270183f4b066d"
+  Cache miss for SQL: "SELECT 1 AS one FROM \"users\" WHERE \"users\".\"id\" = 3 LIMIT 1" with cache key: "arpa_db5b8c323ee2c284ba96adc6e20b7ea1373ca07fa9b09969f5207d467bd895b6"
+  Cache miss for SQL: "SELECT 1 AS one FROM \"users\" WHERE \"users\".\"id\" = 4 LIMIT 1" with cache key: "arpa_129459a1ba342cad3dbd4458cd8eacda4ed641a94a5d1e6cc23604495e44b565"
+  Cache miss for SQL: "SELECT 1 AS one FROM \"users\" WHERE \"users\".\"id\" = 5 LIMIT 1" with cache key: "arpa_9817a74a6f162ea110ed14cef79e95aa78830ff19266cdce75668e0c9c5ccef7"
+  Cache miss for SQL: "SELECT 1 AS one FROM \"users\" WHERE \"users\".\"id\" = 6 LIMIT 1" with cache key: "arpa_610e37a117abc81ec1afebafa0f36b35547f57879536ca7535475075ea08d8ac"
+  Cache miss for SQL: "SELECT 1 AS one FROM \"users\" WHERE \"users\".\"id\" = 7 LIMIT 1" with cache key: "arpa_79e172d168c59c4e5befbe954861ff9076000f955719dd3cca1423b68fb5f319"
+  Cache miss for SQL: "SELECT 1 AS one FROM \"users\" WHERE \"users\".\"id\" = 8 LIMIT 1" with cache key: "arpa_fb29367bdae3e2a48d1fa63cca00fd611c0b6dc84c9f5fd985b9222d49f1f7d9"
+  Cache miss for SQL: "SELECT 1 AS one FROM \"users\" WHERE \"users\".\"id\" = 9 LIMIT 1" with cache key: "arpa_e6e9a73cf9066077893b21dde038e5a616bf25731aeb5a4a9cdb41b7d84d1ece"
+  Cache miss for SQL: "SELECT 1 AS one FROM \"users\" WHERE \"users\".\"id\" = 10 LIMIT 1" with cache key: "arpa_8c94cdae65b6d529364d6ae8cf68f0e827566d471d2bd1107d6bdca29345759e"
+  ```
+
+  _With_ prepared statments yields
+  ```
+  Cache miss for SQL: "SELECT 1 AS one FROM \"users\" WHERE \"users\".\"id\" = $1 LIMIT $2" with cache key: "arpa_3c2ef2bb9a5f370adf63eac3bc9994c054554798d31d247818049c8c21cb68be"
+  ```
+- Use a cache store with an appropriate size limit, and low latency (Memory Store has lower latency than Memcached or Redis)
+- Monitor cache hit/miss rates using the instrumentation events
+- Consider occasionally busting the cache during low-traffic periods to prevent stale entries, or setting a reasonable expiry window for cached values
+
 ### Thread safety
 
 Since Rails already leases exactly one connection per thread from the pool and the adapter operates on that premise, it is safe to use it in multi-threaded servers such as Puma.
@@ -337,7 +441,173 @@ irb(main):051:0> test_multithread_queries
 
 ## Building your own proxy
 
-TODO: update instructions
+These instructions assume an active record adapter `ActiveRecord::ConnectionAdapters::FoobarAdapter` already exists and is properly loaded in your environment.
+
+To create a proxy adapter for an existing database `FoobarAdapter`, follow these steps under the lib folder of your rails application source code:
+
+1. **Create database tasks for your proxy adapter** to allow Rails tasks like `db:create` and `db:migrate` to work:
+
+   ```ruby
+   # lib/active_record/tasks/foobar_proxy_database_tasks.rb
+
+   require "active_record_proxy_adapters/database_tasks"
+
+   module ActiveRecord
+     module Tasks
+       class FoobarProxyDatabaseTasks < FoobarDatabaseTasks
+         include ActiveRecordProxyAdapters::DatabaseTasks
+       end
+     end
+   end
+
+   ActiveRecord::Tasks::DatabaseTasks.register_task(
+     /foobar_proxy/,
+     "ActiveRecord::Tasks::FoobarProxyDatabaseTasks"
+   )
+   ```
+
+2. **Create the proxy implementation class** that will handle the routing logic:
+
+   ```ruby
+   # lib/active_record_proxy_adapters/foobar_proxy.rb
+
+   require "active_record_proxy_adapters/primary_replica_proxy"
+
+   module ActiveRecordProxyAdapters
+     class FoobarProxy < PrimaryReplicaProxy
+       # Override or hijack extra methods here if you need custom behavior
+       # For most adapters, the default behavior works fine
+     end
+   end
+   ```
+
+3. **Create the proxy adapter class** that inherits from the underlying adapter, including the `Hijackable` concern. You need to require the database tasks source, the original adapter source, and the proxy source:
+
+   ```ruby
+   # lib/active_record/connection_adapters/foobar_proxy_adapter.rb
+
+   require "active_record/tasks/foobar_proxy_database_tasks"
+   require "active_record/connection_adapters/foobar_adapter"
+   require "active_record_proxy_adapters/active_record_context"
+   require "active_record_proxy_adapters/hijackable"
+   require "active_record_proxy_adapters/foobar_proxy"
+
+   module ActiveRecord
+     module ConnectionAdapters
+       class FoobarProxyAdapter < FoobarAdapter
+         include ActiveRecordProxyAdapters::Hijackable
+
+         ADAPTER_NAME = "FoobarProxy" # This is only an ActiveRecord convention and is not required to work
+
+         delegate_to_proxy(*ActiveRecordProxyAdapters::ActiveRecordContext.hijackable_methods)
+
+         def initialize(...)
+           @proxy = ActiveRecordProxyAdapters::FoobarProxy.new(self)
+
+           super
+         end
+
+         private
+
+         attr_reader :proxy
+       end
+     end
+   end
+
+   # This is only required for Rails 7.2 or greater.
+   if ActiveRecordProxyAdapters::ActiveRecordContext.active_record_v7_2_or_greater?
+     ActiveRecord::ConnectionAdapters.register(
+       "foobar_proxy",
+       "ActiveRecord::ConnectionAdapters::FoobarProxyAdapter",
+       "active_record/connection_adapters/foobar_proxy_adapter"
+     )
+   end
+
+   ActiveSupport.run_load_hooks(:active_record_foobarproxyadapter,
+                                ActiveRecord::ConnectionAdapters::FoobarProxyAdapter)
+   ```
+
+4. **Create connection handling module** for ActiveRecord integration:
+
+   ```ruby
+   # lib/active_record_proxy_adapters/connection_handling/foobar.rb
+
+   begin
+     require "active_record/connection_adapters/foobar_proxy_adapter"
+   rescue LoadError
+     # foobar not available
+     return
+   end
+
+   # This is only required for Rails 7.0 or earlier.
+   module ActiveRecordProxyAdapters
+     module Foobar
+       module ConnectionHandling
+         def foobar_proxy_adapter_class
+           ActiveRecord::ConnectionAdapters::FoobarProxyAdapter
+         end
+
+         def foobar_proxy_connection(config)
+            # copy and paste the contents of the original method foobar_connection here.
+            # If the contents contain a hardcoded FooBarAdapter.new instance,
+            # replace it with foobar_proxy_adapter_class.new
+         end
+       end
+     end
+   end
+
+   ActiveSupport.on_load(:active_record) do
+     ActiveRecord::Base.extend(ActiveRecordProxyAdapters::Foobar::ConnectionHandling)
+   end
+   ```
+
+5. **In your initializer, load the custom adapter** when the parent adapter is fully loaded:
+
+   ```ruby
+   # config/initializers/active_record_proxy_adapters.rb
+
+   # The parent adapter should have a load hook already. If not, you might need to monkey patch it.
+   ActiveSupport.on_load(:active_record_foobaradapter) do
+     require "active_record_proxy_adapters/connection_handling/foobar"
+   end
+   ```
+
+6. **Add a custom Zeitwerk inflection rule** if your adapter file paths do not follow Rails conventions. You can skip this if it does:
+
+   ```ruby
+   # config/initializers/active_record_proxy_adapters.rb
+
+   Rails.autoloaders.each do |autoloader|
+     autoloader.inflector.inflect(
+       "foobar_proxy_adapter" => "FoobarProxyAdapter"
+     )
+   end
+   ```
+
+7. **Configure your database.yml** to use your new adapter:
+
+   ```yaml
+   development:
+     primary:
+       adapter: foobar_proxy
+       # primary database configuration
+
+     primary_replica:
+       adapter: foobar
+       replica: true
+       # replica database configuration
+   ```
+
+8. **Set up your model to use both connections**:
+
+   ```ruby
+   class ApplicationRecord < ActiveRecord::Base
+     self.abstract_class = true
+     connects_to database: { writing: :primary, reading: :primary_replica }
+   end
+   ```
+
+For testing your adapter, follow the examples in the test suite by creating spec files that match the pattern used for the other adapters.
 
 ## Development
 

data/lib/active_record/connection_adapters/sqlite3_proxy_adapter.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "active_record/tasks/sqlite3_proxy_database_tasks"
+require "active_record/connection_adapters/sqlite3_adapter"
+require "active_record_proxy_adapters/active_record_context"
+require "active_record_proxy_adapters/hijackable"
+require "active_record_proxy_adapters/sqlite3_proxy"
+
+module ActiveRecord
+  module ConnectionAdapters
+    # This adapter is a proxy to the original SQLite3Adapter, allowing the use of the
+    # ActiveRecordProxyAdapters::PrimaryReplicaProxy.
+    class SQLite3ProxyAdapter < SQLite3Adapter
+      include ActiveRecordProxyAdapters::Hijackable
+
+      ADAPTER_NAME = "SQLite3Proxy"
+
+      delegate_to_proxy(*ActiveRecordProxyAdapters::ActiveRecordContext.hijackable_methods)
+
+      def initialize(...)
+        @proxy = ActiveRecordProxyAdapters::SQLite3Proxy.new(self)
+
+        super
+      end
+
+      private
+
+      attr_reader :proxy
+    end
+  end
+end
+
+if ActiveRecordProxyAdapters::ActiveRecordContext.active_record_v7_2_or_greater?
+  ActiveRecord::ConnectionAdapters.register(
+    "sqlite3_proxy",
+    "ActiveRecord::ConnectionAdapters::SQLite3ProxyAdapter",
+    "active_record/connection_adapters/sqlite3_proxy_adapter"
+  )
+end
+
+ActiveSupport.run_load_hooks(:active_record_sqlite3proxyadapter,
+                             ActiveRecord::ConnectionAdapters::SQLite3ProxyAdapter)

data/lib/active_record/tasks/sqlite3_proxy_database_tasks.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "active_record_proxy_adapters/database_tasks"
+
+module ActiveRecord
+  module Tasks
+    # Defines the sqlite3 tasks for dropping, creating, loading schema and dumping schema.
+    # Bypasses all the proxy logic to send all requests to primary.
+    class SQLite3ProxyDatabaseTasks < SQLiteDatabaseTasks
+      include ActiveRecordProxyAdapters::DatabaseTasks
+    end
+  end
+end
+
+# Allow proxy adapter to run rake tasks, i.e. db:drop, db:create, db:schema:load db:migrate, etc...
+ActiveRecord::Tasks::DatabaseTasks.register_task(
+  /sqlite3_proxy/,
+  "ActiveRecord::Tasks::SQLite3ProxyDatabaseTasks"
+)

data/lib/active_record_proxy_adapters/active_record_context.rb

@@ -12,6 +12,7 @@ module ActiveRecordProxyAdapters
       delegate_missing_to :new
     end
 
+    # rubocop:disable Naming/PredicateMethod
     NullConnectionHandlingContext = Class.new do
       def legacy_connection_handling
         false
@@ -21,6 +22,7 @@ module ActiveRecordProxyAdapters
         nil
       end
     end
+    # rubocop:enable Naming/PredicateMethod
 
     def connection_class_for(connection)
       return connection.connection_descriptor.name.constantize if active_record_v8_0_2_or_greater?

data/lib/active_record_proxy_adapters/cache_configuration.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "active_record_proxy_adapters/synchronizable_configuration"
+
+module ActiveRecordProxyAdapters
+  class CacheConfiguration # rubocop:disable Style/Documentation
+    include SynchronizableConfiguration
+
+    # Sets the cache store to use for caching SQL statements.
+    #
+    # @param store [ActiveSupport::Cache::Store] The cache store to use for caching SQL statements.
+    #   Defaults to ActiveSupport::Cache::NullStore, which does not cache anything.
+    #   Thread safe.
+    # @return [ActiveSupport::Cache::Store] The cache store to use for caching SQL statements.
+    #   Defaults to ActiveSupport::Cache::NullStore, which does not cache anything.
+    #   Thread safe.
+    attr_reader :store
+
+    # @return [String] The prefix to use for cache keys. Defaults to "arpa_".
+    attr_reader :key_prefix
+
+    # @return [Proc] A proc that takes an SQL statement and returns a cache key.
+    #   Defaults to a SHA2 hexdigest of the SQL statement.
+    attr_reader :key_builder
+
+    def initialize(lock = Monitor.new)
+      @lock            = lock
+      self.store       = ActiveSupport::Cache::NullStore.new
+      self.key_prefix  = "arpa_"
+      self.key_builder = ->(sql) { Digest::SHA2.hexdigest(sql) }
+    end
+
+    def store=(store)
+      synchronize_update(:"cache.store", from: @store, to: store) do
+        @store = store
+      end
+    end
+
+    def key_prefix=(key_prefix)
+      synchronize_update(:"cache.key_prefix", from: @key_prefix, to: key_prefix) do
+        @key_prefix = key_prefix
+      end
+    end
+
+    def key_builder=(key_builder)
+      synchronize_update(:"cache.key_builder", from: @key_builder, to: key_builder) do
+        @key_builder = key_builder
+      end
+    end
+
+    def bust
+      store.delete_matched("#{key_prefix}*")
+    end
+  end
+end

data/lib/active_record_proxy_adapters/configuration.rb

@@ -1,10 +1,14 @@
 # frozen_string_literal: true
 
 require "active_support/core_ext/integer/time"
+require "active_record_proxy_adapters/synchronizable_configuration"
+require "active_record_proxy_adapters/cache_configuration"
 
 module ActiveRecordProxyAdapters
   # Provides a global configuration object to configure how the proxy should behave.
   class Configuration
+    include SynchronizableConfiguration
+
     PROXY_DELAY                   = 2.seconds.freeze
     CHECKOUT_TIMEOUT              = 2.seconds.freeze
     LOG_SUBSCRIBER_PRIMARY_PREFIX = proc { |event| "#{event.payload[:connection].class::ADAPTER_NAME} Primary" }.freeze
@@ -30,6 +34,7 @@ module ActiveRecordProxyAdapters
       self.checkout_timeout              = CHECKOUT_TIMEOUT
       self.log_subscriber_primary_prefix = LOG_SUBSCRIBER_PRIMARY_PREFIX
       self.log_subscriber_replica_prefix = LOG_SUBSCRIBER_REPLICA_PREFIX
+      self.cache_configuration           = CacheConfiguration.new(@lock)
     end
 
     def log_subscriber_primary_prefix=(prefix)
@@ -60,17 +65,18 @@ module ActiveRecordProxyAdapters
       end
     end
 
+    def cache
+      block_given? ? yield(cache_configuration) : cache_configuration
+    end
+
     private
 
-    def synchronize_update(attribute, from:, to:, &block)
-      ActiveSupport::Notifications.instrument(
-        "active_record_proxy_adapters.configuration_update",
-        attribute:,
-        who: Thread.current,
-        from:,
-        to:
-      ) do
-        @lock.synchronize(&block)
+    # @return [CacheConfiguration] The cache configuration for the proxy adapters.
+    attr_reader :cache_configuration
+
+    def cache_configuration=(cache_configuration)
+      synchronize_update(:cache_configuration, from: @cache_configuration, to: cache_configuration) do
+        @cache_configuration = cache_configuration
       end
     end
   end

data/lib/active_record_proxy_adapters/connection_handling/sqlite3.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+begin
+  require "active_record/connection_adapters/sqlite3_proxy_adapter"
+rescue LoadError
+  # sqlite3 not available
+  return
+end
+
+module ActiveRecordProxyAdapters
+  module SQLite3
+    # Module to extend ActiveRecord::Base with the connection handling methods.
+    # Required to make adapter work in ActiveRecord versions <= 7.2.x
+    module ConnectionHandling
+      def sqlite3_proxy_adapter_class
+        ActiveRecord::ConnectionAdapters::SQLite3ProxyAdapter
+      end
+
+      def sqlite3_proxy_connection(config)
+        connection_factory_mapping
+          .fetch("#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}")
+          .call(config)
+      end
+
+      def connection_factory_mapping
+        {
+          "7.0" => ->(config) { sqlite3_proxy_connection_ar_v70(config) },
+          "7.1" => ->(config) { sqlite3_proxy_connection_ar_v71(config) }
+        }
+      end
+
+      def sqlite3_proxy_connection_ar_v70(config) # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/MethodLength
+        config = config.symbolize_keys
+
+        # Require database.
+        raise ArgumentError, "No database file specified. Missing argument: database" unless config[:database]
+
+        # Allow database path relative to Rails.root, but only if the database
+        # path is not the special path that tells sqlite to build a database only
+        # in memory.
+        if ":memory:" != config[:database] && !config[:database].to_s.start_with?("file:") # rubocop:disable Style/YodaCondition
+          config[:database] = File.expand_path(config[:database], Rails.root) if defined?(Rails.root)
+          dirname = File.dirname(config[:database])
+          Dir.mkdir(dirname) unless File.directory?(dirname)
+        end
+
+        db = ::SQLite3::Database.new(
+          config[:database].to_s,
+          config.merge(results_as_hash: true)
+        )
+
+        sqlite3_proxy_adapter_class.new(db, logger, nil, config)
+      rescue Errno::ENOENT => e
+        raise ActiveRecord::NoDatabaseError if e.message.include?("No such file or directory")
+
+        raise
+      end
+
+      def sqlite3_proxy_connection_ar_v71(config)
+        sqlite3_proxy_adapter_class.new(config)
+      end
+    end
+  end
+end
+
+ActiveSupport.on_load(:active_record) do
+  ActiveRecord::Base.extend(ActiveRecordProxyAdapters::SQLite3::ConnectionHandling)
+end

data/lib/active_record_proxy_adapters/connection_handling.rb

@@ -3,3 +3,4 @@
 require "active_record_proxy_adapters/connection_handling/postgresql"
 require "active_record_proxy_adapters/connection_handling/mysql2"
 require "active_record_proxy_adapters/connection_handling/trilogy"
+require "active_record_proxy_adapters/connection_handling/sqlite3"

data/lib/active_record_proxy_adapters/primary_replica_proxy.rb

@@ -110,15 +110,22 @@ module ActiveRecordProxyAdapters
       end.last
     end
 
-    def roles_for(sql_string)
+    def roles_for(sql_string) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
       return [top_of_connection_stack_role] if top_of_connection_stack_role.present?
-
-      if need_all?(sql_string)
-        [reading_role, writing_role]
-      elsif need_primary?(sql_string)
-        [writing_role]
-      else
-        [reading_role]
+      return [writing_role] if recent_write_to_primary? || in_transaction?
+
+      cache_key = cache_key_for(sql_string)
+      cache_store.fetch(cache_key) do
+        ActiveSupport::Notifications.instrument("active_record_proxy_adapters.cache_miss",
+                                                cache_key: cache_key, sql: sql_string) do
+          if need_all?(sql_string)
+            [reading_role, writing_role]
+          elsif need_primary?(sql_string)
+            [writing_role]
+          else
+            [reading_role]
+          end
+        end
       end
     end
 
@@ -132,6 +139,10 @@ module ActiveRecordProxyAdapters
       [reading_role, writing_role].include?(role) ? role : nil
     end
 
+    def cache_key_for(sql_string)
+      cache_config.key_builder.call(sql_string).prepend(cache_config.key_prefix)
+    end
+
     def connected_to_stack
       return connection_class.connected_to_stack if connection_class.respond_to?(:connected_to_stack)
 
@@ -182,9 +193,7 @@ module ActiveRecordProxyAdapters
     # @return [TrueClass] if there has been a write within the last {#proxy_delay} seconds
     # @return [TrueClass] if sql_string matches a write statement (i.e. INSERT, UPDATE, DELETE, SELECT FOR UPDATE)
     # @return [FalseClass] if sql_string matches a read statement (i.e. SELECT)
-    def need_primary?(sql_string) # rubocop:disable Metrics/CyclomaticComplexity
-      return true  if recent_write_to_primary?
-      return true  if in_transaction?
+    def need_primary?(sql_string)
       return true  if cte_for_write?(sql_string)
       return true  if SQL_PRIMARY_MATCHERS.any?(&match_sql?(sql_string))
       return false if SQL_REPLICA_MATCHERS.any?(&match_sql?(sql_string))
@@ -226,6 +235,14 @@ module ActiveRecordProxyAdapters
       @last_write_at = Concurrent.monotonic_time
     end
 
+    def cache_store
+      cache_config.store
+    end
+
+    def cache_config
+      proxy_config.cache
+    end
+
     def proxy_delay
       proxy_config.proxy_delay
     end

data/lib/active_record_proxy_adapters/railtie.rb

@@ -12,6 +12,9 @@ module ActiveRecordProxyAdapters
         autoloader.inflector.inflect(
           "postgresql_proxy_adapter" => "PostgreSQLProxyAdapter"
         )
+        autoloader.inflector.inflect(
+          "sqlite3_proxy_adapter" => "SQLite3ProxyAdapter"
+        )
       end
     end
   end

data/lib/active_record_proxy_adapters/sqlite3_proxy.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "active_record_proxy_adapters/primary_replica_proxy"
+require "active_record_proxy_adapters/active_record_context"
+
+module ActiveRecordProxyAdapters
+  # Proxy to the original SQLite3Adapter, allowing the use of the ActiveRecordProxyAdapters::PrimaryReplicaProxy.
+  class SQLite3Proxy < PrimaryReplicaProxy
+  end
+end

data/lib/active_record_proxy_adapters/synchronizable_configuration.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module ActiveRecordProxyAdapters
+  module SynchronizableConfiguration # rubocop:disable Style/Documentation
+    extend ActiveSupport::Concern
+
+    included do
+      private
+
+      attr_reader :lock
+
+      def synchronize_update(attribute, from:, to:, &block)
+        ActiveSupport::Notifications.instrument(
+          "active_record_proxy_adapters.configuration_update",
+          attribute:,
+          who: Thread.current,
+          from:,
+          to:
+        ) do
+          lock.synchronize(&block)
+        end
+      end
+    end
+  end
+end

data/lib/active_record_proxy_adapters/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ActiveRecordProxyAdapters
-  VERSION = "0.4.6"
+  VERSION = "0.6.0"
 end

data/lib/active_record_proxy_adapters.rb

@@ -14,6 +14,10 @@ module ActiveRecordProxyAdapters
     yield(config)
   end
 
+  def bust_query_cache
+    config.cache.bust
+  end
+
   def config
     @config ||= Configuration.new
   end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: active_record_proxy_adapters
 version: !ruby/object:Gem::Version
-  version: 0.4.6
+  version: 0.6.0
 platform: ruby
 authors:
 - Matt Cruz
 bindir: exe
 cert_chain: []
-date: 2025-04-28 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -49,6 +49,20 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '8.1'
+- !ruby/object:Gem::Dependency
+  name: digest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.1.0
 description: |-
   This gem allows automatic connection switching between a primary and one read replica database in ActiveRecord.
   It pattern matches the SQL statement being sent to decide whether it should go to the replica (SELECT) or the
@@ -58,23 +72,27 @@ email:
 executables: []
 extensions: []
 extra_rdoc_files:
-- README.md
 - LICENSE.txt
+- README.md
 files:
 - LICENSE.txt
 - README.md
 - lib/active_record/connection_adapters/mysql2_proxy_adapter.rb
 - lib/active_record/connection_adapters/postgresql_proxy_adapter.rb
+- lib/active_record/connection_adapters/sqlite3_proxy_adapter.rb
 - lib/active_record/connection_adapters/trilogy_proxy_adapter.rb
 - lib/active_record/tasks/mysql2_proxy_database_tasks.rb
 - lib/active_record/tasks/postgresql_proxy_database_tasks.rb
+- lib/active_record/tasks/sqlite3_proxy_database_tasks.rb
 - lib/active_record/tasks/trilogy_proxy_database_tasks.rb
 - lib/active_record_proxy_adapters.rb
 - lib/active_record_proxy_adapters/active_record_context.rb
+- lib/active_record_proxy_adapters/cache_configuration.rb
 - lib/active_record_proxy_adapters/configuration.rb
 - lib/active_record_proxy_adapters/connection_handling.rb
 - lib/active_record_proxy_adapters/connection_handling/mysql2.rb
 - lib/active_record_proxy_adapters/connection_handling/postgresql.rb
+- lib/active_record_proxy_adapters/connection_handling/sqlite3.rb
 - lib/active_record_proxy_adapters/connection_handling/trilogy.rb
 - lib/active_record_proxy_adapters/database_tasks.rb
 - lib/active_record_proxy_adapters/hijackable.rb
@@ -83,6 +101,8 @@ files:
 - lib/active_record_proxy_adapters/postgresql_proxy.rb
 - lib/active_record_proxy_adapters/primary_replica_proxy.rb
 - lib/active_record_proxy_adapters/railtie.rb
+- lib/active_record_proxy_adapters/sqlite3_proxy.rb
+- lib/active_record_proxy_adapters/synchronizable_configuration.rb
 - lib/active_record_proxy_adapters/trilogy_proxy.rb
 - lib/active_record_proxy_adapters/version.rb
 homepage: https://github.com/Nasdaq/active_record_proxy_adapters
@@ -108,7 +128,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Read replica proxy adapters for ActiveRecord!
 test_files: []