pgtk 0.32.4 → 0.32.6

data/lib/pgtk/pool.rb

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
-require 'loog'
 # SPDX-FileCopyrightText: Copyright (c) 2019-2026 Yegor Bugayenko
 # SPDX-License-Identifier: MIT
 
 require 'ellipsized'
+require 'loog'
 require 'pg'
 require 'tago'
 require_relative '../pgtk'
@@ -50,11 +50,6 @@ require_relative 'wire'
 # Copyright:: Copyright (c) 2019-2026 Yegor Bugayenko
 # License:: MIT
 class Pgtk::Pool
-  # Raised when no connection becomes available from the pool within
-  # the configured timeout. Indicates that all connections are currently
-  # taken by other threads and none was returned in time.
-  class Busy < StandardError; end
-
   # Constructor.
   #
   # The +idle+ option guards against the cold-slot SSL desync that bites
@@ -78,6 +73,7 @@ class Pgtk::Pool
     @idle = idle
     @log = log
     @pool = IterableQueue.new(max, timeout)
+    @lock = Mutex.new
     @started = false
   end
 
@@ -85,7 +81,12 @@ class Pgtk::Pool
   #
   # @return [String] Version of PostgreSQL server
   def version
-    @version ||= exec('SHOW server_version')[0]['server_version'].split[0]
+    @version ||=
+      begin
+        conn = @pool.pop
+        @pool.push(conn)
+        conn.parameter_status('server_version').split[0]
+      end
   end
 
   # Get as much details about it as possible.
@@ -108,20 +109,22 @@ class Pgtk::Pool
   # open at the same time. For example, Heroku free PostgreSQL database
   # allows only one connection open.
   def start!
-    return if @started
-    @max.times do
-      @pool.push(@wire.connection)
-    end
-    (2 * @max).times do
-      connect { |c| c.exec('SELECT 1') }
-    rescue StandardError => e
-      @log.warn("Pool warm-up query failed, slot will be retried: #{e.message.strip}")
-    end
-    @max.times do
-      connect { |c| c.exec('SELECT 1') }
+    @lock.synchronize do
+      return if @started
+      @max.times do
+        @pool.push(@wire.connection)
+      end
+      (2 * @max).times do
+        connect { |c| c.exec('SELECT 1') }
+      rescue StandardError => e
+        @log.warn("Pool warm-up query failed, slot will be retried: #{e.message.strip}")
+      end
+      @max.times do
+        connect { |c| c.exec('SELECT 1') }
+      end
+      @started = true
+      @log.debug("PostgreSQL pool started with #{@max} connections")
     end
-    @started = true
-    @log.debug("PostgreSQL pool started with #{@max} connections")
   end
 
   # Make a query and return the result as an array of hashes. For example,
@@ -198,9 +201,7 @@ class Pgtk::Pool
       t = Txn.new(c, @log)
       t.exec('START TRANSACTION')
       begin
-        r = yield(t)
-        t.exec('COMMIT')
-        r
+        yield(t).tap { t.exec('COMMIT') }
       ensure
         if c.transaction_status != PG::Constants::PQTRANS_IDLE
           begin
@@ -213,124 +214,6 @@ class Pgtk::Pool
     end
   end
 
