pgtk 0.23.0 → 0.24.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 57546e93aaf2c029a795f61302d943e4f64e7d1e03b77d339636bdfb73d271d5
-  data.tar.gz: 467c0493e69e8402b83ea6b537ac69760d5e712ac088b856307d2418449878f9
+  metadata.gz: 88c5e888b9c116ec175abea3c43fa02d2a878a3edbc61c901be4a07f5a7730d4
+  data.tar.gz: 608f79d18ee7799c1a4bd200d8157a64f25033431ab972fe41072ac7223dae44
 SHA512:
-  metadata.gz: 83b61249a1888eed186c7faa7814c9a07f28fa9268d8d7fad1dfc0b9d7f4b304d4c835116fce6e32b6e651d7a2fc12731417c52922daae8ad9759419b32d2344
-  data.tar.gz: 5107f90f035a11e3ab17c8718f759c6869ea24d3c195dafb1845d546587244ad1e6f82dca7da5b505055cefdafa97f7b0e6390f17374e2458f773e54f7f9dd75
+  metadata.gz: 788a641261c89c9da31133e8d38a9cfcb1bbb91d6d1e2b43161ade3827930ff54baf6096e1ac7c54f13d7921928aefc163d2a5750000e3a916a17c212ea8097e
+  data.tar.gz: 237557831c63cc930743f152abd2a08cd5783d664f4a56f3a5faf24bd359097799463fa0eb66440085b99c46e50a338faf3b76677addc36b0a3f21fb0b415fbe

data/Gemfile.lock

@@ -26,7 +26,7 @@ GEM
       loog (~> 0.6)
       tago (~> 0.1)
     joined (0.4.0)
-    json (2.15.2)
+    json (2.16.0)
     language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
     logger (1.7.0)
@@ -52,7 +52,7 @@ GEM
     pg (1.6.2-x64-mingw-ucrt)
     pg (1.6.2-x86_64-linux)
     prism (1.6.0)
-    qbash (0.4.5)
+    qbash (0.4.7)
       backtrace (> 0)
       elapsed (> 0)
       loog (> 0)
@@ -76,7 +76,7 @@ GEM
       rubocop-ast (>= 1.47.1, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.47.1)
+    rubocop-ast (1.48.0)
       parser (>= 3.3.7.2)
       prism (~> 1.4)
     rubocop-minitest (0.38.2)
@@ -101,7 +101,7 @@ GEM
     simplecov-html (0.13.2)
     simplecov_json_formatter (0.1.4)
     slop (4.10.1)
-    tago (0.3.0)
+    tago (0.4.0)
     threads (0.4.1)
       backtrace (~> 0)
       concurrent-ruby (~> 1.0)

data/README.md

