resilient_reads 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e9ca59bd308356c26b2f833ae03fff90e58733e58e1c972c2eed7f84997e1f72
-  data.tar.gz: bb1eeee56723a1856ec9204b8cd3a8e521fc332d8ab26b0a3c68a538910726b4
+  metadata.gz: ec873d08dc27b40673379ea070233b0aa06ce97f75adc77b9b43b29265be38b1
+  data.tar.gz: b0fb02179cdf69e5859f2d3ec1e0910d122590a92d876665d9d398414ca56ab7
 SHA512:
-  metadata.gz: c443fc6041771447152fbf30c42df9e6aabfbd1a626da0454a102d320c52c2da687e6d9ee196e9caf03a35057de7eb91e1233b785c474c3dc14034962b15b4b1
-  data.tar.gz: 59acea745a3fc0e690607fca23f39e342ccf8a1350a813267336f16491609ea16e10d7fb5739278a45abcd888718a5f0352e760e59c414bc16fcf7f730fafca6
+  metadata.gz: 0d370a34eae6f0a3ff3206547705fd832ecc59a48597661db41cf35f94369140e7d8e0cd68297b98e5db6918cdd3ccca61144d5583612f40a6910cf56f8b9f19
+  data.tar.gz: 2ca096b7bed1ce980eb914bca296c0d015e2766026f621881a545ef09efbbaa63cbd2cd3151b6409718af145e2065029a7c4223de31fe3cef2393062fc44836b

data/README.md

@@ -1,39 +1,217 @@
-# ResilientReads
+# Resilient Reads
 
-TODO: Delete this and the text below, and describe your gem
+Distribute database reads across multiple replicas in Rails with **automatic load balancing**, **health checking**, and **graceful failover** to primary.
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/resilient_reads`. To experiment with that code, run `bin/console` for an interactive prompt.
+Drop-in replacement for [distribute_reads](https://github.com/ankane/distribute_reads) that adds:
+
+- **Multiple replica support** with round-robin or random load balancing across any number of replicas
+- **Graceful failover** — if a replica goes down, reads automatically fall back to primary. No boot crash.
+- **Health monitoring** — background thread periodically re-checks unhealthy replicas and restores them
+- **Per-query logging** — see exactly which connection (primary / replica name) handled each query
+- **No proxy adapter needed** — works with the standard `postgresql`, `mysql2`, or `trilogy` adapters
+- **Rails 7.1+ compatible** — works with Rails 7.1, 7.2, and 8.0+
+- **Query pattern caching** — caches SQL read/write classification results in an LRU cache to avoid repeated regex matching
+- **Lag check caching** — replication lag results are cached per-replica with a configurable TTL (default 5s) to avoid querying lag on every read
+- **Backward compatible** — `distribute_reads { }` and `DistributeReads.by_default = true` still work
 
 ## Installation
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+Add to your Gemfile:
+
+```ruby
+gem "resilient_reads", path: "gems/resilient_reads"
+```
+
+Remove any previous read-distribution gems:
 
-Install the gem and add to the application's Gemfile by executing:
+```ruby
+# Remove these:
+# gem "distribute_reads"
+# gem "active_record_proxy_adapters"
+```
 
-```bash
-bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+## Configuration
+
+### database.yml
+
+Use the **standard adapter** (`postgresql`, `mysql2`, or `trilogy`) for all connections. Mark replicas with `replica: true`:
+
+```yaml
+default: &default
+  adapter: postgresql
+  pool: 5
+
+production:
+  primary:
+    <<: *default
+    host: primary-db.example.com
+    database: myapp_production
+  replica:
+    <<: *default
+    host: replica1.example.com
+    database: myapp_production
+    replica: true
+  replica2:
+    <<: *default
+    host: replica2.example.com
+    database: myapp_production
+    replica: true
+  replica3:
+    <<: *default
+    host: replica3.example.com
+    database: myapp_production
+    replica: true
 ```
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+You can add as many replicas as you want — they are auto-detected by matching config names against `/replica\d*/` with `replica: true`. Or list them explicitly:
+
+```ruby
+config.replicas = [:replica, :replica2, :replica3]
+```
+
+### Initializer
+
+```ruby
+# config/initializers/resilient_reads.rb
+ResilientReads.configure do |config|
+  config.by_default = true             # Route all reads to replicas
+  config.eager_load = true             # Auto-load lazy relations in blocks
+  config.balancing_strategy = :round_robin  # :round_robin or :random
+  config.health_check_interval = 30    # Seconds between health checks
+  config.max_lag = nil                 # Max replication lag (seconds), nil to skip
+  config.lag_failover = true           # Use primary when lag exceeds max
+  config.failover = true               # Fall back to primary when replicas are down
+  config.primary_delay = 2             # Seconds to use primary after a write
+  config.log_query_routing = true      # Log which connection handled each query
+  config.lag_check_interval = 5        # Seconds to cache lag check per replica
+  config.query_cache_enabled = true    # Cache SQL pattern matching results
+  config.query_cache_max_size = 10_000 # Max entries in the query cache
+  config.sticky_writes = true          # After a write, reads stay on primary for the block
+end
+```
+
+### Model
+
+Keep your existing `connects_to` — the gem works alongside it:
 