-  # Thread-safe queue implementation that supports iteration.
-  # Unlike Ruby's Queue class, this implementation allows safe iteration
-  # over all elements while maintaining thread safety for concurrent access.
-  #
-  # This class is used internally by Pool to store database connections
-  # and provide the ability to iterate over them for inspection purposes.
-  #
-  # The queue is bounded by size. When an item is taken out, it remains in
-  # the internal array but is marked as "taken". When returned, it's placed
-  # back in its original slot and marked as available.
-  class IterableQueue
-    def initialize(size, timeout)
-      @size = size
-      @timeout = timeout
-      @items = []
-      @taken = []
-      @free = []
-      @mutex = Mutex.new
-      @condition = ConditionVariable.new
-    end
-
-    def push(item)
-      @mutex.synchronize do
-        if @items.size < @size
-          @items << item
-          @taken << false
-          @free << (@items.size - 1)
-        else
-          index = @items.index(item)
-          if index.nil?
-            index = @taken.index(true)
-            raise(StandardError, 'No taken slot found') if index.nil?
-            @items[index] = item
-          end
-          @taken[index] = false
-          @free << index
-        end
-        @condition.signal
-      end
-    end
-
-    def pop
-      @mutex.synchronize do
-        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + @timeout
-        while @free.empty?
-          remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
-          raise(Busy, "No free connection appeared in the pool after #{@timeout}s of waiting") if remaining <= 0
-          @condition.wait(@mutex, remaining)
-        end
-        index = @free.shift
-        @taken[index] = true
-        @items[index]
-      end
-    end
-
-    def size
-      @mutex.synchronize do
-        @items.size
-      end
-    end
-
-    def map(&)
-      @mutex.synchronize do
-        @items.map(&)
-      end
-    end
-  end
-
-  # A temporary class to execute a single SQL request.
-  class Txn
-    def initialize(conn, log)
-      @conn = conn
-      @log = log
-    end
-
-    # Exec a single parameterized command.
-    # @param [String] query The SQL query with params inside (possibly)
-    # @param [Array] args List of arguments
-    # @param [Integer] result Should be 0 for text results, 1 for binary
-    # @yield [Hash] Rows
-    def exec(query, args = [], result = 0)
-      start = Time.now
-      sql = query.is_a?(Array) ? query.join(' ') : query
-      @conn.instance_variable_set(:@pgtk_last_query, sql)
-      @conn.instance_variable_set(:@pgtk_started_at, start)
-      begin
-        out =
-          if args.empty?
-            @conn.exec(sql) do |res|
-              if block_given?
-                yield(res)
-              else
-                res.each.to_a
-              end
-            end
-          else
-            @conn.exec_params(sql, args, result) do |res|
-              if block_given?
-                yield(res)
-              else
-                res.each.to_a
-              end
-            end
-          end
-      rescue StandardError => e
-        @log.error("#{sql} -> #{e.message}")
-        raise(e)
-      end
-      lag = Time.now - start
-      if lag < 1
-        @log.debug("#{sql} >> #{start.ago} / #{@conn.object_id}")
-      else
-        @log.info("#{sql} >> #{start.ago}")
-      end
-      out
-    end
-  end
-
   private
 
   def connect
@@ -371,9 +254,9 @@ class Pgtk::Pool
   end
 
   def stale(conn)
-    return nil if @idle.nil?
+    return if @idle.nil?
     last = conn.instance_variable_get(:@pgtk_last_used)
-    return nil if last.nil? || Time.now - last < @idle
+    return if last.nil? || Time.now - last < @idle
     begin
       conn.exec('SELECT 1')
       nil
@@ -383,19 +266,23 @@ class Pgtk::Pool
   end
 
   def info(conn)