@@ -220,6 +220,19 @@ require 'pgtk/stash'
 stash = Pgtk::Stash.new(pgsql)
 ```
 
+You can configure `Stash` with optional parameters:
+
+```ruby
+stash = Pgtk::Stash.new(
+  pgsql,
+  cap: 10_000,          # Maximum cached query results (default: 10,000)
+  cap_interval: 60,     # Seconds between cache size enforcement (default: 60)
+  refill_interval: 16,  # Seconds between stale query refilling (default: 16)
+  threads: 4,           # Worker threads for background refilling (default: 4)
+  max_queue_length: 128 # Maximum refilling tasks in queue (default: 128)
+)
+```
+
 `Stash` automatically caches read queries and invalidates the cache
 when tables are modified:
 

data/lib/pgtk/pool.rb

@@ -7,6 +7,7 @@ require 'pg'
 require 'loog'
 require 'tago'
 require_relative '../pgtk'
+require_relative 'version'
 require_relative 'wire'
 
 # Pool provides a connection pool for PostgreSQL database connections.
@@ -74,6 +75,7 @@ class Pgtk::Pool
   def dump
     [
       'Pgtk::Pool',
+      "  Pgtk version: #{Pgtk::VERSION}",
       "  PgSQL version: #{version}",
       "  #{@pool.size} connections:",
       @pool.map do |c|

data/lib/pgtk/stash.rb

@@ -6,6 +6,7 @@
 require 'concurrent-ruby'
 require 'joined'
 require 'loog'
+require 'tago'
 require_relative '../pgtk'
 
 # Database query cache implementation.
@@ -18,6 +19,12 @@ require_relative '../pgtk'
 #
 # The implementation is very naive! Use it at your own risk.
 #
+# @example Basic usage
+#   pool = Pgtk::Pool.new(...)
+#   stash = Pgtk::Stash.new(pool, cap: 1000, refill_interval: 30)
+#   stash.start!
+#   result = stash.exec('SELECT * FROM users WHERE id = $1', [42])
+#
 # Author:: Yegor Bugayenko (yegor256@gmail.com)
 # Copyright:: Copyright (c) 2019-2025 Yegor Bugayenko
 # License:: MIT
@@ -34,20 +41,32 @@ class Pgtk::Stash
 
   # Initialize a new Stash with query caching.
   #
-  # @param [Object] pool Original object
-  # @param [Hash] stash Optional existing stash to use (default: new empty stash)
-  # @option [Hash] queries Internal cache data (default: {})
-  # @option [Hash] tables Internal cache data (default: {})
-  # @param [Integer] refill_interval Interval in seconds for recalculate stale queries
-  # @param [Integer] max_queue_length Number of refilling tasks in the queue
-  # @param [Integer] threads Number of threads in tpool
-  # @param [Loog] loog Logger for debugging (default: null logger)
+  # @param [Object] pool The underlying connection pool that executes actual database queries
+  # @param [Hash] stash Internal cache structure containing queries and tables hashes for sharing state
+  #   across transactions
+  # @param [Integer] refill_interval Interval in seconds between background tasks that recalculate stale
+  #   cached queries
+  # @param [Integer] max_queue_length Maximum number of refilling tasks allowed in the thread pool queue
+  #   before new tasks are skipped
+  # @param [Integer] threads Number of worker threads in the background thread pool for cache refilling
+  #   operations
+  # @param [Integer] cap Maximum number of cached query results to retain; oldest queries are evicted when
+  #   this limit is exceeded
+  # @param [Integer] cap_interval Interval in seconds between background tasks that enforce the cache size
+  #   cap by removing old queries
+  # @param [Loog] loog Logger instance for debugging and monitoring cache operations (default: null logger)
+  # @param [Concurrent::ReentrantReadWriteLock] entrance Read-write lock for thread-safe cache access
+  #   shared across instances
+  # @param [Concurrent::AtomicBoolean] launched Atomic boolean flag tracking whether background tasks have
+  #   been started to prevent multiple launches
   def initialize(
     pool,
     stash: { queries: {}, tables: {} },
     refill_interval: 16,
     max_queue_length: 128,
     threads: 4,
+    cap: 10_000,
+    cap_interval: 60,
     loog: Loog::NULL,
     entrance: Concurrent::ReentrantReadWriteLock.new,
     launched: Concurrent::AtomicBoolean.new(false)
@@ -59,11 +78,19 @@ class Pgtk::Stash
     @refill_interval = refill_interval
     @max_queue_length = max_queue_length
     @threads = threads
+    @cap = cap
+    @cap_interval = cap_interval
     @loog = loog
     @tpool = Concurrent::FixedThreadPool.new(@threads)
   end
 
-  # Start a new connection pool with the given arguments.
+  # Start the connection pool and launch background cache management tasks.
+  #
+  # Initializes background timer tasks for cache refilling and size capping.
+  # The refill task periodically updates stale cached queries based on popularity.
+  # The cap task removes oldest queries when cache size exceeds the configured limit.
+  #
+  # @return [void]
   def start!
     launch!
     @pool.start!
@@ -76,38 +103,54 @@ class Pgtk::Stash
   end
 
   # Convert internal state into text.
+  #
+  # Generates a detailed report of the cache state including query counts,
+  # popularity scores, stale queries, and thread pool status.
+  #
+  # @return [String] Multi-line text representation of the current cache state
   def dump
     qq =
-      @stash[:queries].map do |k, v|
-        [
-          k.dup, # the query
-          v.values.count, # how many keys?
-          v.values.sum { |vv| vv[:popularity] }, # total popularity of all keys
-          v.values.count { |vv| vv[:stale] } # how many stale keys?
-        ]
+      @stash[:queries].map do |q, kk|
+        {
+          q: q.dup, # the query
+          c: kk.values.count, # how many keys?
+          p: kk.values.sum { |vv| vv[:popularity] }, # total popularity of all keys
+          s: kk.values.count { |vv| vv[:stale] }, # how many stale keys?
+          u: kk.values.map { |vv| vv[:used] }.max || Time.now # when was it used
+        }
       end
     [
       @pool.dump,
       '',
-      "Pgtk::Stash (refill_interval=#{@refill_interval}s, max_queue_length=#{@max_queue_length}, threads=#{@threads}):",
+      # rubocop:disable Layout/LineLength
+      "Pgtk::Stash (refill_interval=#{@refill_interval}s, max_queue_length=#{@max_queue_length}, threads=#{@threads}, cap=#{@cap}, cap_interval=#{@cap_interval}s):",
+      # rubocop:enable Layout/LineLength
       "  #{'not ' if @launched.false?}launched",
+      "  #{stash_size} queries stashed (#{stash_size > @cap ? 'above' : 'below'} the cap)",
       "  #{@tpool.queue_length} task(s) in the thread pool",
       "  #{@stash[:tables].count} table(s) in cache",
-      "  #{qq.sum { |a| a[3] }} stale quer(ies) in cache:",
-      qq.select { |a| a[3].positive? }.sort_by { -_1[2] }.take(16).map { |a| "    #{a[1]}/#{a[2]}p/#{a[3]}s: #{a[0]}" },
-      "  #{qq.count { |a| a[3].zero? }} other quer(ies) in cache:",
-      qq.select { |a| a[3].zero? }.sort_by { -_1[2] }.take(8).map { |a| "    #{a[1]}/#{a[2]}p/#{a[3]}s: #{a[0]}" }
+      "  #{qq.sum { |a| a[:s] }} stale quer(ies) in cache:",
+      qq.select { |a| a[:s].positive? }.sort_by { -_1[:p] }.take(8).map do |a|
+        "    #{a[:c]}/#{a[:p]}p/#{a[:s]}s/#{a[:u].ago}: #{a[:q]}"
+      end,
+      "  #{qq.count { |a| a[:s].zero? }} other quer(ies) in cache:",
+      qq.select { |a| a[:s].zero? }.sort_by { -_1[:p] }.take(16).map do |a|
+        "    #{a[:c]}/#{a[:p]}p/#{a[:s]}s/#{a[:u].ago}: #{a[:q]}"
+      end
     ].join("\n")
   end
 
   # Execute a SQL query with optional caching.
   #
   # Read queries are cached, while write queries bypass the cache and invalidate related entries.
+  # Queries containing modification keywords (INSERT, UPDATE, DELETE, etc.) are executed directly
+  # and trigger invalidation of cached queries for affected tables. Read queries (SELECT)
+  # are cached by query text and parameter values. Queries containing NOW() are never cached.
   #
-  # @param [String, Array<String>] query The SQL query to execute
-  # @param [Array] params Query parameters
-  # @param [Integer] result Should be 0 for text results, 1 for binary
-  # @return [PG::Result] Query result
+  # @param [String, Array<String>] query The SQL query to execute as a string or array of strings to be joined
+  # @param [Array] params Query parameters for placeholder substitution in prepared statements (default: empty array)
+  # @param [Integer] result Result format code where 0 requests text format and 1 requests binary format (default: 0)
+  # @return [PG::Result] Query result object containing rows and metadata from the database
   def exec(query, params = [], result = 0)
     pure = (query.is_a?(Array) ? query.join(' ') : query).gsub(/\s+/, ' ').strip
     if MODS_RE.match?(pure) || /(^|\s)pg_[a-z_]+\(/.match?(pure)
@@ -174,13 +217,35 @@ class Pgtk::Stash
 
   private
 
+  # Calculate total number of cached query results.
+  #
+  # Counts all cached query-parameter combinations across all queries.
+  #
+  # @return [Integer] Total count of cached query results
+  def stash_size
+    @stash[:queries].values.sum { |kk| kk.values.size }
+  end
+
+  # Launch background tasks for cache management.
+  #
+  # Starts two concurrent timer tasks: one for enforcing cache size cap by removing
+  # oldest queries, and another for refilling stale cached queries based on popularity.
+  # This method can only be called once per cache instance.
+  #
+  # @return [nil]
+  # @raise [RuntimeError] if background tasks have already been launched on this cache instance
   def launch!
     raise 'Cannot launch multiple times on same cache data' unless @launched.make_true
-    retire = 60 * 60
-    Concurrent::TimerTask.execute(execution_interval: retire, executor: @tpool) do
-      @entrance.with_write_lock do
-        @stash[:queries].each_key do |q|
-          @stash[:queries][q].delete_if { |_, h| h[:used] < Time.now - retire }
+    Concurrent::TimerTask.execute(execution_interval: @cap_interval, executor: @tpool) do
+      loop do
+        break if stash_size <= @cap
+        @entrance.with_write_lock do
+          @stash[:queries].each_key do |q|
+            m = @stash[:queries][q].values.map { |h| h[:used] }.min
+            next unless m
+            @stash[:queries][q].delete_if { |_, h| h[:used] == m }
+            @stash[:queries].delete_if { |_, kk| kk.empty? }
+          end
         end
       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.23.0'
+  VERSION = '0.24.1'
 end

metadata

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