pgtk 0.14.0 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 49420b7b7c01a8b32c8d7557ca7a7520cfaeca0a389b7ed9fc613728ce961e19
-  data.tar.gz: b2a61b0c8c6412bea801612a07b14ae67e9549c5060d3364c907a9dceb4ab040
+  metadata.gz: f5d316eba88319837e0e0076de690cb533c6d384e84c3bf02caf4bc71737ce76
+  data.tar.gz: ffee85649afc871e9a639769ebee131019e93ad11a23a93726d4cc0768eb1186
 SHA512:
-  metadata.gz: cc8fb8ab39be7276878f5031680cb9d9f2e4471863e87289a0d939aaf0c21a5b4cf4ec066c2a74fef959df6c1bafa74dba5309fc7abdacc201dd7eb214cb9b3e
-  data.tar.gz: 128dbf6deb488e9798afc7ca7a76b9f409703591c2e16839e70755dac4c50b9a88baabe308d0503a0aafed241422fa53b2cfe2499172ce6cd81b7fad69ba0185
+  metadata.gz: 38d446cdd29cd57eff8ba863f7c6f9a1fb9b18f490e6655eac0259c6945d5da2f6f0f5c18a6a4e7f55f7184c0408bc5f03228514ccbb1375c3974081b176450f
+  data.tar.gz: d8fba0d7db2ea8645f33f843d2e304a24d3b4579854b0581a408258fa2d28eb455b05005b6a7a70ff44ec2643268632c2ab8bfc8f0ac7ddaf7f566414d03bb26

data/.github/workflows/typos.yml

@@ -0,0 +1,19 @@
+# SPDX-FileCopyrightText: Copyright (c) 2019-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+---
+# yamllint disable rule:line-length
+name: typos
+'on':
+  push:
+    branches:
+      - master
+  pull_request:
+    branches:
+      - master
+jobs:
+  typos:
+    timeout-minutes: 15
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+      - uses: crate-ci/typos@v1.32.0

data/.gitignore

@@ -1,10 +1,12 @@
-*.gem
-.DS_Store
 .bundle/
+.DS_Store
 .idea/
 .yardoc/
+*.gem
 coverage/
 doc/
 node_modules/
 rdoc/
 vendor/
+
+**/.claude/settings.local.json

data/.rubocop.yml

@@ -10,6 +10,10 @@ AllCops:
   TargetRubyVersion: 2.3
   SuggestExtensions: false
   NewCops: enable
+plugins:
+  - rubocop-rake
+  - rubocop-minitest
+  - rubocop-performance
 Minitest/EmptyLineBeforeAssertionMethods:
   Enabled: false
 Style/ClassAndModuleChildren:
@@ -23,17 +27,13 @@ Layout/EmptyLineAfterGuardClause:
 Metrics/AbcSize:
   Max: 100
 Metrics/CyclomaticComplexity:
-  Max: 15
+  Max: 20
 Metrics/ClassLength:
   Max: 200
 Metrics/MethodLength:
   Max: 100
 Metrics/PerceivedComplexity:
-  Max: 15
+  Max: 20
 Metrics/ParameterLists:
   Max: 6
-plugins:
-  - rubocop-rake
-  - rubocop-minitest
-  - rubocop-performance
 require: []

data/Gemfile

@@ -17,5 +17,6 @@ gem 'rubocop-rake', '>0', require: false
 gem 'rubocop-rspec', '>0', require: false
 gem 'simplecov', '~>0.22', require: false
 gem 'simplecov-cobertura', '~>2.1'
+gem 'timeout', '>0'
 gem 'xcop', '>0', require: false
 gem 'yard', '~>0.9', require: false

data/Gemfile.lock

@@ -3,6 +3,9 @@ PATH
   specs:
     pgtk (0.0.0)
       backtrace (> 0)
+      concurrent-ruby (> 0)
+      joined (> 0)
+      logger (> 0)
       loog (> 0)
       pg (~> 1.1)
       qbash (> 0)
@@ -15,29 +18,33 @@ GEM
     ast (2.4.3)
     backtrace (0.4.0)
     builder (3.3.0)
+    concurrent-ruby (1.3.5)
     differ (0.1.2)
     docile (1.4.1)
     elapsed (0.0.1)
       loog (> 0)
       tago (> 0)
