activerecord-wait_for_lsn 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cbd7e6e0f5eb7df644152b7ca91788239c5fbbc650ccd1fc6e17666cf70c0f85
-  data.tar.gz: f7d5f9438d176acf4b937a1786b570cd1253092ee8de6aacb7e392dabdf4e77f
+  metadata.gz: 4221e1d4c57f9b504e6fbd6b81e9cdf4e4a2af356d20f7c9d9d8a0135eb13379
+  data.tar.gz: 7f11cc5b8040fd5dc01564fc4ea56ffcbb0ecd4cc9cec86fa19803f9983bedd6
 SHA512:
-  metadata.gz: 706c03870f25a5f9ea1642d2825b5eacc1a83cc617460e201f47f4b200db63aa8ef218cf4e2611d57048f235cd4c67e7786bb4082fa63aea37e090c51f09fdf6
-  data.tar.gz: 56f9d278efbd92800270b8bc35e1c2034e56567276fe3033f4a763d2a2faa0e7bd265b3e500fbe2106fcd865d70213ab812a2201dbb4c07aa24f9e985a985617
+  metadata.gz: b8ba48eed7797370b91bb8bc780e80fc05ddbfa2eb0391168c351a2cb85cbc7ea8d31f659b11b68fd89577dfd3991dfbb8d0a43196eea5930f32f483b52df5fe
+  data.tar.gz: efb4f5e3ec5d155f7c4cb7df70252a944bc66cdb1d87cfbb253f8faf43157d5fbec192396b06ee8b069cc77085fe2690dcf305f7c51d73180c7bb00b21810fdc

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.2.0 - 2026-09-04
+
+- `max_age` option (default 10 seconds): reads stop waiting for the LSN once
+  the last write is older than this and the LSN is dropped from the session.
+  Before, a session ran `WAIT FOR LSN` on every read for the rest of its life.
+  `max_age: nil` restores that behaviour. `Session` now also records Rails'
+  `last_write` timestamp and gained `clear_last_write_lsn`.
+- Fix ActiveRecord 7.2: rescue `ConnectionNotEstablished` instead of
+  `ConnectionNotDefined`, which only exists since ActiveRecord 8.0. On 7.2 a
+  failed `WAIT FOR LSN` raised `NameError` instead of falling back to the primary.
+- Cast `pg_current_wal_lsn()` to text, silencing the adapter's
+  `unknown OID 3220` warning on every write.
+- Integration tests against a real PostgreSQL 19 primary and standby
+  (`rake test:integration`, cluster in `test/integration/compose.yml`).
+- Drop the `zeitwerk` dependency; the gem requires its four files directly.
+- GitHub Actions CI: rubocop, unit tests on Ruby 3.2–3.4 × ActiveRecord
+  7.2/8.0/8.1, integration tests per ActiveRecord version.
+
 ## 0.1.0 - 2026-09-04
 
 First release.

data/README.md

@@ -1,5 +1,7 @@
 # activerecord-wait_for_lsn
 
