pgtk 0.17.4 → 0.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7c88391a71242e30946bd4c1cb06879c4cf83ce1a4ba00e0511c1784e8713e5a
-  data.tar.gz: '08e01c0c7bca206247159c4d672c274c30aa79be9db4c1605d9c8dd395e14bf4'
+  metadata.gz: e3c09e42b393c24a720d0ca3c63da7d4618cfa430fd40122a516525ef64e0e9c
+  data.tar.gz: 0bf318a887749f9edf00e78a5b229321d77804a36e1afb4a248e8952c757e5b3
 SHA512:
-  metadata.gz: b27a880f60936cfbbdf99c32ab463380a31724b619aa9bd7564b6fe9286075d04759d4fda4203778a84ee2492b15ff5dffea84a2b482d117a4d40edad72f0141
-  data.tar.gz: 770f922faf767f2af485a8433ca29aa8e5c227ed9aca25323eeabf6b718ed77bf6255047c12bb588d8ff31a21f56f8676affb23742069c732dc9803a639177b6
+  metadata.gz: c4ff1a0b73c3d8c7a7f9d917b08284e534f38cd09034b8bb8a031c6ad3412546faf10cbb79a5e66f1f991098bf221642303949fa08d5490e584ed0064b76f70c
+  data.tar.gz: 7632624121254f3c0c8a428c3a0187ec112c813f7ac7fadd1a271ecc11db65b92afe8c27cfe45dadb9aa42893849129dd7e0f0d56783c9ac91640face5b1ec97

data/README.md