-    pipelines = { PG::Constants::PQ_PIPELINE_ON => 'ON', PG::Constants::PQ_PIPELINE_OFF => 'OFF',
-                  PG::Constants::PQ_PIPELINE_ABORTED => 'ABORTED' }
-    statuses = { PG::Constants::CONNECTION_OK => 'OK', PG::Constants::CONNECTION_BAD => 'BAD' }
-    transactions = { PG::Constants::PQTRANS_IDLE => 'IDLE', PG::Constants::PQTRANS_ACTIVE => 'ACTIVE',
-                     PG::Constants::PQTRANS_INTRANS => 'INTRANS', PG::Constants::PQTRANS_INERROR => 'INERROR',
-                     PG::Constants::PQTRANS_UNKNOWN => 'UNKNOWN' }
     conn.instance_variable_set(:@pgtk_pid, conn.backend_pid)
     parts = [
       '    ',
       "##{conn.backend_pid}",
-      pipelines.fetch(conn.pipeline_status, "pipeline_status=#{conn.pipeline_status}"),
-      statuses.fetch(conn.status, "status=#{conn.status}"),
-      transactions.fetch(conn.transaction_status, "transaction_status=#{conn.transaction_status}")
+      {
+        PG::Constants::PQ_PIPELINE_ON => 'ON', PG::Constants::PQ_PIPELINE_OFF => 'OFF',
+        PG::Constants::PQ_PIPELINE_ABORTED => 'ABORTED'
+      }.fetch(conn.pipeline_status, "pipeline_status=#{conn.pipeline_status}"),
+      { PG::Constants::CONNECTION_OK => 'OK', PG::Constants::CONNECTION_BAD => 'BAD' }.fetch(
+        conn.status,
+        "status=#{conn.status}"
+      ),
+      {
+        PG::Constants::PQTRANS_IDLE => 'IDLE', PG::Constants::PQTRANS_ACTIVE => 'ACTIVE',
+        PG::Constants::PQTRANS_INTRANS => 'INTRANS', PG::Constants::PQTRANS_INERROR => 'INERROR',
+        PG::Constants::PQTRANS_UNKNOWN => 'UNKNOWN'
+      }.fetch(conn.transaction_status, "transaction_status=#{conn.transaction_status}")
     ]
     if conn.transaction_status != PG::Constants::PQTRANS_IDLE
       started = conn.instance_variable_get(:@pgtk_started_at)
@@ -434,3 +321,7 @@ class Pgtk::Pool
     @wire.connection
   end
 end
+
+require_relative 'pool/busy'
+require_relative 'pool/iterable_queue'
+require_relative 'pool/txn'

data/lib/pgtk/retry/exhausted.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright (c) 2019-2026 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+require_relative '../../pgtk'
+
+class Pgtk::Retry; end
+
+# Raised when all retry attempts have been exhausted. The original
+# exception that caused the last failure is available via #cause,
+# so its message and stack trace are preserved for debugging.
+#
+# Author:: Yegor Bugayenko (yegor256@gmail.com)
+# Copyright:: Copyright (c) 2019-2026 Yegor Bugayenko
+# License:: MIT
+class Pgtk::Retry::Exhausted < StandardError; end

data/lib/pgtk/retry.rb

@@ -49,11 +49,6 @@ require_relative 'impatient'
 # Copyright:: Copyright (c) 2019-2026 Yegor Bugayenko
 # License:: MIT
 class Pgtk::Retry
-  # Raised when all retry attempts have been exhausted. The original
-  # exception that caused the last failure is available via #cause,
-  # so its message and stack trace are preserved for debugging.
-  class Exhausted < StandardError; end
-
   BACKOFFS = [0.05, 0.2, 1.0].freeze
 
   # Constructor.
@@ -122,3 +117,5 @@ class Pgtk::Retry
     @pool.transaction(&)
   end
 end
+
+require_relative 'retry/exhausted'

data/lib/pgtk/spy.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
-require 'loog'
 # SPDX-FileCopyrightText: Copyright (c) 2019-2026 Yegor Bugayenko
 # SPDX-License-Identifier: MIT
 
+require 'loog'
 require 'pg'
 require_relative '../pgtk'
 require_relative 'wire'
@@ -83,9 +83,9 @@ class Pgtk::Spy
   # @return [Array] Result rows
   def exec(sql, *)
     start = Time.now
-    ret = @pool.exec(sql, *)
-    @block&.call(sql.is_a?(Array) ? sql.join(' ') : sql, Time.now - start)
-    ret
+    @pool.exec(sql, *).tap do
+      @block&.call(sql.is_a?(Array) ? sql.join(' ') : sql, Time.now - start)
+    end
   end
 
   # Run a transaction with spying on each SQL query.

data/lib/pgtk/stash.rb

@@ -29,8 +29,11 @@ require_relative '../pgtk'
 # Copyright:: Copyright (c) 2019-2026 Yegor Bugayenko
 # License:: MIT
 class Pgtk::Stash