-```bash
-gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+```ruby
+class ApplicationRecord < ActiveRecord::Base
+  primary_abstract_class
+  connects_to database: { writing: :primary, reading: :replica }
+end
 ```
 
 ## Usage
 
-TODO: Write usage instructions here
+### Explicit blocks
+
+```ruby
+distribute_reads { User.count }   # Reads from a healthy replica
+
+distribute_reads do
+  User.find_each do |user|
+    user.orders_count = user.orders.count  # replica (SELECT)
+    user.save!                             # primary (INSERT/UPDATE)
+  end
+end
+```
+
+### Options
+
+```ruby
+distribute_reads(primary: true) { ... }          # Force primary
+distribute_reads(max_lag: 3) { ... }             # Override max lag
+distribute_reads(max_lag: 3, lag_failover: true)  # Fallback on high lag
+distribute_reads(failover: false) { ... }         # Raise if no replicas
+```
+
+### Jobs
+
+```ruby
+class ReportJob < ApplicationJob
+  distribute_reads
+
+  def perform
+    # All reads go to replicas
+  end
+end
+```
+
+### By default
+
+When `config.by_default = true`, a Rack middleware automatically wraps
+GET/HEAD requests so all reads hit replicas. After a write (POST/PUT/etc),
+reads stay on primary for `primary_delay` seconds (read-your-own-write).
+
+## Query Routing Log
+
+When `config.log_query_routing = true` (the default), every routed query is logged with the connection it used:
+
+```
+[ResilientReads] → replica 'replica' | User Load | SELECT "users".* FROM "users" WHERE …
+[ResilientReads] → replica 'replica2' | Order Load | SELECT "orders".* FROM "orders" …
+[ResilientReads] → primary (write query) | User Update | UPDATE "users" SET "name" = …
+[ResilientReads] → primary (no healthy replicas) | User Load | SELECT "users".* …
+```
+
+This makes it easy to verify that load balancing is working and which replica handled each query. Set `config.log_query_routing = false` to disable.
+
+## Query Pattern Caching
+
+When `config.query_cache_enabled = true` (the default), the gem caches the result of SQL pattern matching (whether a query is a read or write) in an in-memory LRU cache. This avoids running the regex on every identical query string.
+
+```ruby
+# View cache stats
+ResilientReads.query_cache.stats  # => { hits: 1234, misses: 56, size: 56 }
+
+# Clear the cache manually
+ResilientReads.bust_query_cache!
+```
+
+Disable with `config.query_cache_enabled = false`.
+
+## Lag Check Caching
+
+When `config.max_lag` is set, replication lag is checked for each replica. To avoid querying the replica for lag on **every single read**, the lag value is cached per-replica for `config.lag_check_interval` seconds (default 5). This means the actual lag query runs at most once every 5 seconds per replica, not on every read.
+
+```ruby
+config.lag_check_interval = 10  # Cache lag result for 10 seconds
+```
+
+## How it works
+
+1. **Adapter-level interception** — the gem prepends on the database adapter's
+   `raw_execute`. SELECT queries inside a `distribute_reads` block are routed to
+   a healthy replica connection; writes pass through to the primary. Supports
+   PostgreSQL, MySQL2, and Trilogy adapters.
+
+2. **Separate connection pools** — each replica has its own ActiveRecord connection
+   pool (via a lightweight abstract class). Pools are lazy: no actual DB connection
+   until the first query, so replicas can be unavailable at boot without crashing.
+
+3. **Health checking** — a background thread periodically runs `SELECT 1` against
+   each replica. Unhealthy replicas are removed from rotation and restored once
+   they recover.
 
-## Development
+4. **Load balancing** — round-robin (default) or random selection across healthy
+   replicas. Works with any number of replicas.
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+5. **Replication lag** — supports PostgreSQL WAL-based lag detection and MySQL
+   `SHOW REPLICA STATUS` / `Seconds_Behind_Master` lag checking. Lag values are
+   cached per-replica with a configurable TTL to avoid per-query overhead.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+6. **Query pattern caching** — SQL read/write classification results are cached
+   in an LRU cache (configurable max size) to avoid repeated regex matching.
 
-## Contributing
+## Migrating from distribute_reads
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/resilient_reads.
+1. Replace `gem "distribute_reads"` with `gem "resilient_reads"`
+2. In `database.yml`, change `adapter: postgresql_proxy` to `adapter: postgresql`
+3. Your existing initializer (`DistributeReads.by_default = true` etc.) will
+   continue to work via the backward-compatibility shim
+4. Optionally convert to the new `ResilientReads.configure` block
+5. Add extra replicas to `database.yml` — they're auto-detected
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+MIT

data/lib/resilient_reads/adapter_patch.rb

@@ -13,6 +13,10 @@ module ResilientReads
     # model loading and connection setup.
     SKIP_NAMES = Set.new(%w[SCHEMA EXPLAIN]).freeze
 
+    # SQL clauses that acquire locks and must execute on the primary,
+    # even though the statement starts with SELECT.
+    LOCKING_CLAUSE_PATTERN = /\b(FOR\s+(UPDATE|NO\s+KEY\s+UPDATE|SHARE|KEY\s+SHARE)|LOCK\s+IN\s+SHARE\s+MODE)\b/i
+
     def raw_execute(sql, *args, **kwargs)
       ctx = Thread.current[:resilient_reads_context]
       name = args.first
@@ -21,13 +25,27 @@ module ResilientReads
          ctx[:distributing] &&
          !ctx[:on_replica] &&
          !ctx[:routing] &&
+         !ctx[:stick_to_primary] &&
          !skip_replica_routing?(sql, name) &&
          open_transactions.zero?
 
         execute_on_replica(sql, ctx, *args, **kwargs)
       else
-        if ctx && ctx[:distributing] && write_query?(sql)
-          ResilientReads.log_query("primary", sql, name, reason: "write query")
+        if ctx && ctx[:distributing]
+          if write_query?(sql)
+            # Sticky writes: after any write inside a distribute_reads
+            # block, all subsequent reads stay on primary for the rest of
+            # the block.  This prevents stale-read → conflicting-write
+            # chains that cause MySQL/InnoDB deadlocks, especially with
+            # transactionless writes like update_column that don't bump
+            # open_transactions.
+            if ResilientReads.config.sticky_writes
+              ctx[:stick_to_primary] = true
+            end
+            ResilientReads.log_query("primary", sql, name, reason: "write query")
+          elsif ctx[:stick_to_primary]
+            ResilientReads.log_query("primary", sql, name, reason: "sticky write")
+          end
         end
         super(sql, *args, **kwargs)
       end
@@ -41,17 +59,25 @@ module ResilientReads
       return true if name.nil? || name == ""
       return true if SKIP_NAMES.include?(name)
       return true if write_query?(sql)
+      return true if locking_query?(sql)
       false
     end
 
+    # Detects SELECT statements that acquire row/table locks
+    # (e.g. SELECT ... FOR UPDATE, LOCK IN SHARE MODE).  These must
+    # execute on the primary — a read-only replica cannot acquire locks.
+    def locking_query?(sql)
+      LOCKING_CLAUSE_PATTERN.match?(sql)
+    end
+
     def execute_on_replica(sql, ctx, *args, **kwargs)
-      # Ensure the primary adapter is connected and its type_map is
-      # initialized.  After raw_execute returns the replica's PG::Result,
-      # the caller (cast_result) invokes get_oid_type on *self* (primary)
-      # to resolve column OIDs.  If all prior reads were routed to replicas,
-      # the primary connection was never materialized — leaving @type_map
-      # nil and causing: NoMethodError: undefined method `key?' for nil.
-      connect! unless type_map
+      # Ensure the primary adapter is connected.  If all prior reads
+      # were routed to replicas, the primary connection was never
+      # materialized.  For PostgreSQL this avoids a nil @type_map
+      # (cast_result → get_oid_type → NoMethodError).  For MySQL/Trilogy
+      # it keeps the primary connection alive so the first write after
+      # many reads doesn't hit a stale/timed-out socket.
+      connect! unless connected?
 
       replica = ResilientReads.replica_pool.next_healthy
 