-    json (2.10.2)
+    joined (0.1.0)
+    json (2.11.3)
     language_server-protocol (3.17.0.4)
     lint_roller (1.1.0)
-    loog (0.6.0)
+    logger (1.7.0)
+    loog (0.6.1)
+      logger (~> 1.0)
     minitest (5.25.5)
     minitest-reporters (1.7.1)
       ansi
       builder
       minitest (>= 5.0)
       ruby-progressbar
-    nokogiri (1.18.6-arm64-darwin)
+    nokogiri (1.18.8-arm64-darwin)
       racc (~> 1.4)
-    nokogiri (1.18.6-x64-mingw-ucrt)
+    nokogiri (1.18.8-x64-mingw-ucrt)
       racc (~> 1.4)
-    nokogiri (1.18.6-x86_64-linux-gnu)
+    nokogiri (1.18.8-x86_64-linux-gnu)
       racc (~> 1.4)
-    parallel (1.26.3)
-    parser (3.3.7.3)
+    parallel (1.27.0)
+    parser (3.3.8.0)
       ast (~> 2.4.1)
       racc
     pg (1.5.9)
@@ -49,14 +56,14 @@ GEM
       loog (> 0)
       tago (> 0)
     racc (1.8.1)
-    rack (3.1.12)
+    rack (3.1.14)
     rainbow (3.1.1)
     rake (13.2.1)
     random-port (0.7.5)
       tago (> 0)
     regexp_parser (2.10.0)
     rexml (3.4.1)
-    rubocop (1.75.1)
+    rubocop (1.75.5)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
@@ -64,24 +71,24 @@ GEM
       parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 2.9.3, < 3.0)
-      rubocop-ast (>= 1.43.0, < 2.0)
+      rubocop-ast (>= 1.44.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.43.0)
+    rubocop-ast (1.44.1)
       parser (>= 3.3.7.2)
       prism (~> 1.4)
-    rubocop-minitest (0.37.1)
+    rubocop-minitest (0.38.0)
       lint_roller (~> 1.1)
-      rubocop (>= 1.72.1, < 2.0)
+      rubocop (>= 1.75.0, < 2.0)
       rubocop-ast (>= 1.38.0, < 2.0)
-    rubocop-performance (1.24.0)
+    rubocop-performance (1.25.0)
       lint_roller (~> 1.1)
-      rubocop (>= 1.72.1, < 2.0)
+      rubocop (>= 1.75.0, < 2.0)
       rubocop-ast (>= 1.38.0, < 2.0)
     rubocop-rake (0.7.1)
       lint_roller (~> 1.1)
       rubocop (>= 1.72.1)
-    rubocop-rspec (3.5.0)
+    rubocop-rspec (3.6.0)
       lint_roller (~> 1.1)
       rubocop (~> 1.72, >= 1.72.1)
     ruby-progressbar (1.13.0)
@@ -96,6 +103,7 @@ GEM
     simplecov_json_formatter (0.1.4)
     slop (4.10.1)
     tago (0.1.0)
+    timeout (0.4.3)
     unicode-display_width (3.1.4)
       unicode-emoji (~> 4.0, >= 4.0.4)
     unicode-emoji (4.0.4)
@@ -126,6 +134,7 @@ DEPENDENCIES
   rubocop-rspec (> 0)
   simplecov (~> 0.22)
   simplecov-cobertura (~> 2.1)
+  timeout (> 0)
   xcop (> 0)
   yard (~> 0.9)
 

data/README.md

