distribute_reads

Because ActiveRecord uses lazy evaluation, a query might not execute until it is outside the distribute_reads block, causing it to run on the primary instead of the replica.

To ensure a query runs on a replica, call .to_a or .load inside the block. Alternatively, you can enable automatic loading for all relations returned from distribute_reads blocks by setting DistributeReads.eager_load = true in an initializer.

# This might run on primary if not executed immediately
users = distribute_reads { User.where(orders_count: 1) }

# This ensures execution on the replica
users = distribute_reads { User.where(orders_count: 1).to_a }

After configuring database.yml, add connects_to to your app/models/application_record.rb to define the writing and reading roles.

class ApplicationRecord < ActiveRecord::Base
  connects_to database: {writing: :primary, reading: :replica}
end

By default, all reads go to the primary instance. Wrap code blocks in distribute_reads to route queries to the replica. This works for single queries or multiple queries within a block. Note that writes (like .save!) inside a distribute_reads block will still correctly target the primary.

# Single query
distribute_reads { User.count }

# Multiple queries
distribute_reads do
  User.find_each do |user|
    user.orders_count = user.orders.count  # replica
    user.save!                             # primary
  end
end

To use distribute_reads, you must use ActiveRecordProxyAdapters. Update your config/database.yml so that the primary connection uses a proxy URL and the replica connection uses a standard database URL with replica: true set.

• Primary URL: Must start with postgresql-proxy://, mysql2-proxy://, or trilogy-proxy://.
• Replica URL: Must start with postgresql://, mysql2://, or trilogy://.

default: &default
  primary:
    # should start with postgresql-proxy://, mysql2-proxy://, or trilogy-proxy://
    url: <%= ENV["DATABASE_URL"] %>
  replica:
    # should start with postgresql://, mysql2://, or trilogy://
    url: <%= ENV["REPLICA_DATABASE_URL"] %>
    replica: true

development:
  <<: *default

production:
  <<: *default

Add the gem to your application's Gemfile to begin scaling database reads to replicas in Rails.

gem "distribute_reads"

You can distribute all reads within an ApplicationJob by calling distribute_reads at the class level. You can also pass configuration options to the class method.

class TestJob < ApplicationJob
  distribute_reads

  def perform
    # ...
  end
end

If ActiveRecordProxyAdapters incorrectly routes a query to the primary, you can explicitly force all queries within a block to use the replica by passing replica: true.

distribute_reads(replica: true) do
  # send all queries in block to replica
end

Use DistributeReads.replication_lag to retrieve the current replication lag in seconds.

lag = DistributeReads.replication_lag

You can configure the global behavior of DistributeReads using the following attributes on the DistributeReads module:

• by_default: A boolean indicating if read distribution should be active by default.
• default_options: A hash of options applied to read operations. Default values are { failover: true, lag_failover: false }.
• eager_load: A boolean to enable/disable eager loading.
• logger: An optional logger. If not set, it defaults to ActiveRecord::Base.logger.

If you specify a :max_lag and :lag_failover is set to false (the default), distribute_reads will raise a DistributeReads::TooMuchLag error if the replication lag exceeds the threshold.

Common error messages include:

• "Replication stopped on [Model] connection" (if lag cannot be determined)
• "No replicas available for lag check on [Model] connection"
• "Replica lag over [X] seconds on [Model] connection"