pgtk 0.31.10 → 0.32.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8199974c055231c0da5e834b017c72ba4e9b407edfb738ac86fbfd9f599ad4a9
-  data.tar.gz: af55c47ebb15d25ef602b586e1754bb0f4a5504e47153058badf1dee65c06bc2
+  metadata.gz: 2071a0941e2455164373e80f84f9cd536fd7bc82d216ded50b109c01e56e8b04
+  data.tar.gz: 9261c128b18ccb53a941fba5e880021571a40d973e8cd1294d3c9a7bd3ff9cab
 SHA512:
-  metadata.gz: ef8df2a5c1a960c78d8efbd3f2f786e9bcf2da56dc3b3a0db67505c5fd52641203a0a901d4e985c42c525551030081cff197e4a28765d81abcf7ca64f626b81a
-  data.tar.gz: 5193e34bf05c0a06483ecb2235a6b276c87c355197c5fc049bb30732f589cbb501817fb0ab73401cd95a297bf69941398bfe56812850cf73905e6d8f8d178ae7
+  metadata.gz: b17ff29e64a14aefdd0df18e6bb7c998d484cedffda0669adf15c6ff068c37591e34ee0769182f91718ab4f9e508bbdf34c577cd094c9c96d172fe338d270cf2
+  data.tar.gz: c93fc458236e81969a54fe57f4988b2f23a2f541a4c0d7fbf7849c51c0b98f67c7c5b659458de2b06da3ca47ccd0b713abc8f2f4102c43ac897456249e4e1693

data/README.md

@@ -118,6 +118,22 @@ pgsql = Pgtk::Pool.new(Pgtk::Wire::Yaml.new('config.yml'), max: 5)
 pgsql.start! # Start it with five simultaneous connections
 ```
 
+By default, the pool runs `SELECT 1` on a slot that has been idle for more
+than 60 seconds before yielding it to the caller, and renews the slot in-line
+if that probe fails.
+This guards against managed-PostgreSQL setups behind a TLS-terminating proxy,
+where a cold slot's SSL state can drift out of sync without libpq noticing —
+the next real query then fails with a `decryption failed or bad record mac`
+error.
+You can tune the threshold or disable validation entirely:
+
+```ruby
+# Validate slots idle for more than 30 seconds
+pgsql = Pgtk::Pool.new(wire, max: 5, idle: 30)
+# Disable validation (e.g. for local Unix-socket PostgreSQL)
+pgsql = Pgtk::Pool.new(wire, max: 5, idle: nil)
+```
+
 You can also let it pick the connection parameters from the environment
 variable `DATABASE_URL`, formatted like
 `postgres://user:password@host:5432/dbname`:
@@ -126,6 +142,31 @@ variable `DATABASE_URL`, formatted like
 pgsql = Pgtk::Pool.new(Pgtk::Wire::Env.new)
 ```
 
+Both `Pgtk::Wire::Direct` and `Pgtk::Wire::Env` accept extra keyword
+arguments and forward them to `PG.connect`, so any
+[libpq parameter](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-PARAMKEYWORDS)
+can be passed through (`sslmode`, `connect_timeout`, `keepalives`,
+`keepalives_idle`, `application_name`, and so on):
+
+```ruby
+Pgtk::Wire::Direct.new(
+  host: 'db.example.com', port: 5432, dbname: 'app',
+  user: 'u', password: 'p',
+  sslmode: 'require', connect_timeout: 5, keepalives: 1
+)
+Pgtk::Wire::Env.new('DATABASE_URL', sslmode: 'require', keepalives: 1)
+```
+
+`Pgtk::Wire::Env` also honors the URL query string, so options can be
+configured from the environment alone:
+
+```text
+DATABASE_URL=postgres://u:p@h:5432/d?sslmode=require&keepalives=1&keepalives_idle=30
+```
+
+Explicit keyword arguments win over options carried in the URL query string
+on conflict.
+
 Now you can fetch some data from the DB:
 
 ```ruby

data/lib/pgtk/pool.rb

@@ -57,13 +57,25 @@ class Pgtk::Pool
 
   # Constructor.
   #
+  # The +idle+ option guards against the cold-slot SSL desync that bites
+  # managed PostgreSQL behind a TLS proxy: a slot sits idle long enough for
+  # the proxy and the client to disagree about SSL state, libpq still reports
+  # +CONNECTION_OK+, and the next real query blows up with a decryption error.
+  # When a slot has been idle longer than +idle+ seconds, the pool runs
+  # +SELECT 1+ on it before yielding; if that fails, the slot is renewed
+  # in-line and the caller never sees the error. Set to +nil+ to skip
+  # validation entirely (e.g. for local Unix-socket PostgreSQL).
+  #
   # @param [Pgtk::Wire] wire The wire
   # @param [Integer] max Total amount of PostgreSQL connections in the pool
   # @param [Numeric] timeout Max seconds to wait for a free connection
+  # @param [Numeric, nil] idle Seconds of idleness after which to validate
+  #   a connection on checkout, or +nil+ to disable validation
   # @param [Object] log The log
