distribute_reads 0.5.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 498115398e131f837029f3ad86c21ea646204b399f732a800b32687135bee154
-  data.tar.gz: 40c983fa023cab9fe00b5f0e7b03925d2f1d7c6e3d30056a26e9c147fd92d4b4
+  metadata.gz: 88f83ede9ffd2ad33f91e493d48a6c1ebcc8fc18e6334e5b708345c0f0754d9a
+  data.tar.gz: 7d7bdef9c47ee1f8689c8956a7a7480e6b9a0f0bdf6adb8b997248a643d4fc1d
 SHA512:
-  metadata.gz: 3a3a60620721ef9b23d1faf8a742386dfd58d3830ee7b110dbc44d100d7fd7670189e8893f1d21eab4d7bced008942f8fe8116756ae1aae6cec0f9427b3018d4
-  data.tar.gz: 56b65735bffb296bcfc8719c847988c0ecc4610c21ecad650115181431ac85b0b7cd686c7a409cede3cfc25c9a54de74e6f053556ea9ca6c28feb242e6ad1709
+  metadata.gz: 0e74d909cd478d90c5c0750d46287d8c6e10d1e7cd8910e4a6e3f9398f92e36fd197bec9a6986c45c982cd5d3e730327d6d99366539c87dd99734715f44c448a
+  data.tar.gz: '08d34dd833a3625fd6065e26811b0290848db014be9b5224246fdb1642f4aae0ae8ae675d9ec860699c0c5f8cd60513d442efa2e0d7e456e88570fcaff2661fa'

data/CHANGELOG.md

@@ -1,3 +1,10 @@
+## 1.0.0 (2025-09-23)
+
+- Added support for ActiveRecordProxyAdapters
+- Removed `default_to_primary` option (use `by_default` instead)
+- Dropped support for Makara
+- Dropped support for Ruby < 3.2 and Active Record < 7.1
+
 ## 0.5.0 (2024-06-24)
 
 - Dropped support for Makara 0.4

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2017-2024 Andrew Kane
+Copyright (c) 2017-2025 Andrew Kane
 
 MIT License
 

data/README.md

@@ -2,7 +2,9 @@
 
 Scale database reads to replicas in Rails
 
