pgtk 0.14.0 → 0.16.0

data/lib/pgtk/stash.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright (c) 2019-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+require 'concurrent-ruby'
+require 'joined'
+require 'loog'
+require_relative '../pgtk'
+
+# Database query cache implementation.
+#
+# Provides a caching layer for PostgreSQL queries, automatically invalidating
+# the cache when tables are modified. Read queries are cached while write
+# queries bypass the cache and invalidate related cached entries.
+#
+# Thread-safe with read-write locking.
+#
+# The implementation is very naive! Use it at your own risk.
+#
+# Author:: Yegor Bugayenko (yegor256@gmail.com)
+# Copyright:: Copyright (c) 2019-2025 Yegor Bugayenko
+# License:: MIT
+class Pgtk::Stash
+  # Initialize a new Stash with query caching.
+  #
+  # @param [Object] pgsql PostgreSQL connection object
+  # @param [Hash] stash Optional existing stash to use (default: new empty stash)
+  # @param [Loog] loog Logger for debugging (default: null logger)
+  def initialize(pgsql, stash = {})
+    @pgsql = pgsql
+    @stash = stash
+    @stash[:queries] ||= {}
+    @stash[:tables] ||= {}
+    @entrance = Concurrent::ReentrantReadWriteLock.new
+  end
+
+  # Execute a SQL query with optional caching.
+  #
+  # Read queries are cached, while write queries bypass the cache and invalidate related entries.
+  #
+  # @param [String, Array<String>] query The SQL query to execute
+  # @param [Array] params Query parameters
+  # @return [PG::Result] Query result
+  def exec(query, params = [])
+    pure = (query.is_a?(Array) ? query.join(' ') : query).gsub(/\s+/, ' ').strip
+    if /(^|\s)(INSERT|DELETE|UPDATE|LOCK)\s/.match?(pure) || /(^|\s)pg_[a-z_]+\(/.match?(pure)
+      tables = pure.scan(/(?<=^|\s)(?:UPDATE|INSERT INTO|DELETE FROM|TRUNCATE)\s([a-z]+)(?=[^a-z]|$)/).map(&:first).uniq
+      ret = @pgsql.exec(pure, params)
+      @entrance.with_write_lock do
+        tables.each do |t|
+          @stash[:tables][t]&.each do |q|
+            @stash[:queries].delete(q)
+          end
+          @stash[:tables].delete(t)
+        end
+      end
+    else
+      key = params.map(&:to_s).join(' -*&%^- ')
+      @entrance.with_write_lock { @stash[:queries][pure] ||= {} }
+      ret = @stash[:queries][pure][key]
+      if ret.nil?
+        ret = @pgsql.exec(pure, params)
+        unless /(?<=^|\s)(NOW\(\)|COMMIT|ROLLBACK|START TRANSACTION|TRUNCATE|TO WARNING)(?=;|\s|$)/.match?(pure)
+          @entrance.with_write_lock do
+            @stash[:queries][pure] ||= {}
+            @stash[:queries][pure][key] = ret
+            tables = pure.scan(/(?<=^|\s)(?:FROM|JOIN) ([a-z_]+)(?=\s|$)/).map(&:first).uniq
+            tables.each do |t|
+              @stash[:tables][t] = [] if @stash[:tables][t].nil?
+              @stash[:tables][t].append(pure).uniq!
+            end
+            raise "No tables at #{pure.inspect}" if tables.empty?
+          end
+        end
+      end
+    end
+    ret
+  end
+
+  # Execute a database transaction.
+  #
+  # Yields a new Stash that shares the same cache but uses the transaction connection.
+  #
+  # @yield [Pgtk::Stash] A stash connected to the transaction
+  # @return [Object] The result of the block
+  def transaction
+    @pgsql.transaction do |t|
+      yield Pgtk::Stash.new(t, @stash)
+    end
+  end
+
+  # Start a new connection pool with the given arguments.
+  #
+  # @param args Arguments to pass to the underlying pool's start method
+  # @return [Pgtk::Stash] A new stash that shares the same cache
+  def start(*args)
+    Pgtk::Stash.new(@pgsql.start(*args), @stash)
+  end
+
+  # Get the PostgreSQL server version.
+  #
+  # @return [String] Version string of the database server
+  def version
+    @pgsql.version
+  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.14.0'
+  VERSION = '0.16.0'
 end

data/lib/pgtk/wire.rb

@@ -21,10 +21,16 @@ end
 # License:: MIT
 class Pgtk::Wire::Direct
   # Constructor.
+  #
+  # @param [String] host Host name of the PostgreSQL server
+  # @param [Integer] port Port number of the PostgreSQL server
+  # @param [String] dbname Database name
+  # @param [String] user Username
+  # @param [String] password Password
   def initialize(host:, port:, dbname:, user:, password:)
     raise "The host can't be nil" if host.nil?
     @host = host
-    raise "The host can't be nil" if host.nil?
+    raise "The port can't be nil" if port.nil?
     @port = port
     @dbname = dbname
     @user = user
@@ -41,13 +47,20 @@ class Pgtk::Wire::Direct
 end
 
 # Using ENV variable.
+#
+# The value of the variable should be in this format:
+#
+#   postgres://user:password@host:port/dbname
+#
 # Author:: Yegor Bugayenko (yegor256@gmail.com)
 # Copyright:: Copyright (c) 2019-2025 Yegor Bugayenko
 # License:: MIT
 class Pgtk::Wire::Env
   # Constructor.
+  #
+  # @param [String] var The name of the environment variable with the connection URL
   def initialize(var = 'DATABASE_URL')
-    raise "The name of the environmant variable can't be nil" if var.nil?
+    raise "The name of the environment variable can't be nil" if var.nil?
     @var = var
   end
 
@@ -72,6 +85,9 @@ end
 # License:: MIT
 class Pgtk::Wire::Yaml
   # Constructor.
+  #
+  # @param [String] file Path to the YAML configuration file
+  # @param [String] node The root node name in the YAML file containing PostgreSQL configuration
   def initialize(file, node = 'pgsql')
     raise "The name of the file can't be nil" if file.nil?
     @file = file
@@ -83,12 +99,13 @@ class Pgtk::Wire::Yaml
   def connection
     raise "The file #{@file.inspect} not found" unless File.exist?(@file)
     cfg = YAML.load_file(@file)
+    raise "The node '#{@node}' not found in YAML file #{@file.inspect}" unless cfg[@node]
     Pgtk::Wire::Direct.new(
-      host: cfg['pgsql']['host'],
-      port: cfg['pgsql']['port'],
-      dbname: cfg['pgsql']['dbname'],
-      user: cfg['pgsql']['user'],
-      password: cfg['pgsql']['password']
+      host: cfg[@node]['host'],
+      port: cfg[@node]['port'],
+      dbname: cfg[@node]['dbname'],
+      user: cfg[@node]['user'],
+      password: cfg[@node]['password']
     ).connection
   end
 end

data/pgtk.gemspec

@@ -27,6 +27,9 @@ Gem::Specification.new do |s|
   s.rdoc_options = ['--charset=UTF-8']
   s.extra_rdoc_files = ['README.md', 'LICENSE.txt']
   s.add_dependency 'backtrace', '>0'
+  s.add_dependency 'concurrent-ruby', '>0'
+  s.add_dependency 'joined', '>0'
+  s.add_dependency 'logger', '>0'
   s.add_dependency 'loog', '>0'
   s.add_dependency 'pg', '~>1.1'
   s.add_dependency 'qbash', '>0'

data/test/test__helper.rb

@@ -6,13 +6,71 @@
 $stdout.sync = true
 
 require 'simplecov'
-SimpleCov.start
-
 require 'simplecov-cobertura'
-SimpleCov.formatter = SimpleCov::Formatter::CoberturaFormatter
+unless SimpleCov.running || ENV['PICKS']
+  SimpleCov.command_name('test')
+  SimpleCov.formatter = SimpleCov::Formatter::MultiFormatter.new(
+    [
+      SimpleCov::Formatter::HTMLFormatter,
+      SimpleCov::Formatter::CoberturaFormatter
+    ]
+  )
+  SimpleCov.minimum_coverage 90
+  SimpleCov.minimum_coverage_by_file 90
+  SimpleCov.start do
+    add_filter 'test/'
+    add_filter 'vendor/'
+    add_filter 'target/'
+    track_files 'lib/**/*.rb'
+    track_files '*.rb'
+  end
+end
 
+require 'minitest/autorun'
 require 'minitest/reporters'
 Minitest::Reporters.use! [Minitest::Reporters::SpecReporter.new]
 
-require 'minitest/autorun'
+require 'logger'
+require 'loog'
+require 'rake'
+require 'rake/tasklib'
 require_relative '../lib/pgtk'
+require_relative '../lib/pgtk/liquibase_task'
+require_relative '../lib/pgtk/pgsql_task'
+
+class Pgtk::Test < Minitest::Test
+  def fake_config
+    Dir.mktmpdir do |dir|
+      id = (Time.now.to_f * 1_000_000).to_i % 1_000_000
+      f = File.join(dir, 'cfg.yml')
+      Pgtk::PgsqlTask.new("pgsql#{id}") do |t|
+        t.dir = File.join(dir, 'pgsql')
+        t.user = 'hello'
+        t.password = 'A B C привет ! & | !'
+        t.dbname = 'test'
+        t.yaml = f
+        t.quiet = true
+      end
+      Rake::Task["pgsql#{id}"].invoke
+      Pgtk::LiquibaseTask.new("liquibase#{id}") do |t|
+        t.master = File.join(__dir__, '../test-resources/master.xml')
+        t.yaml = f
+        t.quiet = true
+      end
+      Rake::Task["liquibase#{id}"].invoke
+      assert_path_exists(f)
+      yield f
+    end
+  end
+
+  def fake_pool(log: Loog::NULL)
+    fake_config do |f|
+      pool = Pgtk::Pool.new(
+        Pgtk::Wire::Yaml.new(f),
+        log: log
+      )
+      pool.start(1)
+      yield pool
+    end
+  end
+end

data/test/test_impatient.rb

@@ -0,0 +1,49 @@
+# 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/impatient'
+
+# Pool test.
+# Author:: Yegor Bugayenko (yegor256@gmail.com)
+# Copyright:: Copyright (c) 2017-2025 Yegor Bugayenko
+# License:: MIT
+class TestImpatient < Pgtk::Test
+  def test_takes_version
+    fake_pool do |pool|
+      v = Pgtk::Impatient.new(pool).version
+      refute_nil(v)
+    end
+  end
+
+  def test_doesnt_interrupt
+    fake_pool do |pool|
+      id = Pgtk::Impatient.new(pool).exec(
+        'INSERT INTO book (title) VALUES ($1) RETURNING id',
+        ['1984']
+      ).first['id'].to_i
+      assert_predicate(id, :positive?)
+    end
+  end
+
+  def test_doesnt_interrupt_in_transaction
+    fake_pool do |pool|
+      Pgtk::Impatient.new(pool).transaction do |t|
+        id = t.exec(
+          'INSERT INTO book (title) VALUES ($1) RETURNING id',
+          ['1984']
+        ).first['id'].to_i
+        assert_predicate(id, :positive?)
+      end
+    end
+  end
+end

data/test/test_liquibase_task.rb

@@ -3,10 +3,10 @@
 # SPDX-FileCopyrightText: Copyright (c) 2019-2025 Yegor Bugayenko
 # SPDX-License-Identifier: MIT
 
-require 'minitest/autorun'
 require 'tmpdir'
 require 'rake'
 require 'yaml'
+require_relative 'test__helper'
 require_relative '../lib/pgtk/pgsql_task'
 require_relative '../lib/pgtk/liquibase_task'
 
@@ -14,9 +14,9 @@ require_relative '../lib/pgtk/liquibase_task'
 # Author:: Yegor Bugayenko (yegor256@gmail.com)
 # Copyright:: Copyright (c) 2017-2025 Yegor Bugayenko
 # License:: MIT
-class TestLiquibaseTask < Minitest::Test
+class TestLiquibaseTask < Pgtk::Test
   def test_basic
-    Dir.mktmpdir 'test' do |dir|
+    Dir.mktmpdir do |dir|
       Pgtk::PgsqlTask.new(:pgsql2) do |t|
         t.dir = File.join(dir, 'pgsql')
         t.user = 'hello'
@@ -39,7 +39,7 @@ class TestLiquibaseTask < Minitest::Test
   end
 
   def test_latest_version
-    Dir.mktmpdir 'test' do |dir|
+    Dir.mktmpdir do |dir|
       Pgtk::PgsqlTask.new(:pgsql) do |t|
         t.dir = File.join(dir, 'pgsql')
         t.user = 'xxx'

data/test/test_pgsql_task.rb

@@ -3,19 +3,19 @@
 # SPDX-FileCopyrightText: Copyright (c) 2019-2025 Yegor Bugayenko
 # SPDX-License-Identifier: MIT
 
-require 'minitest/autorun'
 require 'rake'
 require 'tmpdir'
 require 'yaml'
+require_relative 'test__helper'
 require_relative '../lib/pgtk/pgsql_task'
 
 # Pgsql rake task test.
 # Author:: Yegor Bugayenko (yegor256@gmail.com)
 # Copyright:: Copyright (c) 2017-2025 Yegor Bugayenko
 # License:: MIT
-class TestPgsqlTask < Minitest::Test
+class TestPgsqlTask < Pgtk::Test
   def test_basic
-    Dir.mktmpdir 'test' do |dir|
+    Dir.mktmpdir do |dir|
       Pgtk::PgsqlTask.new(:p2) do |t|
         t.dir = File.join(dir, 'pgsql')
         t.user = 'hello'
@@ -34,7 +34,7 @@ class TestPgsqlTask < Minitest::Test
   end
 
   def test_not_quiet
-    Dir.mktmpdir 'test' do |dir|
+    Dir.mktmpdir do |dir|
       Pgtk::PgsqlTask.new(:p3) do |t|
         t.dir = File.join(dir, 'pgsql')
         t.user = 'hello'

data/test/test_pool.rb

@@ -4,12 +4,12 @@
 # SPDX-License-Identifier: MIT
 
 require 'loog'
-require 'minitest/autorun'
 require 'pg'
 require 'qbash'
 require 'rake'
 require 'tmpdir'
 require 'yaml'
+require_relative 'test__helper'
 require_relative '../lib/pgtk/liquibase_task'
 require_relative '../lib/pgtk/pgsql_task'
 require_relative '../lib/pgtk/pool'
@@ -19,9 +19,9 @@ require_relative '../lib/pgtk/spy'
 # Author:: Yegor Bugayenko (yegor256@gmail.com)
 # Copyright:: Copyright (c) 2017-2025 Yegor Bugayenko
 # License:: MIT
-class TestPool < Minitest::Test
+class TestPool < Pgtk::Test
   def test_reads_version
-    bootstrap do |pool|
+    fake_pool do |pool|
       ver = pool.version
       assert(ver.start_with?('1'))
       refute_includes(ver, ' ')
@@ -29,7 +29,7 @@ class TestPool < Minitest::Test
   end
 
   def test_basic
-    bootstrap do |pool|
+    fake_pool do |pool|
       id = pool.exec(
         'INSERT INTO book (title) VALUES ($1) RETURNING id',
         ['Elegant Objects']
@@ -38,9 +38,20 @@ class TestPool < Minitest::Test
     end
   end
 
+  def test_queries_with_block
+    fake_pool do |pool|
+      pool.exec('INSERT INTO book (title) VALUES ($1)', ['1984'])
+      rows = []
+      pool.exec('SELECT * FROM book') do |row|
+        rows.append(row)
+      end
+      assert_equal(1, rows.size)
+    end
+  end
+
   def test_with_spy
     queries = []
-    bootstrap do |pool|
+    fake_pool do |pool|
       pool = Pgtk::Spy.new(pool) { |sql| queries.append(sql) }
       pool.exec(
         ['INSERT INTO book', '(title) VALUES ($1)'],
@@ -52,7 +63,7 @@ class TestPool < Minitest::Test
   end
 
   def test_complex_query
-    bootstrap do |pool|
+    fake_pool do |pool|
       pool.exec(
         "
         INSERT INTO book (title) VALUES ('one');
@@ -64,7 +75,7 @@ class TestPool < Minitest::Test
 
   def test_logs_sql
     log = Loog::Buffer.new
-    bootstrap(log: log) do |pool|
+    fake_pool(log: log) do |pool|
       pool.exec(
         'INSERT INTO book (title) VALUES ($1)',
         ['Object Thinking']
@@ -75,7 +86,7 @@ class TestPool < Minitest::Test
 
   def test_logs_errors
     log = Loog::Buffer.new
-    bootstrap(log: log) do |pool|
+    fake_pool(log: log) do |pool|
       assert_raises(PG::UndefinedTable) do
         pool.exec('INSERT INTO tableDoesNotExist (a) VALUES (42)')
       end
@@ -84,7 +95,7 @@ class TestPool < Minitest::Test
   end
 
   def test_transaction
-    bootstrap do |pool|
+    fake_pool do |pool|
       id = Pgtk::Spy.new(pool).transaction do |t|
         t.exec('DELETE FROM book')
         t.exec(
@@ -100,7 +111,7 @@ class TestPool < Minitest::Test
   end
 
   def test_transaction_with_error
-    bootstrap do |pool|
+    fake_pool do |pool|
       pool.exec('DELETE FROM book')
       assert_empty(pool.exec('SELECT * FROM book'))
       assert_raises(StandardError) do
@@ -116,7 +127,7 @@ class TestPool < Minitest::Test
   end
 
   def test_reconnects_on_pg_error
-    bootstrap do |pool|
+    fake_pool do |pool|
       assert_raises PG::UndefinedTable do
         pool.exec('SELECT * FROM thisiserror')
       end
@@ -128,7 +139,7 @@ class TestPool < Minitest::Test
 
   def test_reconnects_on_pg_reboot
     port = RandomPort::Pool::SINGLETON.acquire
-    Dir.mktmpdir 'test' do |dir|
+    Dir.mktmpdir do |dir|
       id = rand(100..999)
       Pgtk::PgsqlTask.new("pgsql#{id}") do |t|
         t.dir = File.join(dir, 'pgsql')
@@ -181,33 +192,4 @@ class TestPool < Minitest::Test
       end
     end
   end
-
-  private
-
-  def bootstrap(log: Loog::NULL)
-    Dir.mktmpdir 'test' do |dir|
-      id = rand(100..999)
-      Pgtk::PgsqlTask.new("pgsql#{id}") do |t|
-        t.dir = File.join(dir, 'pgsql')
-        t.user = 'hello'
-        t.password = 'A B C привет ! & | !'
-        t.dbname = 'test'
-        t.yaml = File.join(dir, 'cfg.yml')
-        t.quiet = true
-      end
-      Rake::Task["pgsql#{id}"].invoke
-      Pgtk::LiquibaseTask.new("liquibase#{id}") do |t|
-        t.master = File.join(__dir__, '../test-resources/master.xml')
-        t.yaml = File.join(dir, 'cfg.yml')
-        t.quiet = true
-      end
-      Rake::Task["liquibase#{id}"].invoke
-      pool = Pgtk::Pool.new(
-        Pgtk::Wire::Yaml.new(File.join(dir, 'cfg.yml')),
-        log: log
-      )
-      pool.start(1)
-      yield pool
-    end
-  end
 end

data/test/test_stash.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright (c) 2019-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+require_relative 'test__helper'
+require_relative '../lib/pgtk/pool'
+require_relative '../lib/pgtk/stash'
+
+# Pool test.
+# Author:: Yegor Bugayenko (yegor256@gmail.com)
+# Copyright:: Copyright (c) 2017-2025 Yegor Bugayenko
+# License:: MIT
+class TestStash < Pgtk::Test
+  def test_simple_insert
+    fake_pool do |pool|
+      id = Pgtk::Stash.new(pool).exec(
+        'INSERT INTO book (title) VALUES ($1) RETURNING id',
+        ['Elegant Objects']
+      )[0]['id'].to_i
+      assert_predicate(id, :positive?)
+    end
+  end
+
+  def test_caching
+    fake_pool do |pool|
+      stash = Pgtk::Stash.new(pool)
+      query = 'SELECT count(*) FROM book'
+      first_result = stash.exec(query)
+      second_result = stash.exec(query)
+      assert_equal(first_result.to_a, second_result.to_a)
+      assert_same(first_result, second_result)
+    end
+  end
+
+  def test_cache_invalidation
+    fake_pool do |pool|
+      stash = Pgtk::Stash.new(pool)
+      query = 'SELECT count(*) FROM book'
+      first_result = stash.exec(query)
+      stash.exec('INSERT INTO book (title) VALUES ($1)', ['New Book'])
+      second_result = stash.exec(query)
+      refute_same(first_result, second_result)
+    end
+  end
+
+  def test_caching_with_params
+    fake_pool do |pool|
+      stash = Pgtk::Stash.new(pool)
+      query = 'SELECT * FROM book WHERE title = $1'
+      first_result = stash.exec(query, ['Elegant Objects'])
+      second_result = stash.exec(query, ['Elegant Objects'])
+      assert_equal(first_result.to_a, second_result.to_a)
+      assert_same(first_result, second_result)
+      different_param_result = stash.exec(query, ['Different Title'])
+      refute_same(first_result, different_param_result)
+    end
+  end
+
+  def test_version
+    fake_pool do |pool|
+      stash = Pgtk::Stash.new(pool)
+      assert_match(/^\d+\.\d+/, stash.version)
+    end
+  end
+
+  def test_transaction
+    fake_pool do |pool|
+      stash = Pgtk::Stash.new(pool)
+      stash.exec('INSERT INTO book (title) VALUES ($1)', ['Transaction Test'])
+      stash.transaction do |tx|
+        result = tx.exec('SELECT title FROM book WHERE title = $1', ['Transaction Test'])
+        assert_equal('Transaction Test', result[0]['title'])
+        true
+      end
+    end
+  end
+
+  def test_start
+    fake_pool do |pool|
+      stash = Pgtk::Stash.new(pool)
+      stash.exec('INSERT INTO book (title) VALUES ($1)', ['Start Test'])
+      new_stash = stash.start(1)
+      assert_instance_of(Pgtk::Stash, new_stash)
+      result = new_stash.exec('SELECT title FROM book WHERE title = $1', ['Start Test'])
+      assert_equal('Start Test', result[0]['title'])
+    end
+  end
+end

data/test/test_wire.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright (c) 2019-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+require 'cgi'
+require 'yaml'
+require_relative 'test__helper'
+require_relative '../lib/pgtk/wire'
+
+# Wire test.
+# Author:: Yegor Bugayenko (yegor256@gmail.com)
+# Copyright:: Copyright (c) 2017-2025 Yegor Bugayenko
+# License:: MIT
+class TestWire < Pgtk::Test
+  def test_connects
+    fake_config do |f|
+      wire = Pgtk::Wire::Yaml.new(f)
+      c = wire.connection
+      refute_nil(c)
+    end
+  end
+
+  def test_connects_via_env_variable
+    fake_config do |f|
+      c = YAML.load_file(f)['pgsql']
+      v = 'DATABASE_URL'
+      ENV[v] = [
+        "postgres://#{CGI.escape(c['user'])}:#{CGI.escape(c['password'])}",
+        "@#{CGI.escape(c['host'])}:#{CGI.escape(c['port'].to_s)}/#{CGI.escape(c['dbname'])}"
+      ].join
+      wire = Pgtk::Wire::Env.new(v)
+      c = wire.connection
+      refute_nil(c)
+    end
+  end
+end