-  MODS = %w[INSERT DELETE UPDATE LOCK VACUUM TRANSACTION COMMIT ROLLBACK REINDEX TRUNCATE CREATE ALTER DROP SET].freeze
-  MODS_RE = Regexp.new("(^|\\s)(#{MODS.join('|')})(\\s|$)")
+  MODS = %w[
+    INSERT DELETE UPDATE LOCK VACUUM TRANSACTION COMMIT ROLLBACK
+    REINDEX TRUNCATE CREATE ALTER DROP SET START
+  ].freeze
+  MODS_RE = Regexp.new("\\A(#{MODS.join('|')})(\\s|$)")
 
   IDENT = '[a-z_][a-z0-9_]*'
 
@@ -39,9 +42,13 @@ class Pgtk::Stash
 
   READS_RE = Regexp.new("(?<=^|\\s)(?:FROM|JOIN)\\s(#{IDENT})(?=\\s|;|$)")
 
-  SEPARATOR = ' --%*@#~($-- '
+  NONDETERMINISTIC = /
+    \b(?:NOW|CURRENT_TIMESTAMP|CURRENT_DATE|CURRENT_TIME|
+    LOCALTIMESTAMP|LOCALTIME|RANDOM|GEN_RANDOM_UUID|
+    CLOCK_TIMESTAMP)(?:\s*\(|(?=[^a-z0-9_]|$))
+  /ix
 
-  private_constant :MODS, :ALTS, :IDENT, :MODS_RE, :ALTS_RE, :READS_RE, :SEPARATOR
+  private_constant :MODS, :ALTS, :IDENT, :MODS_RE, :ALTS_RE, :READS_RE, :NONDETERMINISTIC
 
   # Initialize a new Stash with query caching.
   #
@@ -76,7 +83,9 @@ class Pgtk::Stash
     @pool = pool
     @stash = stash
     @stash[:table_mod] ||= {}
-    @stash[:table_inflight] ||= {}
+    unless @stash[:table_inflight].default_proc
+      @stash[:table_inflight] = Hash.new { |h, k| h[k] = Concurrent::AtomicFixnum.new(0) }
+    end
     @loog = loog
     @entrance = entrance
     @refill = refill
@@ -109,8 +118,7 @@ class Pgtk::Stash
   # @return [String] Multi-line text representation of the current cache state
   def dump
     @entrance.with_read_lock do
-      qq = queries
-      body(qq)
+      body(queries)
     end
   end
 
@@ -122,8 +130,10 @@ class Pgtk::Stash
   # @return [PG::Result] Query result object
   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)
+    if MODS_RE.match?(pure)
       modify(pure, params, result)