-  def initialize(wire, max: 8, timeout: 1, log: Loog::NULL)
+  def initialize(wire, max: 8, timeout: 1, idle: 60, log: Loog::NULL)
     @wire = wire
     @max = max
+    @idle = idle
     @log = log
     @pool = IterableQueue.new(max, timeout)
     @started = false
@@ -324,7 +336,7 @@ class Pgtk::Pool
   def connect
     conn = @pool.pop
     begin
-      reason = cause(conn)
+      reason = cause(conn) || stale(conn)
       if reason
         begin
           conn = renew(conn, reason)
@@ -344,6 +356,7 @@ class Pgtk::Pool
         raise(e)
       end
     ensure
+      conn.instance_variable_set(:@pgtk_last_used, Time.now) if @idle && !conn.finished?
       @pool.push(conn)
     end
   end
@@ -357,6 +370,18 @@ class Pgtk::Pool
     "inspection failed: #{e.message.strip}"
   end
 
+  def stale(conn)
+    return nil if @idle.nil?
+    last = conn.instance_variable_get(:@pgtk_last_used)
+    return nil if last.nil? || Time.now - last < @idle
+    begin
+      conn.exec('SELECT 1')
+      nil
+    rescue StandardError => e
+      "validation failed after #{last.ago} idle: #{e.message.strip}"
+    end
+  end
+
   def info(conn)
     pipelines = { PG::Constants::PQ_PIPELINE_ON => 'ON', PG::Constants::PQ_PIPELINE_OFF => 'OFF',
                   PG::Constants::PQ_PIPELINE_ABORTED => 'ABORTED' }

data/lib/pgtk/version.rb

@@ -10,5 +10,5 @@ require_relative '../pgtk'
 # Copyright:: Copyright (c) 2019-2026 Yegor Bugayenko
 # License:: MIT
 module Pgtk
-  VERSION = '0.31.10' unless defined?(VERSION)
+  VERSION = '0.32.0' unless defined?(VERSION)
 end

data/lib/pgtk/wire.rb

@@ -3,6 +3,7 @@
 # SPDX-FileCopyrightText: Copyright (c) 2019-2026 Yegor Bugayenko
 # SPDX-License-Identifier: MIT
 
+require 'cgi'
 require 'pg'
 require 'uri'
 require 'yaml'
@@ -25,7 +26,9 @@ module Pgtk::Wire
     # @param [String] dbname Database name
     # @param [String] user Username
     # @param [String] password Password
-    def initialize(host:, port:, dbname:, user:, password:)
+    # @param [Hash] opts Extra options forwarded to +PG.connect+ (e.g. +sslmode+,
+    #   +connect_timeout+, +keepalives+, +keepalives_idle+, +application_name+)
+    def initialize(host:, port:, dbname:, user:, password:, **opts)
       raise(ArgumentError, "The host can't be nil") if host.nil?
       @host = host
       raise(ArgumentError, "The port can't be nil") if port.nil?
@@ -33,11 +36,12 @@ module Pgtk::Wire
       @dbname = dbname
       @user = user
       @password = password
+      @opts = opts
     end
 
     # Create a new connection to PostgreSQL server.
     def connection
-      PG.connect(dbname: @dbname, host: @host, port: @port, user: @user, password: @password)
+      PG.connect(dbname: @dbname, host: @host, port: @port, user: @user, password: @password, **@opts)
     end
   end
 
@@ -54,21 +58,27 @@ module Pgtk::Wire
     # Constructor.
     #
     # @param [String] var The name of the environment variable with the connection URL
-    def initialize(var = 'DATABASE_URL')
+    # @param [Hash] opts Extra options forwarded to +PG.connect+ (e.g. +sslmode+,
+    #   +connect_timeout+, +keepalives+, +keepalives_idle+, +application_name+).
+    #   Explicit kwargs win over options carried in the URL query string on conflict.
+    def initialize(var = 'DATABASE_URL', **opts)
       raise(ArgumentError, "The name of the environment variable can't be nil") if var.nil?
       @value = ENV.fetch(var, nil)
       raise(ArgumentError, "The environment variable #{@value.inspect} is not set") if @value.nil?
+      @opts = opts
     end
 
     # Create a new connection to PostgreSQL server.
     def connection
       uri = URI(@value)
+      extras = uri.query ? URI.decode_www_form(uri.query).to_h.transform_keys(&:to_sym) : {}
       Pgtk::Wire::Direct.new(
         host: CGI.unescape(uri.host),
         port: uri.port || 5432,
         dbname: CGI.unescape(uri.path[1..]),
         user: CGI.unescape(uri.userinfo.split(':')[0]),
-        password: CGI.unescape(uri.userinfo.split(':')[1])
+        password: CGI.unescape(uri.userinfo.split(':')[1]),
+        **extras.merge(@opts)
       ).connection
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pgtk
 version: !ruby/object:Gem::Version
-  version: 0.31.10
+  version: 0.32.0
 platform: ruby
 authors:
 - Yegor Bugayenko