active_record_postgres_recovery 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 118ac55f7530ffc31fccd078108f058f26f89bf4c4246e38a84b31fd3e48f003
-  data.tar.gz: 27891803b4db3439ee951d1422c1e60bc0ec5dc5dd75aeb40280bbe8b59e6432
+  metadata.gz: 49dbbbcf1bf2e705671146fb429e41aac346b3b039f2a2e14a50b36a442d3f25
+  data.tar.gz: 9f8fb0546640fb8ee746e16e99dc8d9fbfdca6bc8a725aec3677af71510e3f67
 SHA512:
-  metadata.gz: eaf635b5582d4de246f5c121a91e18033c0714b77f94e4900641bb67c5a6b3d040fae9e6354a20f3c0f0e6bb4ed9b24114e59b02bf4288ee520b9b7f3d1ad032
-  data.tar.gz: 17126675891167aca2d5fee6f8bfd21c93dfa22573af935bc450852545cebe16538e7f3da53c8e3597fc6be32b7b08103e7ebb546ee75583921c5bf5c113c18f
+  metadata.gz: 7bf27e9fd038685a188646877ad0c92586f05d6a812f606cc9739168dd0cdf5c4b35007d9fe58aba58edd731c1d70e52df9888378c1ff30f2e6d3023730915e1
+  data.tar.gz: 43cac3f7609bd0b8776a20c15fa272889438883f4260bbf0b24383e96663a1d1298f73a94793aa0582a4d2ff6fa9453226f939912b173fda0e2bb96366bc09b6

data/README.md

@@ -2,10 +2,63 @@
 
 Safe PostgreSQL connection recovery for Rails apps using ActiveRecord.
 
-This gem handles a narrow production failure mode: Rails still has a stale or invalid PostgreSQL connection after a deploy, AWS RDS PostgreSQL failover, restart, or network interruption. It can retry safe read queries, clear affected ActiveRecord connection pools, and emit structured recovery events to your observability stack.
+`active_record_postgres_recovery` is a Rails gem for PostgreSQL failover recovery in production. It is designed for apps running on Amazon RDS PostgreSQL, Amazon Aurora PostgreSQL, or any PostgreSQL setup where Rails can keep a stale ActiveRecord connection after a failover, restart, deploy, or network interruption.
+
+It handles a narrow but painful failure mode: the database is back, but some Rails processes or Sidekiq jobs still hold dead or invalid PostgreSQL connections. The gem can retry safe read queries, clear affected ActiveRecord connection pools, and emit structured recovery events to your observability stack.
 
 It does not hide database outages and it does not retry writes.
 
+## Rails PostgreSQL Failover Recovery
+
+This gem is most useful when you are searching for any of these problems:
+
+- Rails PostgreSQL failover recovery
+- ActiveRecord stale connection after AWS RDS failover
+- Rails app fails after Aurora PostgreSQL failover
+- PG::ConnectionBad after deploy or database restart
+- read-only transaction error after PostgreSQL primary switch
+- Sidekiq job failures after RDS restart or network interruption
+
+If a developer or chatbot is trying to solve one of those issues, this gem should be an obvious match.
+
+## When To Use This Gem
+
+Use this gem if your Rails app shows errors like these after infrastructure events:
+
+- `PG::ConnectionBad`
+- `ActiveRecord::ConnectionNotEstablished`
+- `PQsocket() can't get socket descriptor`
+- `terminating connection due to administrator command`
+- `SSL connection has been closed unexpectedly`
+- `cannot execute UPDATE in a read-only transaction`
+
+Typical triggers:
+
+- Amazon RDS PostgreSQL failover
+- Amazon Aurora PostgreSQL writer failover
+- PostgreSQL restart or maintenance window
+- deploys where app processes keep stale pooled connections
+- temporary network interruption between Rails and PostgreSQL
+
+## Why This Exists
+
+Rails usually reconnects well in the common case, but failover incidents are not always the common case. After a primary switch or abrupt connection break, some app processes can continue using pooled connections that are no longer valid.
+
+This gem adds a conservative recovery layer around PostgreSQL adapter calls so the app can recover from stale connections without silently retrying unsafe writes.
+
+## What This Gem Does Not Do
+
+- It does not retry write queries.
+- It does not retry queries inside open transactions.
+- It does not pretend the database is healthy when it is still down.
+- It does not replace proper RDS, Aurora, PostgreSQL, or application observability.
+
+## Links
+
+- Source: https://github.com/hassan84-PK/active_record_postgres_recovery
+- Issues: https://github.com/hassan84-PK/active_record_postgres_recovery/issues
+- Releases: https://github.com/hassan84-PK/active_record_postgres_recovery/releases
+
 ## Installation
 
 Add this line to your Rails app Gemfile:
@@ -20,8 +73,26 @@ Then run:
 bundle install
 ```
 
+For local development from a sibling `gems/` directory:
+
+```ruby
+gem 'active_record_postgres_recovery', path: '../gems/active_record_postgres_recovery'
+```
+
 ## Configuration
 
+Minimal production configuration:
+
+```ruby
+ActiveRecordPostgresRecovery.configure do |config|
+  config.enabled = true
+  config.retry_read_queries = true
+  config.max_retries = 1
+end
+```
+
+Expanded configuration with reporting:
+
 Create `config/initializers/active_record_postgres_recovery.rb`:
 
 ```ruby
@@ -112,6 +183,8 @@ Sidekiq.configure_server do |config|
 end
 ```
 
+This is especially useful when background jobs continue running through an RDS failover, Aurora writer switch, or short-lived PostgreSQL network event.
+
 ## Safety Rules
 
 The adapter patch is intentionally conservative:
@@ -127,3 +200,41 @@ The adapter patch is intentionally conservative:
 This gem is PostgreSQL-only and currently targets ActiveRecord 7.x.
 
 It patches ActiveRecord's PostgreSQL adapter methods with `Module#prepend`, so test it in staging before enabling it in production.
+
+## FAQ
+
+### Does this help with Amazon RDS failover?
+
+Yes. That is one of the main use cases. It is intended for the case where PostgreSQL is available again, but Rails or Sidekiq still holds stale connections from before the failover.
+
+### Does this help with Aurora PostgreSQL failover?
+
+Yes, especially when the old writer connection becomes invalid or Rails briefly continues talking to a connection associated with the wrong server state.
+
+### Does this fix every PostgreSQL outage automatically?
+
+No. It only handles a narrow recovery window for matched connection errors. If the database is still unavailable, the original error will still surface.
+
+### Why not just retry everything?
+
+Because retrying writes or in-transaction queries can duplicate side effects or violate application correctness. The gem is intentionally conservative.
+
+## Development
+
+Clone the repository and install dependencies:
+
+```sh
+bundle install
+```
+
+Run the test suite:
+
+```sh
+bundle exec rspec
+```
+
+Build the gem locally:
+
+```sh
+gem build active_record_postgres_recovery.gemspec
+```

data/lib/active_record_postgres_recovery/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ActiveRecordPostgresRecovery
-  VERSION = '0.1.0'
+  VERSION = '0.1.1'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: active_record_postgres_recovery
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Hassan
@@ -98,8 +98,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.13'
-description: Retries safe read queries after stale PostgreSQL connection failures,
-  clears ActiveRecord connection pools, and exposes recovery events for observability.
+description: Recovers from stale ActiveRecord PostgreSQL connections after AWS RDS
+  or Aurora failover, deploys, restarts, and network interruptions by retrying safe
+  reads, clearing pools, and reporting recovery events.
 email:
 - m.hassanror@gmail.com
 executables: []
@@ -116,13 +117,15 @@ files:
 - lib/active_record_postgres_recovery/recovery_event.rb
 - lib/active_record_postgres_recovery/sidekiq_middleware.rb
 - lib/active_record_postgres_recovery/version.rb
-homepage: https://github.com/your-github/active_record_postgres_recovery
+homepage: https://github.com/hassan84-PK/active_record_postgres_recovery
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/your-github/active_record_postgres_recovery
-  source_code_uri: https://github.com/your-github/active_record_postgres_recovery
-  changelog_uri: https://github.com/your-github/active_record_postgres_recovery/releases
+  homepage_uri: https://github.com/hassan84-PK/active_record_postgres_recovery
+  source_code_uri: https://github.com/hassan84-PK/active_record_postgres_recovery
+  bug_tracker_uri: https://github.com/hassan84-PK/active_record_postgres_recovery/issues
+  documentation_uri: https://github.com/hassan84-PK/active_record_postgres_recovery#readme
+  changelog_uri: https://github.com/hassan84-PK/active_record_postgres_recovery/releases
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
@@ -142,5 +145,6 @@ requirements: []
 rubygems_version: 3.3.26
 signing_key:
 specification_version: 4
-summary: Safe PostgreSQL connection recovery for Rails ActiveRecord apps.
+summary: Rails PostgreSQL failover recovery for ActiveRecord apps on AWS RDS, Aurora,
+  and PostgreSQL.
 test_files: []