+    elsif /(^|\s)pg_[a-z_]+\(/.match?(pure)
+      @pool.exec(pure, params, result)
     else
       select(pure, params, result)
     end
@@ -146,7 +156,7 @@ class Pgtk::Stash
       {
         q: q.dup,
         c: kk.values.count,
-        p: kk.values.sum { |vv| vv[:popularity] },
+        p: kk.values.sum { |vv| vv[:popularity]&.value || 0 },
         s: kk.values.count { |vv| vv[:stale] },
         u: kk.values.map { |vv| vv[:used] }.max || Time.now
       }
@@ -223,49 +233,42 @@ class Pgtk::Stash
     tables = pure.scan(ALTS_RE).flatten
     tables.uniq!
     affected = (tables + tables.flat_map { |t| @cascades&.fetch(t, []) || [] }).uniq
-    @entrance.with_write_lock do
-      affected.each { |t| @stash[:table_inflight][t] = (@stash[:table_inflight][t] || 0) + 1 }
-    end
+    affected.each { |t| @stash[:table_inflight][t].increment }
     begin
-      ret = @pool.exec(pure, params, result)
-      now = Time.now
-      @entrance.with_write_lock do
-        affected.each do |t|
-          @stash[:table_inflight][t] -= 1
-          old = @stash[:table_mod][t]
-          stamp = old && old > now ? old : now
-          @stash[:table_mod][t] = stamp
-          @stash[:tables][t]&.each do |q|
-            @stash[:queries][q]&.each_key do |key|
-              @stash[:queries][q][key][:stale] = stamp
+      @pool.exec(pure, params, result).tap do
+        now = Time.now
+        @entrance.with_write_lock do
+          affected.each do |t|
+            @stash[:table_inflight][t].decrement
+            @stash[:table_mod][t] = (@stash[:table_mod][t] || 0) + 1
+            @stash[:tables][t]&.each do |q|
+              @stash[:queries][q]&.each_key do |key|
+                @stash[:queries][q][key][:stale] = now
+              end
             end
           end
         end
       end
-      ret
     rescue StandardError
-      @entrance.with_write_lock do
-        affected.each { |t| @stash[:table_inflight][t] -= 1 }
-      end
+      affected.each { |t| @stash[:table_inflight][t].decrement }
       raise
     end
   end
 
   def select(pure, params, result)
-    key = params.join(SEPARATOR)
-    ret = @stash.dig(:queries, pure, key, :ret)
-    if ret.nil? || @stash.dig(:queries, pure, key, :stale)
+    ret = @stash.dig(:queries, pure, params, :ret)
+    if ret.nil? || @stash.dig(:queries, pure, params, :stale)
       tables = pure.scan(READS_RE).flatten
       tables.uniq!
       marks = tables.to_h { |t| [t, @stash[:table_mod][t]] }
       ret = @pool.exec(pure, params, result)
-      cache(pure, key, params, result, ret, tables, marks) unless pure.include?(' NOW() ')
+      cache(pure, params, result, ret, tables, marks) unless pure.match?(NONDETERMINISTIC)
     end
-    bump(pure, key) if @stash.dig(:queries, pure, key)
+    bump(pure, params) if @stash.dig(:queries, pure, params)
     ret
   end
 
-  def cache(pure, key, params, result, ret, tables, marks)
+  def cache(pure, params, result, ret, tables, marks)
     raise(ArgumentError, "No tables at #{pure.inspect}") if tables.empty?
     @entrance.with_write_lock do
       tables.each do |t|
@@ -273,7 +276,7 @@ class Pgtk::Stash
         @stash[:tables][t].append(pure).uniq!
       end
       @stash[:queries][pure] ||= {}
-      existing = @stash[:queries][pure][key]
+      existing = @stash[:queries][pure][params]
       stillborn = tables.any? { |t| (cur = @stash[:table_mod][t]) && cur != marks[t] }
       entry = { ret:, params:, result:, used: Time.now }
       entry[:stale] =
@@ -283,31 +286,38 @@ class Pgtk::Stash
           Time.now
         end
       entry.delete(:stale) if entry[:stale].nil?
-      @stash[:queries][pure][key] = entry
+      entry[:popularity] = (existing && existing[:popularity]) || Concurrent::AtomicFixnum.new
+      @stash[:queries][pure][params] = entry
     end
   end
 
-  def bump(pure, key)
-    @entrance.with_write_lock do
-      @stash[:queries][pure][key][:popularity] ||= 0
-      @stash[:queries][pure][key][:popularity] += 1
-      @stash[:queries][pure][key][:used] = Time.now
-    end
+  # Bump popularity and last-used time of a cached entry.
+  #
+  # This runs without the exclusive write lock: popularity is a
+  # +Concurrent::AtomicFixnum+ and +used+ is a plain assignment of an
+  # immutable value, neither of which mutates the structure of the
+  # +@stash[:queries]+ tree. Keeping it off the writer lock means a
+  # read-only workload never serializes through the writer (see #414).
+  #
+  # @return [void]
+  def bump(pure, params)
+    entry = @stash.dig(:queries, pure, params)
+    return unless entry
+    (entry[:popularity] ||= Concurrent::AtomicFixnum.new).increment
+    entry[:used] = Time.now
   end
 
   # Calculate total number of cached query results.
   #
   # @return [Integer] Total count of cached query results
   def cached
-    @entrance.with_write_lock do
+    @entrance.with_read_lock do
       @stash[:queries].values.sum { |kk| kk.values.size }
     end
   end
 
   # Discover ON DELETE CASCADE / ON UPDATE CASCADE foreign keys so that a
   # modify on the parent table also invalidates cached queries on children.
-  #
-  # @return [nil]
   def cascade!
     direct = Hash.new { |h, k| h[k] = [] }
     @pool.exec(<<~SQL).each { |r| direct[r['parent']] << r['child'] }
@@ -324,7 +334,6 @@ class Pgtk::Stash
         AND tc.table_schema NOT IN ('pg_catalog', 'information_schema')
     SQL
     @cascades = direct.keys.to_h { |p| [p, transitive(p, direct, []).uniq] }
-    nil
   end
 
   def transitive(parent, direct, seen)
@@ -356,6 +365,8 @@ class Pgtk::Stash
           end
         end
       end
+    rescue StandardError => e
+      @loog.warn("Stash capper crashed: #{e.class}: #{e.message}")
     end
   end
 
@@ -367,26 +378,30 @@ class Pgtk::Stash
           evict(q) if @stash[:queries][q].empty?
         end
       end
+    rescue StandardError => e
+      @loog.warn("Stash retiree crashed: #{e.class}: #{e.message}")
     end
   end
 
-  def evict(query)
-    @stash[:queries].delete(query)
-    @stash[:tables].each_value { |list| list.delete(query) }
-    @stash[:tables].delete_if { |_, list| list.empty? }
-  end
-
   def refiller!
     Concurrent::TimerTask.execute(execution_interval: @refill, executor: @tpool) do
       ranked.each { |q| replenish(q) }
+    rescue StandardError => e
+      @loog.warn("Stash refiller crashed: #{e.class}: #{e.message}")
     end
   end
 
+  def evict(query)
+    @stash[:queries].delete(query)
+    @stash[:tables].each_value { |list| list.delete(query) }
+    @stash[:tables].delete_if { |_, list| list.empty? }
+  end
+
   def ranked
     qq =
       @entrance.with_write_lock do
         @stash[:queries]
-          .map { |k, v| [k, v.values.sum { |vv| vv[:popularity] }, v.values.any? { |vv| vv[:stale] }] }
+          .map { |k, v| [k, v.values.sum { |vv| vv[:popularity]&.value || 0 }, v.values.any? { |vv| vv[:stale] }] }
       end
     qq.select { _1[2] }.sort_by { -_1[1] }.map { _1[0] }
   end
@@ -414,7 +429,7 @@ class Pgtk::Stash
           next unless h
           next unless h[:stale] == mark
           next if pinned.any? { |t, m| @stash[:table_mod][t] != m }
-          next if tables.any? { |t| (@stash[:table_inflight][t] || 0).positive? }
+          next if tables.any? { |t| @stash[:table_inflight][t].value.positive? }
           h[:ret] = ret
           h.delete(:stale)
         end

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.32.4' unless defined?(VERSION)
+  VERSION = '0.32.6' unless defined?(VERSION)
 end

data/lib/pgtk/wire/direct.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright (c) 2019-2026 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+require 'pg'
+require_relative '../../pgtk'
+
+module Pgtk::Wire; end
+
+# Simple wire with details.
+#
+# Author:: Yegor Bugayenko (yegor256@gmail.com)
+# Copyright:: Copyright (c) 2019-2026 Yegor Bugayenko
+# 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
+  # @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?
+    @port = port
+    @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, **@opts)
+  end
+end

data/lib/pgtk/wire/env.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright (c) 2019-2026 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+require 'cgi'
+require 'uri'
+require_relative '../../pgtk'
+require_relative 'direct'
+
+module Pgtk::Wire; 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-2026 Yegor Bugayenko
+# License:: MIT
+class Pgtk::Wire::Env
+  # Constructor.
+  #
+  # @param [String] var The name of the environment variable with the connection 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 #{var.inspect} is not set") if @value.nil?
+    @opts = opts
+  end
+
+  # Create a new connection to PostgreSQL server.
+  def connection
+    uri = URI(@value)
+    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]),
+      **(uri.query ? URI.decode_www_form(uri.query).to_h.transform_keys(&:to_sym) : {}).merge(@opts)
+    ).connection
+  end
+end