@@ -84,8 +110,8 @@ module ResilientReads
         ctx[:routing] = false
         result
       rescue ActiveRecord::ConnectionNotEstablished,
-             ActiveRecord::StatementInvalid,
-             ActiveRecord::ConnectionFailed => e
+        ActiveRecord::StatementInvalid,
+        ActiveRecord::ConnectionFailed => e
         ctx[:routing] = false
         raise unless connection_level_error?(e)
 
@@ -136,6 +162,10 @@ module ResilientReads
         cause = error.cause
         cause.is_a?(PG::Error) ||
           cause.is_a?(IOError) ||
+          cause.is_a?(Errno::ETIMEDOUT) ||
+          cause.is_a?(Errno::ECONNRESET) ||
+          cause.is_a?(Errno::EPIPE) ||
+          cause.is_a?(Errno::ECONNREFUSED) ||
           (defined?(PG::ConnectionBad) && cause.is_a?(PG::ConnectionBad)) ||
           (defined?(Trilogy::Error) && cause.is_a?(Trilogy::Error)) ||
           (defined?(Mysql2::Error) && cause.is_a?(Mysql2::Error))
@@ -144,4 +174,4 @@ module ResilientReads
       end
     end
   end
-end
+end

data/lib/resilient_reads/configuration.rb

