activerecord-wait_for_lsn 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: cbd7e6e0f5eb7df644152b7ca91788239c5fbbc650ccd1fc6e17666cf70c0f85
+  data.tar.gz: f7d5f9438d176acf4b937a1786b570cd1253092ee8de6aacb7e392dabdf4e77f
+SHA512:
+  metadata.gz: 706c03870f25a5f9ea1642d2825b5eacc1a83cc617460e201f47f4b200db63aa8ef218cf4e2611d57048f235cd4c67e7786bb4082fa63aea37e090c51f09fdf6
+  data.tar.gz: 56f9d278efbd92800270b8bc35e1c2034e56567276fe3033f4a763d2a2faa0e7bd265b3e500fbe2106fcd865d70213ab812a2201dbb4c07aa24f9e985a985617

data/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+## 0.1.0 - 2026-09-04
+
+First release.
+
+- Keep the replica connection leased for the whole request. `WAIT FOR LSN`
+  and every read that follows now run on the same connection, so the guarantee
+  holds behind a TCP load balancer or a libpq multi-host `host=a,b` where the
+  pool's connections point at different standbys. Before, the read could pick
+  another pooled connection and land on a standby that had not replayed the
+  LSN yet.
+- Add `database` (the `database.yml` entry name) to the `read_from_replica`,
+  `read_from_primary` and `wait_for_lsn` event payloads.
+- Add an opt-in Yabeda integration: `require "active_record/wait_for_lsn/yabeda"`
+  and `ActiveRecord::WaitForLSN::Yabeda.collect_replication_lag!` fill
+  `wait_for_lsn_replication_lag_seconds` and `wait_for_lsn_replication_lag_bytes`
+  per standby from `pg_stat_replication` on every export.
+- Drop the `mode` option. The wait always uses `standby_replay`, the only mode
+  that guarantees a following `SELECT` on the replica sees the write.
+  `standby_write` and `standby_flush` only confirm WAL arrival, so a read could
+  still miss a fresh row or return a stale one. `primary_flush` is primary-only
+  and never applied to the replica wait.
+- Rename `timeout` to `wait_timeout` and lower the default from `500ms` to
+  `20ms`.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 izhanov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,152 @@
+# activerecord-wait_for_lsn
+
+Read-your-writes on Rails read replicas via PostgreSQL 19
+[`WAIT FOR LSN`](https://www.postgresql.org/docs/19/sql-wait-for.html).
+
+After a write the resolver stores the primary's `pg_current_wal_lsn()` in the
+session. Before a read it runs `WAIT FOR LSN` on the replica. If the replica has
+caught up, the read goes to the replica, otherwise to the primary.
+
+## Usage
+
+```ruby
+# Gemfile
+gem "activerecord-wait_for_lsn"
+```
+
+```ruby
+# config/initializers/multi_db.rb
+Rails.application.configure do
+  config.active_record.database_selector = { wait_timeout: "50ms" } # default 20ms
+  config.active_record.database_resolver = ActiveRecord::WaitForLSN::Resolver
+  config.active_record.database_resolver_context = ActiveRecord::WaitForLSN::Session
+end
+```
+
+Requires PostgreSQL 19, a streaming standby configured as `replica: true`, and
+Rails 7.2+.
+
+## Options
+
+Passed through the `database_selector` hash.
+
+| Option     | Default            | Description |
+|------------|--------------------|-------------|
+| `wait_timeout` | `"20ms"` | How long to wait for the replica before reading from the primary. Any PostgreSQL interval literal: `"200ms"`, `"1s"`. |
+| `no_throw`     | `true`   | Return a status (`success`, `timeout`, `not in recovery`) instead of raising on timeout. |
+
+## Several replicas
+
+Rails has one reading role per class, so several standbys sit behind one
+`replica` entry: a TCP load balancer (HAProxy, PgBouncer in session mode) or
+libpq's own multi-host connection string. With PostgreSQL 16+ libpq the entry
+can spread connections itself:
+
+```yaml
+replica:
+  <<: *default
+  host: standby1,standby2,standby3
+  port: "5432,5432,5432" # quoted, or YAML reads it as one number
+  load_balance_hosts: random
+  replica: true
+```
+
+Every request leases one replica connection: the `WAIT FOR LSN` and all reads
+of the request run over that connection, hence on the same standby, whichever
+one the pool handed out. Transaction-pooling proxies that spread the statements
+of one client connection over several servers break the guarantee.
+
+Note that `load_balance_hosts` balances connections, not requests: libpq picks
+a host when a connection is opened, and the pool then reuses its most recently
+returned connections first. Under light load a couple of pooled connections
+serve most requests, so the standbys they landed on see most of the reads.
+For an even spread per request put a round-robin TCP balancer in front of the
+standbys.
+
+Which standby is behind and by how much is visible per standby through the
+[lag metrics](#metrics), which come from `pg_stat_replication` on the primary
+and cover every streaming standby, whether or not it takes reads.
+
+## Wait mode
+
+The wait always uses `MODE 'standby_replay'`: the LSN must be applied on the
+standby, so a following `SELECT` sees the write. The other modes
+(`standby_write`, `standby_flush`) only confirm the WAL has arrived on the
+standby, not that it is visible, so they are not exposed.
+
+## Instrumentation
+
+Each wait emits `database_selector.active_record.wait_for_lsn` with `lsn`,
+`lsn_status` and `database` (the `database.yml` entry of the standby) in the
+payload. On `success` the event duration is how long the replica took to
+replay your last write. `database_selector.active_record.read_from_replica`
+and `database_selector.active_record.read_from_primary` fire around every read,
+also with `database` in the payload, so per-replica counters are one
+subscriber away:
+
+```ruby
+ActiveSupport::Notifications.subscribe("database_selector.active_record.wait_for_lsn") do |event|
+  Rails.logger.info "WAIT FOR LSN on #{event.payload[:database]}: #{event.payload[:lsn_status]} in #{event.duration.round}ms"
+end
+```
+
+## Metrics
+
+An opt-in [Yabeda](https://github.com/yabeda-rb/yabeda) integration exports
+replication lag per standby. Add Yabeda and an exporter to the Gemfile:
+
+```ruby
+gem "yabeda"
+gem "yabeda-prometheus" # or yabeda-datadog, yabeda-statsd, ...
+```
+
+Then require the integration from an initializer and opt in:
+
+```ruby
+# config/initializers/multi_db.rb
+require "active_record/wait_for_lsn/yabeda"
+ActiveRecord::WaitForLSN::Yabeda.collect_replication_lag!
+```
+
+Before every export (each Prometheus scrape) it runs one query against the
+primary and sets two gauges per streaming standby, replay stage only, since
+that is the point at which a `SELECT` on the standby sees the write:
+
+| Metric | Tags | Description |
+|--------|------|-------------|
+| `wait_for_lsn_replication_lag_seconds` | `standby` | `replay_lag` from `pg_stat_replication`. |
+| `wait_for_lsn_replication_lag_bytes` | `standby` | `pg_current_wal_lsn() - replay_lsn`. |
+
+`standby` is the `application_name` the standby sets in `primary_conninfo`,
+which falls back to its `cluster_name`.
+
+Why `pg_stat_replication` and not the wait itself: the duration of the
+`wait_for_lsn` event is how long a request waited for its own write, capped by
+`wait_timeout`. A replica that caught up before the next request arrives shows
+a wait of zero. The real lag is measured by PostgreSQL from standby feedback.
+Per-request counters (reads by role, wait statuses) are yours to build from the
+events above if you need them.
+
+Requirements and caveats:
+
+- The application's database role needs `pg_read_all_stats` (or superuser),
+  otherwise the lag columns are `NULL` for every row:
+  ```sql
+  GRANT pg_read_all_stats TO app;
+  ```
+- PostgreSQL reports `NULL` once a standby is fully caught up and the primary
+  is idle. Both gauges record it as `0`.
+- The query runs on the writing connection with `prevent_writes: true` and
+  costs one round trip per scrape, not per request.
+
+```promql
+# Replay lag per standby, the number DBAs see in pg_stat_replication
+wait_for_lsn_replication_lag_seconds
+
+# Alert when a standby falls more than a second behind
+max(wait_for_lsn_replication_lag_seconds) > 1
+```
+
+## License
+
+MIT

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/lib/active_record/wait_for_lsn/read_query_patch.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module WaitForLSN
+    module ReadQueryPatch
+      WAIT_FOR = /\A(?:\s|\()*WAIT\s+FOR\b/i
+
+      def write_query?(sql)
+        return false if WAIT_FOR.match?(sql)
+
+        super
+      end
+    end
+  end
+end

data/lib/active_record/wait_for_lsn/resolver.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module WaitForLSN
+    class Resolver < ::ActiveRecord::Middleware::DatabaseSelector::Resolver
+      DEFAULT_LSN_TIMEOUT = "20ms"
+      DEFAULT_LSN_NO_THROW = true
+      LSN_MODE = "standby_replay"
+      LSN_OUTPUT_SUCCESS = "success"
+
+      attr_reader :wait_timeout, :no_throw
+
+      def initialize(context, options = {})
+        super
+        @wait_timeout = options.fetch(:wait_timeout, DEFAULT_LSN_TIMEOUT)
+        @no_throw = options.fetch(:no_throw, DEFAULT_LSN_NO_THROW)
+      end
+
+      def read(&blk)
+        super
+      ensure
+        release_replica_connection
+      end
+
+      private
+
+      def write_to_primary
+        ActiveRecord::Base.connected_to(role: ActiveRecord.writing_role, prevent_writes: false) do
+          instrumenter.instrument("database_selector.active_record.write_to_primary") do
+            yield
+          ensure
+            context.update_last_write_lsn(current_write_lsn)
+          end
+        end
+      end
+
+      def read_from_primary(&blk)
+        ActiveRecord::Base.connected_to(role: ActiveRecord.writing_role, prevent_writes: true) do
+          instrumenter.instrument("database_selector.active_record.read_from_primary", database: database_name, &blk)
+        end
+      end
+
+      def read_from_replica(&blk)
+        connected_to_replica(prevent_writes: true) do
+          instrumenter.instrument("database_selector.active_record.read_from_replica", database: database_name, &blk)
+        end
+      end
+
+      def read_from_primary?
+        lsn = context.last_write_lsn
+        return false unless lsn
+        return false if wait_for_lsn(lsn) == LSN_OUTPUT_SUCCESS
+
+        release_replica_connection
+        true
+      rescue ActiveRecord::StatementInvalid, ActiveRecord::ConnectionNotDefined
+        release_replica_connection
+        true
+      end
+
+      def wait_for_lsn(lsn)
+        connected_to_replica do
+          conn = ActiveRecord::Base.connection_pool.lease_connection
+          query = "WAIT FOR LSN #{conn.quote(lsn)} WITH (#{wait_for_lsn_options})"
+          payload = { lsn: lsn, database: database_name }
+          instrumenter.instrument("database_selector.active_record.wait_for_lsn", payload) do |p|
+            p[:lsn_status] = conn.select_value(query)
+          end
+        end
+      end
+
+      def release_replica_connection
+        connected_to_replica do
+          ActiveRecord::Base.connection_pool.release_connection
+        end
+      rescue ActiveRecord::ConnectionNotDefined
+        nil
+      end
+
+      def connected_to_replica(prevent_writes: false, &blk)
+        ActiveRecord::Base.connected_to(role: ActiveRecord.reading_role, prevent_writes: prevent_writes, &blk)
+      end
+
+      def database_name
+        ActiveRecord::Base.connection_pool.db_config.name
+      rescue ActiveRecord::ConnectionNotDefined
+        nil
+      end
+
+      def current_write_lsn
+        ActiveRecord::Base.connection_pool.with_connection do |conn|
+          conn.select_value("SELECT pg_current_wal_lsn();")
+        end
+      end
+
+      def wait_for_lsn_options
+        options = { timeout: wait_timeout, mode: LSN_MODE, no_throw: no_throw }
+        options.filter_map do |(opt, val)|
+          next unless val
+
+          opt == :no_throw ? opt.to_s.upcase : "#{opt.upcase} '#{val}'"
+        end.join(", ")
+      end
+    end
+  end
+end

data/lib/active_record/wait_for_lsn/session.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module WaitForLSN
+    class Session < ::ActiveRecord::Middleware::DatabaseSelector::Resolver::Session
+      def last_write_lsn
+        session[:last_write_lsn]
+      end
+
+      def update_last_write_lsn(new_lsn)
+        session[:last_write_lsn] = new_lsn
+      end
+    end
+  end
+end

data/lib/active_record/wait_for_lsn/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module WaitForLSN
+    VERSION = "0.1.0"
+  end
+end

data/lib/active_record/wait_for_lsn/yabeda.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "yabeda"
+
+module ActiveRecord
+  module WaitForLSN
+    # Opt-in Yabeda metrics. Not loaded automatically; require it from an initializer:
+    #
+    #   require "active_record/wait_for_lsn/yabeda"
+    #   ActiveRecord::WaitForLSN::Yabeda.collect_replication_lag!
+    #
+    # Registers the +wait_for_lsn+ group with replication lag gauges per standby.
+    # They are filled before every export by querying +pg_stat_replication+ on the
+    # primary, which needs +pg_read_all_stats+. Metrics are recorded once
+    # +Yabeda.configure!+ has run, which Yabeda's own Railtie does after the app
+    # is initialized.
+    module Yabeda
+      # Replay stage only: the point at which a SELECT on the standby sees the write.
+      REPLICATION_LAG_SQL = <<~SQL
+        SELECT application_name,
+               pg_current_wal_lsn() - replay_lsn AS replay_lag_bytes,
+               EXTRACT(EPOCH FROM replay_lag)   AS replay_lag_seconds
+        FROM pg_stat_replication
+        WHERE state = 'streaming'
+      SQL
+
+      ::Yabeda.configure do
+        group :wait_for_lsn do
+          gauge :replication_lag,
+                comment: "Replay lag reported by pg_stat_replication on the primary",
+                unit: :seconds,
+                tags: [:standby]
+
+          gauge :replication_lag_bytes,
+                comment: "WAL bytes the standby has yet to replay, from pg_stat_replication",
+                tags: [:standby]
+        end
+      end
+
+      class << self
+        # Queries pg_stat_replication on the primary before every export (each
+        # Prometheus scrape) and sets the replication lag gauges per standby.
+        def collect_replication_lag!
+          ::Yabeda.collect { record_replication_lag }
+        end
+
+        def record_replication_lag
+          return unless ::Yabeda.already_configured?
+
+          replication_lag_rows.each do |row|
+            tags = { standby: row["application_name"] }
+            # NULL means the standby is idle and fully caught up.
+            ::Yabeda.wait_for_lsn.replication_lag.set(tags, row["replay_lag_seconds"].to_f)
+            ::Yabeda.wait_for_lsn.replication_lag_bytes.set(tags, row["replay_lag_bytes"].to_i)
+          end
+        end
+
+        private
+
+        def replication_lag_rows
+          ActiveRecord::Base.connected_to(role: ActiveRecord.writing_role, prevent_writes: true) do
+            ActiveRecord::Base.connection_pool.with_connection do |conn|
+              conn.select_all(REPLICATION_LAG_SQL).to_a
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_record/wait_for_lsn.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "active_record"
+require "zeitwerk"
+
+require_relative "wait_for_lsn/version"
+
+loader = Zeitwerk::Loader.for_gem_extension(ActiveRecord)
+loader.inflector.inflect("wait_for_lsn" => "WaitForLSN")
+loader.ignore("#{__dir__}/wait_for_lsn/version.rb")
+loader.ignore("#{__dir__}/wait_for_lsn/yabeda.rb") # opt-in, required explicitly
+loader.setup
+
+module ActiveRecord
+  # Read-your-writes for Rails replicas via PostgreSQL 19 +WAIT FOR LSN+.
+  #
+  #   config.active_record.database_selector = { wait_timeout: "50ms" }
+  #   config.active_record.database_resolver = ActiveRecord::WaitForLSN::Resolver
+  #   config.active_record.database_resolver_context = ActiveRecord::WaitForLSN::Session
+  module WaitForLSN
+  end
+end
+
+# Rails classifies SQL on replica connections by its first keyword and treats
+# anything unknown as a write. Teach the PostgreSQL adapter that WAIT FOR is read-only.
+ActiveSupport.on_load(:active_record_postgresqladapter) do
+  prepend ActiveRecord::WaitForLSN::ReadQueryPatch
+end

data/lib/activerecord-wait_for_lsn.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "active_record/wait_for_lsn"

metadata

@@ -0,0 +1,83 @@
+--- !ruby/object:Gem::Specification
+name: activerecord-wait_for_lsn
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Aibek Izhanov
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+description: |-
+  A DatabaseSelector resolver that stores the primary WAL LSN after each write and runs
+  WAIT FOR LSN on the replica before reading, falling back to the primary on timeout.
+email:
+- aibek.izhanov@evilmartians.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/active_record/wait_for_lsn.rb
+- lib/active_record/wait_for_lsn/read_query_patch.rb
+- lib/active_record/wait_for_lsn/resolver.rb
+- lib/active_record/wait_for_lsn/session.rb
+- lib/active_record/wait_for_lsn/version.rb
+- lib/active_record/wait_for_lsn/yabeda.rb
+- lib/activerecord-wait_for_lsn.rb
+homepage: https://github.com/izhanov/activerecord-wait_for_lsn
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/izhanov/activerecord-wait_for_lsn
+  source_code_uri: https://github.com/izhanov/activerecord-wait_for_lsn
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Read-your-writes on Rails replicas using PostgreSQL 19 WAIT FOR LSN
+test_files: []