@@ -173,6 +173,42 @@ pool = Pgtk::Spy.new(pool) do |sql|
 end
 ```
 
+## Query Timeouts with `Pgtk::Impatient`
+
+To prevent queries from running indefinitely, use `Pgtk::Impatient` to enforce
+timeouts on database operations:
+
+```ruby
+require 'pgtk/impatient'
+# Wrap the pool with a 5-second timeout for all queries
+impatient = Pgtk::Impatient.new(pool, 5)
+```
+
+The impatient decorator ensures queries don't hang your application:
+
+```ruby
+begin
+  # This query will be terminated if it takes longer than 5 seconds
+  impatient.exec('SELECT * FROM large_table WHERE complex_condition')
+rescue Pgtk::Impatient::TooSlow => e
+  puts "Query timed out: #{e.message}"
+end
+```
+
+You can exclude specific queries from timeout enforcement using regex patterns:
+
+```ruby
+# Don't timeout any SELECT queries or specific maintenance operations
+impatient = Pgtk::Impatient.new(pool, 2, /^SELECT/, /^VACUUM/)
+```
+
+Key features:
+
+1. Configurable timeout in seconds for each query
+2. Raises `Pgtk::Impatient::TooSlow` exception when timeout is exceeded
+3. Can exclude queries matching specific patterns from timeout checks
+4. Also sets PostgreSQL's `statement_timeout` for transactions
+
 ## Query Caching with `Pgtk::Stash`
 
 For applications with frequent read queries,
@@ -205,6 +241,37 @@ for simple queries:
 3. Write operations (`INSERT`, `UPDATE`, `DELETE`) bypass
 the cache and invalidate all cached queries for affected tables
 
+## Automatic Retries with `Pgtk::Retry`
+
+For resilient database operations, `Pgtk::Retry` provides automatic retry
+functionality for failed `SELECT` queries:
+
+```ruby
+require 'pgtk/retry'
+# Wrap the pool with retry functionality (default: 3 attempts)
+retry_pool = Pgtk::Retry.new(pgsql)
+# Or specify custom number of attempts
+retry_pool = Pgtk::Retry.new(pgsql, attempts: 5)
+```
+
+The retry decorator automatically retries `SELECT` queries that fail due to
+transient errors (network issues, connection problems, etc.):
+
+```ruby
+# This SELECT will be retried up to 3 times if it fails
+users = retry_pool.exec('SELECT * FROM users WHERE active = true')
+
+# Non-SELECT queries are NOT retried to prevent duplicate writes
+retry_pool.exec('INSERT INTO logs (message) VALUES ($1)', ['User logged in'])
+```
+
+Key features:
+
+1. Only `SELECT` queries are retried (to prevent duplicate data modifications)
+2. Retries happen immediately without delay
+3. The original error is raised after all retry attempts are exhausted
+4. Works seamlessly with other decorators like `Pgtk::Spy` and `Pgtk::Impatient`
+
 ## Some Examples
 
 This library works in

data/lib/pgtk/retry.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright (c) 2019-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+require_relative '../pgtk'
+
+# Retry is a decorator for Pool that automatically retries failed SELECT queries.
+# It provides fault tolerance for transient database errors by retrying read-only
+# operations a configurable number of times before giving up.
+#
+# This class implements the same interface as Pool but adds retry logic specifically
+# for SELECT queries. Non-SELECT queries are executed without retry to maintain
+# data integrity and avoid unintended side effects from duplicate writes.
+#
+# Basic usage:
+#
+#   # Create and configure a regular pool
+#   pool = Pgtk::Pool.new(wire).start(4)
+#
+#   # Wrap the pool in a retry decorator with 3 attempts
+#   retry_pool = Pgtk::Retry.new(pool, attempts: 3)
+#
+#   # SELECT queries are automatically retried on failure
+#   begin
+#     retry_pool.exec('SELECT * FROM users WHERE id = $1', [42])
+#   rescue PG::Error => e
+#     puts "Query failed after 3 attempts: #{e.message}"
+#   end
+#
+#   # Non-SELECT queries are not retried
+#   retry_pool.exec('UPDATE users SET active = true WHERE id = $1', [42])
+#
+#   # Transactions pass through without retry logic
+#   retry_pool.transaction do |t|
+#     t.exec('SELECT * FROM accounts')  # No retry within transaction
+#     t.exec('UPDATE accounts SET balance = balance + 100')
+#   end
+#
+#   # Combining with other decorators
+#   impatient = Pgtk::Impatient.new(retry_pool, 5)
+#   spy = Pgtk::Spy.new(impatient) do |sql, duration|
+#     puts "Query: #{sql} (#{duration}s)"
+#   end
+#
+# Author:: Yegor Bugayenko (yegor256@gmail.com)
+# Copyright:: Copyright (c) 2019-2025 Yegor Bugayenko
+# License:: MIT
+class Pgtk::Retry
+  # Constructor.
+  #
+  # @param [Pgtk::Pool] pool The pool to decorate
+  # @param [Integer] attempts Number of attempts to make (default: 3)
+  def initialize(pool, attempts: 3)
+    @pool = pool
+    @attempts = attempts
+  end
+
+  # Get the version of PostgreSQL server.
+  #
+  # @return [String] Version of PostgreSQL server
+  def version
+    @pool.version
+  end
+
+  # Execute a SQL query with automatic retry for SELECT queries.
+  #
+  # @param [String] sql The SQL query with params inside (possibly)
+  # @param [Array] args List of arguments
+  # @return [Array] Result rows
+  def exec(sql, *args)
+    query = sql.is_a?(Array) ? sql.join(' ') : sql
+    if query.strip.upcase.start_with?('SELECT')
+      attempt = 0
+      begin
+        @pool.exec(sql, *args)
+      rescue StandardError => e
+        attempt += 1
+        raise e if attempt >= @attempts
+        retry
+      end
+    else
+      @pool.exec(sql, *args)
+    end
+  end
+
+  # Run a transaction without retry logic.
+  #
+  # @yield [Object] Yields the transaction object
+  # @return [Object] Result of the block
+  def transaction(&block)
+    @pool.transaction(&block)
+  end
+end

data/lib/pgtk/version.rb

@@ -11,5 +11,5 @@ require_relative '../pgtk'
 # License:: MIT
 module Pgtk
   # Current version of the library.
-  VERSION = '0.17.4'
+  VERSION = '0.18.0'
 end

data/test/test_retry.rb

@@ -0,0 +1,232 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright (c) 2019-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+require 'loog'
+require 'pg'
+require 'qbash'
+require 'rake'
+require 'tmpdir'
+require 'yaml'
+require_relative 'test__helper'
+require_relative '../lib/pgtk/pool'
+require_relative '../lib/pgtk/retry'
+
+# Retry test.
+# Author:: Yegor Bugayenko (yegor256@gmail.com)
+# Copyright:: Copyright (c) 2017-2025 Yegor Bugayenko
+# License:: MIT
+class TestRetry < Pgtk::Test
+  def test_takes_version
+    fake_pool do |pool|
+      v = Pgtk::Retry.new(pool).version
+      refute_nil(v)
+    end
+  end
+
+  def test_executes_select_without_error
+    fake_pool do |pool|
+      retry_pool = Pgtk::Retry.new(pool, attempts: 3)
+      result = retry_pool.exec('SELECT 1 as value')
+      assert_equal('1', result.first['value'])
+    end
+  end
+
+  def test_retries_select_on_failure
+    fake_pool do |pool|
+      counter = 0
+      stub_pool = Object.new
+      def stub_pool.version
+        'stub'
+      end
+      stub_pool.define_singleton_method(:exec) do |sql, *args|
+        counter += 1
+        raise PG::Error, 'Connection lost' if counter < 3
+        pool.exec(sql, *args)
+      end
+      retry_pool = Pgtk::Retry.new(stub_pool, attempts: 3)
+      result = retry_pool.exec('SELECT 2 as num')
+      assert_equal('2', result.first['num'])
+      assert_equal(3, counter)
+    end
+  end
+
+  def test_fails_after_max_attempts
+    fake_pool do |_pool|
+      stub_pool = Object.new
+      def stub_pool.version
+        'stub'
+      end
+      stub_pool.define_singleton_method(:exec) do |_sql, *_args|
+        raise PG::Error, 'Persistent failure'
+      end
+      retry_pool = Pgtk::Retry.new(stub_pool, attempts: 2)
+      assert_raises(PG::Error) do
+        retry_pool.exec('SELECT * FROM users')
+      end
+    end
+  end
+
+  def test_does_not_retry_insert
+    fake_pool do |_pool|
+      counter = 0
+      stub_pool = Object.new
+      def stub_pool.version
+        'stub'
+      end
+      stub_pool.define_singleton_method(:exec) do |_sql, *_args|
+        counter += 1
+        raise PG::Error, 'Insert failed'
+      end
+      retry_pool = Pgtk::Retry.new(stub_pool, attempts: 3)
+      assert_raises(PG::Error) do
+        retry_pool.exec('INSERT INTO book (title) VALUES ($1)', ['Test Book'])
+      end
+      assert_equal(1, counter)
+    end
+  end
+
+  def test_does_not_retry_update
+    fake_pool do |_pool|
+      counter = 0
+      stub_pool = Object.new
+      def stub_pool.version
+        'stub'
+      end
+      stub_pool.define_singleton_method(:exec) do |_sql, *_args|
+        counter += 1
+        raise PG::Error, 'Update failed'
+      end
+      retry_pool = Pgtk::Retry.new(stub_pool, attempts: 3)
+      assert_raises(PG::Error) do
+        retry_pool.exec('UPDATE book SET title = $1 WHERE id = $2', ['New Title', 1])
+      end
+      assert_equal(1, counter)
+    end
+  end
+
+  def test_does_not_retry_delete
+    fake_pool do |_pool|
+      counter = 0
+      stub_pool = Object.new
+      def stub_pool.version
+        'stub'
+      end
+      stub_pool.define_singleton_method(:exec) do |_sql, *_args|
+        counter += 1
+        raise PG::Error, 'Delete failed'
+      end
+      retry_pool = Pgtk::Retry.new(stub_pool, attempts: 3)
+      assert_raises(PG::Error) do
+        retry_pool.exec('DELETE FROM book WHERE id = $1', [1])
+      end
+      assert_equal(1, counter)
+    end
+  end
+
+  def test_handles_select_with_leading_whitespace
+    fake_pool do |pool|
+      counter = 0
+      stub_pool = Object.new
+      def stub_pool.version
+        'stub'
+      end
+      stub_pool.define_singleton_method(:exec) do |sql, *args|
+        counter += 1
+        raise PG::Error, 'Connection lost' if counter < 2
+        pool.exec(sql, *args)
+      end
+      retry_pool = Pgtk::Retry.new(stub_pool, attempts: 3)
+      result = retry_pool.exec('  SELECT 3 as value')
+      assert_equal('3', result.first['value'])
+      assert_equal(2, counter)
+    end
+  end
+
+  def test_handles_select_case_insensitive
+    fake_pool do |pool|
+      counter = 0
+      stub_pool = Object.new
+      def stub_pool.version
+        'stub'
+      end
+      stub_pool.define_singleton_method(:exec) do |sql, *args|
+        counter += 1
+        raise PG::Error, 'Connection lost' if counter < 2
+        pool.exec(sql, *args)
+      end
+      retry_pool = Pgtk::Retry.new(stub_pool, attempts: 3)
+      result = retry_pool.exec('select 4 as value')
+      assert_equal('4', result.first['value'])
+      assert_equal(2, counter)
+    end
+  end
+
+  def test_handles_array_sql
+    fake_pool do |pool|
+      counter = 0
+      stub_pool = Object.new
+      def stub_pool.version
+        'stub'
+      end
+      stub_pool.define_singleton_method(:exec) do |sql, *args|
+        counter += 1
+        raise PG::Error, 'Connection lost' if counter < 2
+        pool.exec(sql, *args)
+      end
+      retry_pool = Pgtk::Retry.new(stub_pool, attempts: 3)
+      result = retry_pool.exec(%w[SELECT 5 as value])
+      assert_equal('5', result.first['value'])
+      assert_equal(2, counter)
+    end
+  end
+
+  def test_transaction_passes_through
+    fake_pool do |pool|
+      retry_pool = Pgtk::Retry.new(pool)
+      retry_pool.transaction do |t|
+        id = t.exec(
+          'INSERT INTO book (title) VALUES ($1) RETURNING id',
+          ['Transaction Book']
+        ).first['id'].to_i
+        assert_predicate(id, :positive?)
+      end
+    end
+  end
+
+  def test_preserves_original_error_type
+    fake_pool do |_pool|
+      stub_pool = Object.new
+      def stub_pool.version
+        'stub'
+      end
+      stub_pool.define_singleton_method(:exec) do |_sql, *_args|
+        raise ArgumentError, 'Invalid argument'
+      end
+      retry_pool = Pgtk::Retry.new(stub_pool, attempts: 2)
+      assert_raises(ArgumentError) do
+        retry_pool.exec('SELECT * FROM table')
+      end
+    end
+  end
+
+  def test_retries_with_unicode_query
+    fake_pool do |pool|
+      counter = 0
+      stub_pool = Object.new
+      def stub_pool.version
+        'stub'
+      end
+      stub_pool.define_singleton_method(:exec) do |sql, *args|
+        counter += 1
+        raise PG::Error, 'Connection lost' if counter < 2
+        pool.exec(sql, *args)
+      end
+      retry_pool = Pgtk::Retry.new(stub_pool, attempts: 3)
+      result = retry_pool.exec('SELECT \'привет\' as greeting')
+      assert_equal('привет', result.first['greeting'])
+      assert_equal(2, counter)
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pgtk
 version: !ruby/object:Gem::Version
-  version: 0.17.4
+  version: 0.18.0
 platform: ruby
 authors:
 - Yegor Bugayenko
@@ -176,6 +176,7 @@ files:
 - lib/pgtk/liquibase_task.rb
 - lib/pgtk/pgsql_task.rb
 - lib/pgtk/pool.rb
+- lib/pgtk/retry.rb
 - lib/pgtk/spy.rb
 - lib/pgtk/stash.rb
 - lib/pgtk/version.rb
@@ -190,6 +191,7 @@ files:
 - test/test_liquibase_task.rb
 - test/test_pgsql_task.rb
 - test/test_pool.rb
+- test/test_retry.rb
 - test/test_stash.rb
 - test/test_wire.rb
 homepage: https://github.com/yegor256/pgtk