@@ -1,12 +1,12 @@
 # Ruby + PostgreSQL + Liquibase + Rake
 
 [![EO principles respected here](https://www.elegantobjects.org/badge.svg)](https://www.elegantobjects.org)
-[![DevOps By Rultor.com](http://www.rultor.com/b/yegor256/pgtk)](http://www.rultor.com/p/yegor256/pgtk)
+[![DevOps By Rultor.com](https://www.rultor.com/b/yegor256/pgtk)](https://www.rultor.com/p/yegor256/pgtk)
 [![We recommend RubyMine](https://www.elegantobjects.org/rubymine.svg)](https://www.jetbrains.com/ruby/)
 
 [![rake](https://github.com/yegor256/pgtk/actions/workflows/rake.yml/badge.svg)](https://github.com/yegor256/pgtk/actions/workflows/rake.yml)
-[![PDD status](http://www.0pdd.com/svg?name=yegor256/pgtk)](http://www.0pdd.com/p?name=yegor256/pgtk)
-[![Gem Version](https://badge.fury.io/rb/pgtk.svg)](http://badge.fury.io/rb/pgtk)
+[![PDD status](https://www.0pdd.com/svg?name=yegor256/pgtk)](https://www.0pdd.com/p?name=yegor256/pgtk)
+[![Gem Version](https://badge.fury.io/rb/pgtk.svg)](https://badge.fury.io/rb/pgtk)
 [![Maintainability](https://api.codeclimate.com/v1/badges/3a5bebac001e5288b00d/maintainability)](https://codeclimate.com/github/yegor256/pgtk/maintainability)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/yegor256/pgtk/blob/master/LICENSE.txt)
 [![Test Coverage](https://img.shields.io/codecov/c/github/yegor256/pgtk.svg)](https://codecov.io/github/yegor256/pgtk?branch=master)
@@ -99,7 +99,7 @@ bundle exec rake pgsql liquibase
 
 A temporary PostgreSQL server will be started and the entire set of
 Liquibase SQL changes will be applied. You will be able to connect
-to it from your application, using the file `target/config.yml`.
+to it from your application, using the file `target/pgsql-config.yml`.
 
 From inside your app you may find this class useful:
 
@@ -123,7 +123,7 @@ Now you can fetch some data from the DB:
 name = pgsql.exec('SELECT name FROM user WHERE id = $1', [id])[0]['name']
 ```
 
-You may also use it if you need to run a transaction:
+You may also use it when you need to run a transaction:
 
 ```ruby
 pgsql.transaction do |t|
@@ -132,7 +132,7 @@ pgsql.transaction do |t|
 end
 ```
 
-To make your PostgreSQL database visible in your unit test, I would
+To make your PostgreSQL database visible in your unit tests, I would
 recommend you create a method `test_pgsql` in your `test__helper.rb` file
 (which is `required` in all unit tests) and implement it like this:
 
@@ -143,7 +143,6 @@ require 'pgtk/pool'
 module Minitest
   class Test
     def test_pgsql
-      config = YAML.load_file()
       @@test_pgsql ||= Pgtk::Pool.new(
         Pgtk::Wire::Yaml.new('target/pgsql-config.yml')
       ).start
@@ -152,7 +151,10 @@ module Minitest
 end
 ```
 
-You can also track all SQL queries sent through, with the help of `Pgtk::Pool`:
+## Logging with `Pgtk::Spy`
+
+You can also track all SQL queries sent through the pool,
+with the help of `Pgtk::Spy`:
 
 ```ruby
 require 'pgtk/spy'
@@ -161,11 +163,46 @@ pool = Pgtk::Spy.new(pool) do |sql|
 end
 ```
 
-Well, it works in
+## Query Caching with `Pgtk::Stash`
+
+For applications with frequent read queries,
+you can use `Pgtk::Stash` to add a caching layer:
+
+```ruby
+require 'pgtk/stash'
+stash = Pgtk::Stash.new(pgsql)
+```
+
+`Stash` automatically caches read queries and invalidates the cache
+when tables are modified:
+
+```ruby
+# First execution runs the query against the database
+result1 = stash.exec('SELECT * FROM users WHERE id = $1', [123])
+# Second execution with the same query and parameters returns cached result
+result2 = stash.exec('SELECT * FROM users WHERE id = $1', [123])
+# This modifies the 'users' table, invalidating any cached queries for that table
+stash.exec('UPDATE users SET name = $1 WHERE id = $2', ['John', 123])
+# This will execute against the database again since cache was invalidated
+result3 = stash.exec('SELECT * FROM users WHERE id = $1', [123])
+```
+
+Note that the caching implementation is basic and only suitable
+for simple queries:
+
+1. Queries must reference tables (using `FROM` or `JOIN`)
+2. Cache is invalidated by table, not by specific rows
+3. Write operations (`INSERT`, `UPDATE`, `DELETE`) bypass
+the cache and invalidate all cached queries for affected tables
+
+## Some Examples
+
+This library works in
 [netbout.com](https://github.com/yegor256/netbout),
 [wts.zold.io](https://github.com/zold-io/wts.zold.io),
 [mailanes.com](https://github.com/yegor256/mailanes), and
 [0rsk.com](https://github.com/yegor256/0rsk).
+
 They are all open source, you can see how they use `pgtk`.
 
 ## How to contribute

data/REUSE.toml

@@ -4,9 +4,17 @@
 version = 1
 [[annotations]]
 path = [
+    ".DS_Store",
+    ".gitattributes",
+    ".gitignore",
+    ".pdd",
     "**.json",
     "**.md",
+    "**.png",
     "**.txt",
+    "**/.DS_Store",
+    "**/.gitignore",
+    "**/.pdd",
     "**/*.csv",
     "**/*.jpg",
     "**/*.json",
@@ -16,15 +24,8 @@ path = [
     "**/*.svg",
     "**/*.txt",
     "**/*.vm",
-    "**/.DS_Store",
-    "**/.gitignore",
-    "**/.pdd",
     "**/CNAME",
     "**/Gemfile.lock",
-    ".DS_Store",
-    ".gitattributes",
-    ".gitignore",
-    ".pdd",
     "Gemfile.lock",
     "README.md",
     "renovate.json",

data/Rakefile

@@ -5,7 +5,6 @@
 
 require 'rubygems'
 require 'rake'
-require 'rdoc'
 require 'rake/clean'
 
 def name
@@ -37,7 +36,6 @@ require 'rubocop/rake_task'
 desc 'Run Rubocop on all directories'
 RuboCop::RakeTask.new(:rubocop) do |task|
   task.fail_on_error = true
-  task.requires << 'rubocop-rspec'
 end
 
 require 'xcop/rake_task'

data/lib/pgtk/impatient.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright (c) 2019-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+require 'timeout'
+require_relative '../pgtk'
+
+# Impatient is a decorator for Pool that enforces timeouts on all database operations.
+# It ensures that SQL queries don't run indefinitely, which helps prevent application
+# hangs and resource exhaustion when database operations are slow or stalled.
+#
+# This class implements the same interface as Pool but wraps each database operation
+# in a timeout block. If a query exceeds the specified timeout, it raises a Timeout::Error
+# exception, allowing the application to handle slow queries gracefully.
+#
+# Basic usage:
+#
+#   # Create and configure a regular pool
+#   pool = Pgtk::Pool.new(wire).start(4)
+#
+#   # Wrap the pool in an impatient decorator with a 2-second timeout
+#   impatient = Pgtk::Impatient.new(pool, 2)
+#
+#   # Execute queries with automatic timeout enforcement
+#   begin
+#     impatient.exec('SELECT * FROM large_table WHERE complex_condition')
+#   rescue Timeout::Error
+#     puts "Query timed out after 2 seconds"
+#   end
+#
+#   # Transactions also enforce timeouts on each query
+#   begin
+#     impatient.transaction do |t|
+#       t.exec('UPDATE large_table SET processed = true')
+#       t.exec('DELETE FROM queue WHERE processed = true')
+#     end
+#   rescue Timeout::Error
+#     puts "Transaction timed out"
+#   end
+#
+#   # Combining with Spy for timeout monitoring
+#   spy = Pgtk::Spy.new(impatient) do |sql, duration|
+#     puts "Query completed in #{duration} seconds: #{sql}"
+#   end
+#
+#   # Now queries are both timed and monitored
+#   spy.exec('SELECT * FROM users')
+#
+# Author:: Yegor Bugayenko (yegor256@gmail.com)
+# Copyright:: Copyright (c) 2019-2025 Yegor Bugayenko
+# License:: MIT
+class Pgtk::Impatient
+  # Constructor.
+  #
+  # @param [Pgtk::Pool] pool The pool to decorate
+  # @param [Integer] timeout Timeout in seconds for each SQL query
+  def initialize(pool, timeout = 1)
+    @pool = pool
+    @timeout = timeout
+  end
+
+  # Get the version of PostgreSQL server.
+  #
+  # @return [String] Version of PostgreSQL server
+  def version
+    @pool.version
+  end
+
+  # Execute a SQL query with a timeout.
+  #
+  # @param [String] sql The SQL query with params inside (possibly)
+  # @param [Array] args List of arguments
+  # @return [Array] Result rows
+  # @raise [Timeout::Error] If the query takes too long
+  def exec(sql, *args)
+    Timeout.timeout(@timeout) do
+      @pool.exec(sql, *args)
+    end
+  end
+
+  # Run a transaction with a timeout for each query.
+  #
+  # @yield [Pgtk::Impatient] Yields an impatient transaction
+  # @return [Object] Result of the block
+  def transaction
+    @pool.transaction do |t|
+      yield Pgtk::Impatient.new(t, @timeout)
+    end
+  end
+end

data/lib/pgtk/liquibase_task.rb

@@ -16,8 +16,38 @@ require_relative '../pgtk'
 # Copyright:: Copyright (c) 2019-2025 Yegor Bugayenko
 # License:: MIT
 class Pgtk::LiquibaseTask < Rake::TaskLib
-  attr_accessor :name, :master, :yaml, :quiet, :liquibase_version, :postgresql_version, :contexts
+  # Task name
+  # @return [Symbol]
+  attr_accessor :name
 
+  # Path to Liquibase master XML file
+  # @return [String]
+  attr_accessor :master
+
+  # Path to YAML file with PostgreSQL connection details
+  # @return [String, Array<String>]
+  attr_accessor :yaml
+
+  # Whether to suppress output
+  # @return [Boolean]
+  attr_accessor :quiet
+
+  # Liquibase version to use
+  # @return [String]
+  attr_accessor :liquibase_version
+
+  # PostgreSQL JDBC driver version to use
+  # @return [String]
+  attr_accessor :postgresql_version
+
+  # Liquibase contexts to apply
+  # @return [String]
+  attr_accessor :contexts
+
+  # Initialize a new Liquibase task.
+  #
+  # @param [Array] args Task arguments
+  # @yield [Pgtk::LiquibaseTask, Object] Yields self and task arguments
   def initialize(*args, &task_block)
     super()
     @name = args.shift || :liquibase

data/lib/pgtk/pgsql_task.rb

@@ -19,8 +19,50 @@ require_relative '../pgtk'
 # Copyright:: Copyright (c) 2019-2025 Yegor Bugayenko
 # License:: MIT
 class Pgtk::PgsqlTask < Rake::TaskLib
-  attr_accessor :name, :dir, :fresh_start, :user, :password, :dbname, :yaml, :quiet, :port, :config
+  # Task name
+  # @return [Symbol]
+  attr_accessor :name
 
+  # Directory where PostgreSQL server files will be stored
+  # @return [String]
+  attr_accessor :dir
+
+  # Whether to delete the PostgreSQL data directory on each run
+  # @return [Boolean]
+  attr_accessor :fresh_start
+
+  # PostgreSQL username
+  # @return [String]
+  attr_accessor :user
+
+  # PostgreSQL password
+  # @return [String]
+  attr_accessor :password
+
+  # PostgreSQL database name
+  # @return [String]
+  attr_accessor :dbname
+
+  # Path to YAML file where configuration will be written
+  # @return [String]
+  attr_accessor :yaml
+
+  # Whether to suppress output
+  # @return [Boolean]
+  attr_accessor :quiet
+
+  # TCP port for PostgreSQL server (random if nil)
+  # @return [Integer, nil]
+  attr_accessor :port
+
+  # Configuration options for PostgreSQL server
+  # @return [Hash]
+  attr_accessor :config
+
+  # Initialize a new PostgreSQL server task.
+  #
+  # @param [Array] args Task arguments
+  # @yield [Pgtk::PgsqlTask, Object] Yields self and task arguments
   def initialize(*args, &task_block)
     super()
     @name = args.shift || :pgsql
@@ -129,6 +171,8 @@ class Pgtk::PgsqlTask < Rake::TaskLib
         }
       }.to_yaml
     )
-    puts "PostgreSQL has been started in process ##{pid}, port #{port}" unless @quiet
+    return if @quiet
+    puts "PostgreSQL has been started in process ##{pid}, port #{port}"
+    puts "YAML config saved to #{@yaml}"
   end
 end

data/lib/pgtk/pool.rb

@@ -8,7 +8,40 @@ require 'loog'
 require_relative '../pgtk'
 require_relative 'wire'
 
-# Pool.
+# Pool provides a connection pool for PostgreSQL database connections.
+# It manages a fixed number of connections to optimize performance and
+# resource usage while providing a simple interface for database operations.
+#
+# The Pool class handles connection lifecycle, reconnects on errors,
+# and provides transaction support. It's the core class for interacting
+# with a PostgreSQL database in this library.
+#
+# Basic usage:
+#
+#   # Create a wire that knows how to connect to PostgreSQL
+#   wire = Pgtk::Wire::Direct.new(
+#     host: 'localhost',
+#     port: 5432,
+#     dbname: 'mydatabase',
+#     user: 'postgres',
+#     password: 'secret'
+#   )
+#
+#   # Create and start a connection pool with 4 connections
+#   pool = Pgtk::Pool.new(wire).start(4)
+#
+#   # Execute a simple query
+#   pool.exec('SELECT * FROM users')
+#
+#   # Execute a parameterized query
+#   pool.exec('SELECT * FROM users WHERE email = $1', ['user@example.com'])
+#
+#   # Use transactions for multiple operations
+#   pool.transaction do |t|
+#     t.exec('UPDATE accounts SET balance = balance - $1 WHERE id = $2', [100, 42])
+#     t.exec('UPDATE accounts SET balance = balance + $1 WHERE id = $2', [100, 43])
+#   end
+#
 # Author:: Yegor Bugayenko (yegor256@gmail.com)
 # Copyright:: Copyright (c) 2019-2025 Yegor Bugayenko
 # License:: MIT

data/lib/pgtk/spy.rb

@@ -8,20 +8,65 @@ require 'loog'
 require_relative '../pgtk'
 require_relative 'wire'
 
-# A pool tha spies on another pool.
+# Spy is a decorator for Pool that intercepts and tracks SQL queries.
+# It provides observability into database operations by invoking a callback
+# with the SQL query and its execution time for each database operation.
+#
+# This class implements the same interface as Pool, but adds instrumentation
+# functionality while delegating actual database operations to the decorated pool.
+# Use Spy for debugging, performance monitoring, or audit logging.
+#
+# Basic usage:
+#
+#   # Create and configure a regular pool
+#   pool = Pgtk::Pool.new(wire).start(4)
+#
+#   # Wrap the pool in a spy that tracks all executed queries
+#   queries = []
+#   spy = Pgtk::Spy.new(pool) do |sql, duration|
+#     puts "Query: #{sql}"
+#     puts "Duration: #{duration} seconds"
+#     queries << sql
+#   end
+#
+#   # Use the spy just like a regular pool, with automatic tracking
+#   spy.exec('SELECT * FROM users')
+#
+#   # Transactions also track each query inside the transaction
+#   spy.transaction do |t|
+#     t.exec('UPDATE users SET active = true WHERE id = $1', [42])
+#     t.exec('INSERT INTO audit_log (user_id, action) VALUES ($1, $2)', [42, 'activated'])
+#   end
+#
+#   # Examine collected queries for analysis
+#   puts "Total queries: #{queries.size}"
+#   puts "First query: #{queries.first}"
+#
 # Author:: Yegor Bugayenko (yegor256@gmail.com)
 # Copyright:: Copyright (c) 2019-2025 Yegor Bugayenko
 # License:: MIT
 class Pgtk::Spy
+  # Constructor.
+  #
+  # @param [Pgtk::Pool] pool The pool to spy on
+  # @yield [String, Float] Yields the SQL query and execution time
   def initialize(pool, &block)
     @pool = pool
     @block = block
   end
 
+  # Get the version of PostgreSQL server.
+  #
+  # @return [String] Version of PostgreSQL server
   def version
     @pool.version
   end
 
+  # Execute a SQL query and track its execution.
+  #
+  # @param [String] sql The SQL query with params inside (possibly)
+  # @param [Array] args List of arguments
+  # @return [Array] Result rows
   def exec(sql, *args)
     start = Time.now
     ret = @pool.exec(sql, *args)
@@ -29,6 +74,10 @@ class Pgtk::Spy
     ret
   end
 
+  # Run a transaction with spying on each SQL query.
+  #
+  # @yield [Pgtk::Spy] Yields a spy transaction
+  # @return [Object] Result of the block
   def transaction
     @pool.transaction do |t|
       yield Pgtk::Spy.new(t, &@block)