-:tangerine: Battle-tested at [Instacart](https://www.instacart.com/opensource)
+**Distribute Reads 1.0 was recently released** - see [how to upgrade](#upgrading)
+
+:tangerine: Battle-tested at [Instacart](https://www.instacart.com/opensource) with [Makara](https://github.com/instacart/makara)
 
 [![Build Status](https://github.com/ankane/distribute_reads/actions/workflows/build.yml/badge.svg)](https://github.com/ankane/distribute_reads/actions)
 
@@ -16,19 +18,17 @@ gem "distribute_reads"
 
 ## How to Use
 
-[Makara](https://github.com/instacart/makara) does most of the work. First, update `database.yml` to use it:
+[ActiveRecordProxyAdapters](https://github.com/Nasdaq/active_record_proxy_adapters) does most of the work. First, update `config/database.yml` to use it:
 
 ```yml
 default: &default
-  url: postgresql-makara:///
-  makara:
-    sticky: true
-    connections:
-      - role: master
-        name: primary
-        url: <%= ENV["DATABASE_URL"] %>
-      - name: replica
-        url: <%= ENV["REPLICA_DATABASE_URL"] %>
+  primary:
+    adapter: postgresql_proxy
+    url: <%= ENV["DATABASE_URL"] %>
+  replica:
+    adapter: postgresql
+    url: <%= ENV["REPLICA_DATABASE_URL"] %>
+    replica: true
 
 development:
   <<: *default
@@ -39,6 +39,14 @@ production:
 
 **Note:** You can use the same instance for the primary and replica in development.
 
+Then add `connects_to` to `app/models/application_record.rb`:
+
+```ruby
+class ApplicationRecord < ActiveRecord::Base
+  connects_to database: {writing: :primary, reading: :replica}
+end
+```
+
 By default, all reads go to the primary instance. To use the replica, do:
 
 ```ruby
@@ -74,7 +82,7 @@ You can pass any options as well.
 
 ## Lazy Evaluation
 
-Active Record uses [lazy evaluation](https://www.theodinproject.com/courses/ruby-on-rails/lessons/active-record-queries), which can delay the execution of a query to outside of a `distribute_reads` block. In this case, the primary will be used.
+Active Record uses [lazy evaluation](https://www.theodinproject.com/lessons/ruby-on-rails-active-record-queries), which can delay the execution of a query to outside of a `distribute_reads` block. In this case, the primary will be used.
 
 ```ruby
 users = distribute_reads { User.where(orders_count: 1) } # not executed yet
@@ -128,13 +136,13 @@ If no replicas are available, primary is used. To prevent this situation from ov
 
 ```ruby
 distribute_reads(failover: false) do
-  # raises DistributeReads::NoReplicasAvailable
+  # ...
 end
 ```
 
 ### Default Options
 
-Change the defaults
+Change the defaults for `distribute_reads` blocks
 
 ```ruby
 DistributeReads.default_options = {
@@ -177,7 +185,7 @@ Get replication lag in seconds
 DistributeReads.replication_lag
 ```
 
-Most of the time, Makara does a great job automatically routing queries to replicas. If it incorrectly routes a query to primary, you can use:
+Most of the time, ActiveRecordProxyAdapters does a great job automatically routing queries to replicas. If it incorrectly routes a query to primary, you can use:
 
 ```ruby
 distribute_reads(replica: true) do
@@ -195,11 +203,17 @@ ActiveRecord::Base.connected_to(role: :reading) do
 end
 ```
 
-However, it’s not able to do automatic statement-based routing like Makara yet.
+However, it’s not able to do automatic statement-based routing yet.
 
 ## Thanks
 
-Thanks to [TaskRabbit](https://github.com/taskrabbit) for Makara, [Sherin Kurian](https://github.com/sherin) for the max lag option, and [Nick Elser](https://github.com/nickelser) for the write-through cache.
+Thanks to [Nasdaq](https://github.com/Nasdaq) for ActiveRecordProxyAdapters, [TaskRabbit](https://github.com/taskrabbit) for Makara, [Sherin Kurian](https://github.com/sherin) for the max lag option, and [Nick Elser](https://github.com/nickelser) for the write-through cache.
+
+## Upgrading
+
+### 1.0
+
+ActiveRecordProxyAdapters is now used instead of Makara. Update `config/database.yml` and `app/models/application_record.rb` to [use it](#how-to-use).
 
 ## History
 

data/lib/distribute_reads/appropriate_pool.rb

@@ -1,35 +1,46 @@
 module DistributeReads
   module AppropriatePool
-    def _appropriate_pool(*args)
+    def roles_for(...)
       if Thread.current[:distribute_reads]
         if Thread.current[:distribute_reads][:replica]
-          if @slave_pool.completely_blacklisted?
-            raise DistributeReads::NoReplicasAvailable, "No replicas available" if Thread.current[:distribute_reads][:failover] == false
-            DistributeReads.log "No replicas available. Falling back to master pool."
-            @master_pool
-          else
-            @slave_pool
-          end
-        elsif Thread.current[:distribute_reads][:primary] || needs_master?(*args) || (blacklisted = @slave_pool.completely_blacklisted?)
-          if blacklisted
-            if Thread.current[:distribute_reads][:failover] == false
-              raise DistributeReads::NoReplicasAvailable, "No replicas available"
-            else
-              DistributeReads.log "No replicas available. Falling back to master pool."
-            end
-          end
-          stick_to_master(*args) if DistributeReads.by_default
-          @master_pool
-        elsif in_transaction?
-          @master_pool
+          [reading_role]
+        elsif Thread.current[:distribute_reads][:primary]
+          [writing_role]
         else
-          @slave_pool
+          super
         end
       elsif !DistributeReads.by_default
-        @master_pool
+        [writing_role]
       else
         super
       end
     end
+
+    def recent_write_to_primary?(...)
+      Thread.current[:distribute_reads] ? false : super
+    end
+
+    def connection_for(role, ...)
+      return super if role == writing_role
+
+      begin
+        super
+      rescue ActiveRecord::NoDatabaseError, ActiveRecord::ConnectionNotEstablished
+        failover = Thread.current[:distribute_reads] ? Thread.current[:distribute_reads][:failover] : true
+        raise if failover == false
+        DistributeReads.log "No replicas available. Falling back to primary."
+        super(writing_role, ...)
+      end
+    end
+
+    # defer error handling to connection_for
+    def checkout_replica_connection
+      replica_pool.checkout(proxy_checkout_timeout)
+    end
+
+    def update_primary_latest_write_timestamp(...)
+      return if !DistributeReads.by_default
+      super
+    end
   end
 end

data/lib/distribute_reads/global_methods.rb

@@ -23,7 +23,7 @@ module DistributeReads
             current_lag =
               begin
                 DistributeReads.replication_lag(connection: base_model.connection)
-              rescue DistributeReads::NoReplicasAvailable
+              rescue ActiveRecord::ConnectionNotEstablished
                 # TODO rescue more exceptions?
                 false
               end
@@ -44,7 +44,7 @@ module DistributeReads
                 # TODO possibly per connection
                 Thread.current[:distribute_reads][:primary] = true
                 Thread.current[:distribute_reads][:replica] = false
-                DistributeReads.log "#{message}. Falling back to master pool."
+                DistributeReads.log "#{message}. Falling back to primary."
                 break
               else
                 raise DistributeReads::TooMuchLag, message

data/lib/distribute_reads/job_methods.rb

@@ -7,7 +7,7 @@ module DistributeReads
     included do
       before_perform do
         if DistributeReads.by_default
-          Makara::Context.release_all
+          ActiveRecord::Base.connection.send(:proxy).send(:current_context=, nil)
         end
       end
     end

data/lib/distribute_reads/version.rb

@@ -1,3 +1,3 @@
 module DistributeReads
-  VERSION = "0.5.0"
+  VERSION = "1.0.0"
 end

data/lib/distribute_reads.rb

@@ -1,6 +1,6 @@
 # dependencies
 require "active_support"
-require "makara"
+require "active_record_proxy_adapters"
 
 # modules
 require_relative "distribute_reads/appropriate_pool"
@@ -10,7 +10,6 @@ require_relative "distribute_reads/version"
 module DistributeReads
   class Error < StandardError; end
   class TooMuchLag < Error; end
-  class NoReplicasAvailable < Error; end
 
   class << self
     attr_accessor :by_default, :default_options, :eager_load
@@ -33,14 +32,9 @@ module DistributeReads
   def self.replication_lag(connection: nil)
     connection ||= ActiveRecord::Base.connection
 
-    replica_pool = connection.instance_variable_get(:@slave_pool)
-    if replica_pool && replica_pool.connections.size > 1
-      log "Multiple replicas available, lag only reported for one"
-    end
-
     with_replica do
       case connection.adapter_name
-      when "PostgreSQL", "PostGIS"
+      when "PostgreSQL", "PostGIS", "PostgreSQLProxy"
         # cache the version number
         @aurora_postgres ||= {}
         cache_key = connection.pool.object_id
@@ -79,12 +73,12 @@ module DistributeReads
             END AS lag".squish
           ).first["lag"].to_f
         end
-      when "MySQL", "Mysql2", "Mysql2Spatial", "Mysql2Rgeo"
+      when "MySQL", "Mysql2", "Mysql2Spatial", "Mysql2Rgeo", "Mysql2Proxy", "TrilogyProxy"
         @aurora_mysql ||= {}
         cache_key = connection.pool.object_id
 
         unless @aurora_mysql.key?(cache_key)
-          # makara doesn't send SHOW queries to replica by default
+          # SHOW queries not sent to replica by default
           @aurora_mysql[cache_key] = connection.select_all("SHOW VARIABLES LIKE 'aurora_version'").any?
         end
 
@@ -129,7 +123,7 @@ module DistributeReads
     @backtrace_cleaner ||= begin
       bc = ActiveSupport::BacktraceCleaner.new
       bc.add_silencer { |line| line.include?("lib/distribute_reads") }
-      bc.add_silencer { |line| line.include?("lib/makara") }
+      bc.add_silencer { |line| line.include?("lib/active_record_proxy_adapters") }
       bc.add_silencer { |line| line.include?("lib/active_record") }
       bc
     end
@@ -146,19 +140,16 @@ module DistributeReads
     end
   end
   private_class_method :with_replica
+end
 
-  # legacy
-  def self.default_to_primary
-    !by_default
-  end
+ActiveSupport.on_load(:active_record) do
+  require "active_record_proxy_adapters/connection_handling"
+  ActiveRecordProxyAdapters::PrimaryReplicaProxy.prepend DistributeReads::AppropriatePool
 
-  # legacy
-  def self.default_to_primary=(value)
-    self.by_default = !value
-  end
+  require "active_record_proxy_adapters/log_subscriber"
+  ActiveRecord::LogSubscriber.detach_from :active_record
 end
 
-Makara::Proxy.prepend DistributeReads::AppropriatePool
 Object.include DistributeReads::GlobalMethods
 Object.send :private, :distribute_reads
 

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: distribute_reads
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Andrew Kane
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-06-24 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -16,29 +15,28 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.1'
+        version: '7.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.1'
+        version: '7.1'
 - !ruby/object:Gem::Dependency
-  name: makara
+  name: active_record_proxy_adapters
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0.5'
+        version: '0.8'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0.5'
-description:
+        version: '0.8'
 email: andrew@ankane.org
 executables: []
 extensions: []
@@ -56,7 +54,6 @@ homepage: https://github.com/ankane/distribute_reads
 licenses:
 - MIT
 metadata: {}
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -64,15 +61,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.1'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.11
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Scale database reads with replicas in Rails
 test_files: []