@@ -66,6 +66,12 @@ module ResilientReads
     # Maximum number of entries in the SQL pattern cache.
     attr_accessor :query_cache_max_size
 
+    # When true (default), a write inside a distribute_reads block causes
+    # all subsequent reads in the same block to go to primary.  This
+    # prevents stale-read → conflicting-write chains that cause deadlocks,
+    # especially with transactionless writes like update_column.
+    attr_accessor :sticky_writes
+
     def initialize
       @by_default = false
       @eager_load = false
@@ -85,6 +91,7 @@ module ResilientReads
       @default_options = {}
       @query_cache_enabled = true
       @query_cache_max_size = 10_000
+      @sticky_writes = true
     end
   end
-end
+end

data/lib/resilient_reads/lag_checker.rb

@@ -45,24 +45,29 @@ module ResilientReads
     end
 
     def self.lag_for_mysql(conn)
-      result = conn.execute("SHOW REPLICA STATUS")
-      # MySQL 8.0.22+ uses SHOW REPLICA STATUS
+      # Prefer SHOW REPLICA STATUS (MySQL 8.0.22+, MariaDB 10.5.1+)
+      # and fall back to the deprecated SHOW SLAVE STATUS.
+      result =
+        begin
+          conn.execute("SHOW REPLICA STATUS")
+        rescue ActiveRecord::StatementInvalid
+          conn.execute("SHOW SLAVE STATUS")
+        end
 
       row = if result.respond_to?(:first)
               result.first
-      elsif result.respond_to?(:to_a)
+            elsif result.respond_to?(:to_a)
               result.to_a.first
-      end
+            end
 
       return nil unless row
 
-      # Seconds_Behind_Master / Seconds_Behind_Source (MySQL 8.0.22+)
-      lag =
-        if row.is_a?(Hash)
-              row["Seconds_Behind_Source"]
-        elsif row.respond_to?(:[])
-              row["Seconds_Behind_Source"]
-        end
+      # Seconds_Behind_Source (MySQL 8.0.22+) / Seconds_Behind_Master (legacy)
+      lag = if row.is_a?(Hash)
+              row["Seconds_Behind_Source"] || row["Seconds_Behind_Master"]
+            elsif row.respond_to?(:[])
+              row["Seconds_Behind_Source"] || row["Seconds_Behind_Master"]
+            end
 
       lag&.to_f
     rescue => e
@@ -70,4 +75,4 @@ module ResilientReads
       nil
     end
   end
-end
+end

data/lib/resilient_reads/version.rb

@@ -1,3 +1,3 @@
 module ResilientReads
-  VERSION = "0.1.2"
+  VERSION = "0.1.3"
 end

data/lib/resilient_reads.rb

@@ -61,6 +61,7 @@ module ResilientReads
         distributing: true,
         on_replica: false,
         routing: false,
+        stick_to_primary: false,
         options: opts
       }
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: resilient_reads
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
 platform: ruby
 authors:
 - Jamie Puckett