+[![CI](https://github.com/izhanov/activerecord-wait_for_lsn/actions/workflows/ci.yml/badge.svg)](https://github.com/izhanov/activerecord-wait_for_lsn/actions/workflows/ci.yml)
+
 Read-your-writes on Rails read replicas via PostgreSQL 19
 [`WAIT FOR LSN`](https://www.postgresql.org/docs/19/sql-wait-for.html).
 
@@ -34,6 +36,13 @@ Passed through the `database_selector` hash.
 |------------|--------------------|-------------|
 | `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. |
+| `max_age`      | `10`     | Seconds after a write during which reads wait for the LSN. Older writes are assumed replicated and the LSN is dropped from the session. `nil` waits forever. |
+
+`max_age` is what keeps a session from running `WAIT FOR LSN` on every read for
+the rest of its life: once the last write is older than `max_age` the resolver
+stops checking and reads straight from the replica. Pick a value above the
+replication lag you are prepared to tolerate; the lag gauges below show what
+your standbys actually do. Rails' own `delay` option is not used.
 
 ## Several replicas
 
@@ -147,6 +156,34 @@ wait_for_lsn_replication_lag_seconds
 max(wait_for_lsn_replication_lag_seconds) > 1
 ```
 
+## Development
+
+Unit tests need no database:
+
+```sh
+bundle exec rake test
+```
+
+Integration tests run the resolver and the `DatabaseSelector` middleware
+against a real PostgreSQL 19 primary and streaming standby. Start the cluster
+from the bundled compose file, then point the tests at it:
+
+```sh
+docker compose -f test/integration/compose.yml up -d --wait
+PRIMARY_URL=postgres://postgres:postgres@localhost:55432/wait_for_lsn_test \
+REPLICA_URL=postgres://postgres:postgres@localhost:55433/wait_for_lsn_test \
+bundle exec rake test:integration
+```
+
+Both connections must be superuser: the tests set `recovery_min_apply_delay`
+on the standby to simulate lag. CI runs the suite against ActiveRecord 7.2,
+8.0 and 8.1 via the gemfiles in `gemfiles/`:
+
+```sh
+BUNDLE_GEMFILE=gemfiles/activerecord_7.2.gemfile bundle install
+BUNDLE_GEMFILE=gemfiles/activerecord_7.2.gemfile bundle exec rake test
+```
+
 ## License
 
 MIT

data/Rakefile

@@ -3,10 +3,21 @@
 require "bundler/gem_tasks"
 require "minitest/test_task"
 
-Minitest::TestTask.create
+# Unit tests: no database needed.
+Minitest::TestTask.create(:test) do |t|
+  t.test_globs = ["test/active_record/**/*_test.rb"]
+end
 
-require "rubocop/rake_task"
+# Integration tests against a real primary + standby, see test/integration/compose.yml.
+Minitest::TestTask.create(:"test:integration") do |t|
+  t.test_globs = ["test/integration/**/*_test.rb"]
+end
 
-RuboCop::RakeTask.new
-
-task default: %i[test rubocop]
+# The CI gemfiles under gemfiles/ carry no rubocop.
+begin
+  require "rubocop/rake_task"
+  RuboCop::RakeTask.new
+  task default: %i[test rubocop]
+rescue LoadError
+  task default: :test
+end

data/lib/active_record/wait_for_lsn/resolver.rb

@@ -5,15 +5,17 @@ module ActiveRecord
     class Resolver < ::ActiveRecord::Middleware::DatabaseSelector::Resolver
       DEFAULT_LSN_TIMEOUT = "20ms"
       DEFAULT_LSN_NO_THROW = true
+      DEFAULT_LSN_MAX_AGE = 10 # seconds
       LSN_MODE = "standby_replay"
       LSN_OUTPUT_SUCCESS = "success"
 
-      attr_reader :wait_timeout, :no_throw
+      attr_reader :wait_timeout, :no_throw, :max_age
 
       def initialize(context, options = {})
         super
         @wait_timeout = options.fetch(:wait_timeout, DEFAULT_LSN_TIMEOUT)
         @no_throw = options.fetch(:no_throw, DEFAULT_LSN_NO_THROW)
+        @max_age = options.fetch(:max_age, DEFAULT_LSN_MAX_AGE)
       end
 
       def read(&blk)
@@ -47,17 +49,30 @@ module ActiveRecord
       end
 
       def read_from_primary?
-        lsn = context.last_write_lsn
-        return false unless lsn
-        return false if wait_for_lsn(lsn) == LSN_OUTPUT_SUCCESS
+        return false unless recent_write?
+        return false if wait_for_lsn(context.last_write_lsn) == LSN_OUTPUT_SUCCESS
 
         release_replica_connection
         true
-      rescue ActiveRecord::StatementInvalid, ActiveRecord::ConnectionNotDefined
+      rescue ActiveRecord::StatementInvalid, ActiveRecord::ConnectionNotEstablished
         release_replica_connection
         true
       end
 
+      def recent_write?
+        return false unless context.last_write_lsn
+        return true if within_max_age?
+
+        context.clear_last_write_lsn
+        false
+      end
+
+      def within_max_age?
+        return true if max_age.nil?
+
+        Time.now - context.last_write_timestamp <= max_age
+      end
+
       def wait_for_lsn(lsn)
         connected_to_replica do
           conn = ActiveRecord::Base.connection_pool.lease_connection
@@ -73,7 +88,7 @@ module ActiveRecord
         connected_to_replica do
           ActiveRecord::Base.connection_pool.release_connection
         end
-      rescue ActiveRecord::ConnectionNotDefined
+      rescue ActiveRecord::ConnectionNotEstablished
         nil
       end
 
@@ -83,13 +98,13 @@ module ActiveRecord
 
       def database_name
         ActiveRecord::Base.connection_pool.db_config.name
-      rescue ActiveRecord::ConnectionNotDefined
+      rescue ActiveRecord::ConnectionNotEstablished
         nil
       end
 
       def current_write_lsn
         ActiveRecord::Base.connection_pool.with_connection do |conn|
-          conn.select_value("SELECT pg_current_wal_lsn();")
+          conn.select_value("SELECT pg_current_wal_lsn()::text")
         end
       end
 

data/lib/active_record/wait_for_lsn/session.rb

@@ -9,6 +9,12 @@ module ActiveRecord
 
       def update_last_write_lsn(new_lsn)
         session[:last_write_lsn] = new_lsn
+        update_last_write_timestamp
+      end
+
+      def clear_last_write_lsn
+        session.delete(:last_write_lsn)
+        session.delete(:last_write)
       end
     end
   end

data/lib/active_record/wait_for_lsn/version.rb

@@ -2,6 +2,6 @@
 
 module ActiveRecord
   module WaitForLSN
-    VERSION = "0.1.0"
+    VERSION = "0.2.0"
   end
 end

data/lib/active_record/wait_for_lsn.rb

@@ -1,15 +1,12 @@
 # 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
+require_relative "wait_for_lsn/session"
+require_relative "wait_for_lsn/resolver"
+require_relative "wait_for_lsn/read_query_patch"
+# wait_for_lsn/yabeda is opt-in and required explicitly.
 
 module ActiveRecord
   # Read-your-writes for Rails replicas via PostgreSQL 19 +WAIT FOR LSN+.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: activerecord-wait_for_lsn
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Aibek Izhanov
@@ -23,20 +23,6 @@ dependencies:
     - - ">="
       - !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.