sequel-pg_reaper 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c7913ddd64a29c3656aae7b2dc5bf9dd24d98155d95188a39c56eee9bfbfc595
+  data.tar.gz: 0f796c4ac4f0350a9905b20be4b812ca6832129e9241af6a1d0c8f3c17c91a6d
+SHA512:
+  metadata.gz: d1a5880580d6ce8d9cfc95bfd043659c8ce2bf9ef9a20f961bb3eb7b1792052a508c9d5814f2ac2b6c4db95a75f4178e413653feb439fb37f75cda04ffe1b6aa
+  data.tar.gz: 296f67f6788c2700be3c879c0327ede358268aac94a754fd8ffc3b40a6fbc7b37d40794870df20e63baf20e9f5441831b5a6cfc1a99ea49a762dfafa46634d17

data/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 1.0.0 (2026-10-14)
+
+
+### Features
+
+* add pg_reaper extension to recycle aged Sequel connections ([9003e07](https://github.com/rubyists/sequel-pg_reaper/commit/9003e0769e3d00a28cb9f71385ef298425d69629))
+
+
+### Bug Fixes
+
+* complete the example documentation for real world usage ([#1](https://github.com/rubyists/sequel-pg_reaper/issues/1)) ([c77e39c](https://github.com/rubyists/sequel-pg_reaper/commit/c77e39c7993208aeb431bfba074795e56bfe46d1))

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Tj (bougyman) Vanderpoel
+
+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.adoc

@@ -0,0 +1,94 @@
+= sequel-pg_reaper
+Tj Vanderpoel (bougyman) <bougyman@users.noreply.github.com>
+:toc: right
+:toclevels: 3
+:sectanchors:
+:icons: font
+:tip-caption: 💡
+:note-caption: 📝
+:experimental:
+:docinfo: private
+:docinfodir: {docdir}
+ifdef::env-github[]
+:tip-caption: :bulb:
+:note-caption: :information_source:
+:important-caption: :heavy_exclamation_mark:
+:caution-caption: :fire:
+:warning-caption: :warning:
+endif::[]
+:conventional-commits: https://www.conventionalcommits.org/en/v1.0.0/[Conventional Commits]
+
+A https://sequel.jeremyevans.net/[Sequel] extension that retires pooled connections once they pass a maximum age.
+
+See link:documents/motivation.adoc[the motivation] for why it exists.
+
+== Usage
+
+[source,ruby]
+----
+DB = Sequel.connect(url, connection_max_lifetime: 90)
+DB.extension :pg_reaper
+----
+
+* `connection_max_lifetime` is in seconds and defaults to 120
+* The age is checked as a connection is checked out of the pool, so the cost is one hash lookup
+* A connection that is too old is disconnected and replaced before your code sees it
+* A connection already checked out, such as inside a transaction, is never reaped
+* Idle connections are not closed in the background, see <<Idle connections>>
+* Single and sharded single pools are not supported
+
+The lifetime can also be changed at runtime with `DB.pool.connection_max_lifetime = 60`.
+
+== Idle connections
+
+Nothing in this extension, or in Sequel's `connection_validator`, closes an idle socket in the background.
+Both act when a connection is checked out:
+
+* `pg_reaper` replaces any connection older than `connection_max_lifetime`, however long it sat idle
+* `connection_validator` runs a query on connections idle longer than `connection_validation_timeout`
+  and replaces the ones that fail
+
+For a pgdog rollout `pg_reaper` is enough, if two conditions hold that this extension does not enforce:
+
+* The pod's shutdown grace is longer than `connection_max_lifetime`, as with pgdog's 180s against the default 120s
+* New connections stop reaching a pod once it is terminating
+
+Connection age does not tell you a connection is alive. If the grace is shorter than the lifetime, a connection
+opened just before SIGTERM is still young when the pod dies, and it is handed out dead.
+
+Load `connection_validator` as well to cover connections that die for other reasons, such as a pgdog crash
+or a network failure:
+
+[source,ruby]
+----
+DB = Sequel.connect(url, connection_max_lifetime: 120)
+DB.extension :connection_validator, :pg_reaper
+DB.pool.connection_validation_timeout = 30
+----
+
+* `connection_validation_timeout` is an idle threshold, not a detection deadline, so the 30 above is not a promise
+  that a dead connection is found within 30s
+* Only a connection idle longer than the threshold is validated at checkout, and an unused dead connection is not
+  found until something checks it out
+* Set it to `-1` to validate on every checkout, which costs a query each time
+* Load order does not matter
+
+[WARNING]
+----
+A connection checked out for longer than the time left before the pod terminates is not interrupted, keep transactions short
+----
+
+== Development
+
+[source,sh]
+----
+mise install
+bundle exec rake
+----
+
+Tests use `Sequel.mock`, so no database is needed.
+
+Commits and PR titles must follow {conventional-commits} to be included in the changelog and release notes.
+The hooks in `.githooks` enforce it, and `mise run setup` enables them.
+
+Releases are cut by https://github.com/googleapis/release-please[release-please] and published to rubygems.org.

data/documents/motivation.adoc

@@ -0,0 +1,13 @@
+= Motivation
+
+To make pgdog rollouts smooth.
+
+Pgdog's shutdown timer is 180s. If the clients all disconnect and reconnect themselves within 120s,
+they are drained from pgdog before the pod terminates, and have already been routed to a fresher pgdog.
+
+Persistent connections also keep load from ever balancing across all the dogs. Recycling connections
+now and then lets the load eventually balance.
+
+== Problem
+
+When pgdog pods cycle in Kubernetes, Sequel can get bad disconnects in the middle of transactions.

data/lib/sequel/extensions/pg_reaper.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative '../pg_reaper'
+
+# The pg_reaper extension retires pooled connections older than the Database's
+# :connection_max_lifetime option (default 120s) as they are checked out.
+Sequel::Database.register_extension(:pg_reaper) do |db|
+  pool = db.pool.extend(Rubyists::Sequel::PgReaper::PoolMethods)
+  lifetime = db.opts[:connection_max_lifetime]
+  pool.connection_max_lifetime = lifetime if lifetime
+end

data/lib/sequel/pg_reaper/version.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Rubyists
+  module Sequel
+    module PgReaper
+      # x-release-please-start-version
+      VERSION = '1.0.0'
+      # x-release-please-end
+    end
+  end
+end

data/lib/sequel/pg_reaper.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require 'sequel'
+require_relative 'pg_reaper/version'
+
+module Rubyists
+  module Sequel
+    # Retires pooled connections once they pass a maximum age, so clients move
+    # to fresher pgdog pods before the old ones terminate
+    module PgReaper
+      DEFAULT_MAX_LIFETIME = 120
+
+      # Extended onto the Database's connection pool
+      module PoolMethods
+        attr_reader :connection_max_lifetime
+
+        def self.extended(pool)
+          case pool.pool_type
+          when :single, :sharded_single
+            raise ::Sequel::Error, 'cannot load pg_reaper extension if using single or sharded_single connection pool'
+          end
+
+          pool.instance_exec do
+            sync do
+              @connection_timers ||= {}.compare_by_identity
+              @connection_max_lifetime ||= DEFAULT_MAX_LIFETIME
+            end
+          end
+        end
+
+        # Maximum connection age in seconds, checked as a connection is checked out
+        def connection_max_lifetime=(seconds)
+          unless seconds.is_a?(Numeric) && seconds.positive?
+            raise ArgumentError, 'connection_max_lifetime must be a positive number'
+          end
+
+          @connection_max_lifetime = seconds
+        end
+
+        private
+
+        def make_new(*)
+          conn = super
+          sync { @connection_timers[conn] = ::Sequel.start_timer }
+          conn
+        end
+
+        def disconnect_connection(conn)
+          sync { @connection_timers.delete(conn) }
+          super
+        end
+
+        # Connections opened before the extension loaded get their clock started on first checkout
+        def expired?(conn)
+          timer = sync { @connection_timers[conn] ||= ::Sequel.start_timer }
+          ::Sequel.elapsed_seconds_since(timer) > @connection_max_lifetime
+        end
+
+        def forget_allocation(server)
+          case pool_type
+          when :sharded_threaded, :sharded_timed_queue
+            sync { @allocated[server].delete(::Sequel.current) }
+          else
+            sync { @allocated.delete(::Sequel.current) }
+          end
+        end
+
+        # Mirrors Sequel's connection_validator: drop the allocation, disconnect, and ask for another connection
+        def acquire(*args)
+          loop do
+            conn = super
+            return conn unless conn && expired?(conn)
+
+            forget_allocation(args.last)
+            disconnect_acquired_connection(conn, *args)
+          end
+        end
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,68 @@
+--- !ruby/object:Gem::Specification
+name: sequel-pg_reaper
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- bougyman
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: sequel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+description: Retires pooled Sequel connections after a maximum lifetime, so clients
+  reach fresher pgdog pods.
+email:
+- bougyman@users.noreply.github.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- Readme.adoc
+- documents/motivation.adoc
+- lib/sequel/extensions/pg_reaper.rb
+- lib/sequel/pg_reaper.rb
+- lib/sequel/pg_reaper/version.rb
+homepage: https://github.com/rubyists/sequel-pg_reaper
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/rubyists/sequel-pg_reaper
+  source_code_uri: https://github.com/rubyists/sequel-pg_reaper
+  changelog_uri: https://github.com/rubyists/sequel-pg_reaper/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: Recycles Sequel connections by age so pgdog pods can drain cleanly during
+  rollouts.
+test_files: []