百科.dev
全部条目在线工具AI 编程趋势榜开源项目技术资讯提交条目
登录
< 返回工具列表
D

distribute_reads

> 编程语言
开源

在 Rails 中扩展数据库读取到副本

370 stars0 点赞0 次浏览
访问官网GitHub

工具介绍

在 Rails 中扩展数据库读取到副本

Distribute Reads

Scale database reads to replicas in Rails

Distribute Reads 1.0 was recently released - see how to upgrade

:tangerine: Battle-tested at Instacart with Makara

Installation

Add this line to your application’s Gemfile:

ruby
gem "distribute_reads"

How to Use

ActiveRecordProxyAdapters does most of the work. First, update config/database.yml to use it:

yaml
default: &default
  primary:
    # should start with postgresql-proxy://, mysql2-proxy://, or trilogy-proxy://
    url: 
  replica:
    # should start with postgresql://, mysql2://, or trilogy://
    url: 
    replica: true

development:
  <<: *default

production:
  <<: *default

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
distribute_reads { User.count }

Works with multiple queries as well.

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

Jobs

Distribute all reads in a job with:

ruby
class TestJob < ApplicationJob
  distribute_reads

  def perform
    # ...
  end
end

You can pass any options as well.

Lazy Evaluation

Active Record uses lazy evaluation, 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

Call to_a or load inside the block to ensure the query runs on a replica.

ruby
users = distribute_reads { User.where(orders_count: 1).to_a }

You can automatically load relations returned from distribute_reads blocks by creating an initializer with:

ruby
DistributeReads.eager_load = true

Options

Replica Lag

Raise an error when replica lag is too high (specified in seconds)

ruby
distribute_reads(max_lag: 3) do
  # raises DistributeReads::TooMuchLag
end

Instead of raising an error, you can also use primary

ruby
distribute_reads(max_lag: 3, lag_failover: true) do
  # ...
end

If you have multiple databases, this only checks lag on ActiveRecord::Base connection. Specify connections to check with

ruby
distribute_reads(max_lag: 3, lag_on: [ApplicationRecord, LogRecord]) do
  # ...
end

Note: If lag on any connection exceeds the max lag and lag failover is used, all connections will use their primary.

Availability

If no replicas are available, primary is used. To prevent this situation from overloading the primary, you can raise an error instead.

ruby
distribute_reads(failover: false) do
  # ...
end

Default Options

Change the defaults for distribute_reads blocks

ruby
DistributeReads.default_options = {
  lag_failover: true,
  failover: false
}

Logging

Messages about failover are logged to the Active Record logger by default. Set a different logger with:

ruby
DistributeReads.logger = Logger.new(STDERR)

Or use nil to disable logging.

Distribute Reads by Default

At some point, you may wish to distribute reads by default.

ruby
DistributeReads.by_default = true

To make queries go to primary, use:

ruby
distribute_reads(primary: true) do
  # ...
end

Reference

Get replication lag in seconds

ruby
DistributeReads.replication_lag

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
  # send all queries in block to replica
end

Rails

Rails 6+ has native support for replicas :tada:

ruby
ActiveRecord::Base.connected_to(role: :reading) do
  # do reads
end

However, it’s not able to do automatic statement-based routing yet.

Thanks

Thanks to Nasdaq for ActiveRecordProxyAdapters, TaskRabbit for Makara, Sherin Kurian for the max lag option, and Nick Elser 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.

History

View the changelog

Contributing

Everyone is encouraged to help improve this project. Here are a few ways you can help:

  • Report bugs
  • Fix bugs and submit pull requests
  • Write, clarify, or fix documentation
  • Suggest or add new features

To get started with development and testing:

bash
git clone https://github.com/ankane/distribute_reads.git
cd distribute_reads
createdb distribute_reads_test_primary
createdb distribute_reads_test_replica
bundle install
bundle exec rake test

Issues· 0 开放

查看全部 Issues在 GitHub 打开

暂无开放 Issues,或尚未同步最近议题。

> 标签

Ruby

暂无评论,来聊聊你的看法吧

> 工具信息

发布日期2026年8月1日
最后更新2026年9月17日
分类编程语言
定价开源

> 相关工具

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言