pgbouncerhero 3.0.0 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 269d1da746f222ec69b19046e30b54eda65b082be5be4df7177dc44007c71042
-  data.tar.gz: 9653ffded27e1f8580f6de55f2385fedcd0ac3e52ce5fa607a1cab5bcff3b766
+  metadata.gz: 913492602328ce8fb2d3731212ccd7cef95c2a9429fbe6d4112d9a65d5853b35
+  data.tar.gz: 5475f266d924090db51b7a242cc7a7e9b90e917dd485e562f346d7f471d3e9bf
 SHA512:
-  metadata.gz: 946980cd130e213f922110a77258beda36d4973cd9d3215f840bb62fde4960c0e84e479076c8dc5853b4c16f69c67b5546d3dd61f21e9e009ed0b1f15f422625
-  data.tar.gz: 85d1f29c93363ff5dafe39cd0140229b40f623cd5c9433e1c68c4e18a9181e4eaa0bbc0765b35ed03bf981521c6995c0c9ae3d46b1b0737cc595cfa13ab3eb43
+  metadata.gz: 0e6ceb49a3f0c1b28a2edeb0939fdc7bd9f4284c02c5361f879ecedd7cb9af17f1862f5943fb75b9c79e03f5d75d0242fefc4c8ee7b67cf43b62c1ee0414c345
+  data.tar.gz: 96bc7a41d920340e9fce91c6686b6819a71393713b8e4e559e95cf790ebcae3b5d7fba13a29b62d32342aced8dceb8376c0db92b2c29f3678252199ae4c2f4e4

data/CHANGELOG.md

@@ -1,3 +1,31 @@
+## Unreleased
+
+## 3.1.0 - 2026-08-23
+
+**New:**
+- Read-only mode for hiding and server-side blocking PgBouncer administrative commands
+- PgBouncer state visibility and Resume controls
+- Integration coverage across supported PgBouncer 1.23, 1.24, and 1.25 releases
+- Bounded, thread-safe connection pools per PgBouncer with configurable size and checkout timeout
+- Explicit `Database#with_connection` leases for running multiple commands on one connection
+- Real PgBouncer integration coverage for admin queries, summaries, reloads, authentication, and reconnection
+- A dedicated CI integration job backed by the repository's Docker Compose stack
+- Configurable `PgBouncerHero.config_path`, resolved from the host application's `Rails.root` by default
+- `PgBouncerHero.reset!` for reloading configuration and connections safely
+- Request-level engine coverage and gem-package validation in CI
+
+**Improved:**
+- Use `SHUTDOWN WAIT_FOR_CLIENTS` for graceful shutdowns initiated from the dashboard
+- Reconnect stale or failed pooled connections automatically and close every pool on reset
+- Pin PostgreSQL and PgBouncer development images and wait for container health before testing
+- Let Dependabot maintain Docker image versions alongside gems and GitHub Actions
+- Protect PgBouncer connections from concurrent use while allowing bounded parallel queries
+- Resolve parameterized group and database names consistently in routes and controllers
+- Load Rails engine dependencies explicitly and declare Propshaft as a runtime dependency
+- Cache Appraisal dependencies directly in the Ruby/Rails CI matrix
+- Pin GitHub Actions to their current immutable release commits
+- Add read-only workflow permissions, cancellation of superseded runs, and job timeouts
+
 ## 3.0.0
 
 **Breaking Changes:**

data/README.md

@@ -14,6 +14,7 @@ A graphical user interface for your PgBouncers.
 
 - Ruby >= 3.2
 - Rails >= 7.2
+- PgBouncer >= 1.23
 - Propshaft (asset pipeline)
 - importmap-rails
 
@@ -69,6 +70,8 @@ pgbouncers:
   production:
     primary:
       url: <%= ENV["PGBOUNCER_PRODUCTION_PRIMARY_DATABASE_URL"] %>
+      pool_size: 5
+      pool_timeout: 5
     replica:
       url: <%= ENV["PGBOUNCER_PRODUCTION_REPLICA_DATABASE_URL"] %>
   staging:
@@ -76,14 +79,69 @@ pgbouncers:
       url: <%= ENV["PGBOUNCER_STAGING_PRIMARY_DATABASE_URL"] %>
     replica:
       url: <%= ENV["PGBOUNCER_STAGING_REPLICA_DATABASE_URL"] %>
+
+# Optional: allow monitoring while blocking all administrative commands
+read_only: true
+```
+
+Environment-specific top-level keys are also supported. PgBouncerHero reads
+`config/pgbouncerhero.yml` from the host application's `Rails.root` by default.
+An initializer can point to a different file:
+
+```ruby
+PgBouncerHero.config_path = Rails.root.join("config/pgbouncerhero.production.yml")
+```
+
+Changing `PgBouncerHero.env` or `config_path` resets cached groups and closes
+their open connections. Call `PgBouncerHero.reset!` after changing a config
+file at runtime, or `PgBouncerHero.disconnect!` when only the connections need
+to be closed. Stale connections reconnect automatically.
+
+The PostgreSQL connection timeout defaults to five seconds and can be changed
+with `PGBOUNCERHERO_TIMEOUT`.
+
+PgBouncerHero keeps a bounded, lazily created connection pool for each
+configured PgBouncer. The pool defaults to five connections with a five-second
+checkout timeout. Set `PGBOUNCERHERO_POOL_SIZE` and
+`PGBOUNCERHERO_POOL_TIMEOUT` to change the defaults for every PgBouncer, or set
+`pool_size` and `pool_timeout` on an individual database entry as shown above.
+Per-database settings take precedence over environment variables.
+
+Code that needs to issue multiple commands on the same PostgreSQL connection
+can lease one explicitly:
+
+```ruby
+database.with_connection do |connection|
+  connection.exec("SHOW VERSION")
+  connection.exec("SHOW CONFIG")
+end
 ```
 
+`database.connection` remains available as a connection-compatible proxy for
+existing integrations. Connections are checked when borrowed, and stale or
+failed connections are discarded and recreated automatically.
+
+### Safe Administration
+
+The dashboard shows PgBouncer's current state and provides Reload, Suspend,
+Resume, and graceful shutdown controls. Dashboard shutdown uses
+`SHUTDOWN WAIT_FOR_CLIENTS`: PgBouncer stops accepting new clients and exits
+after existing clients disconnect. The Ruby API keeps `database.shutdown` as
+the immediate command for compatibility and also accepts `:immediate`,
+`:wait_for_clients`, or `:wait_for_servers`. State visibility requires
+PgBouncer 1.19 or newer; graceful shutdown modes require PgBouncer 1.23 or
+newer.
+
+Set `read_only: true` at the top level of `config/pgbouncerhero.yml`, or set
+`PGBOUNCERHERO_READ_ONLY=true`, to hide and server-side reject every
+administrative command. The environment variable takes precedence over YAML.
+
 ## Development
 
 Start PostgreSQL and PgBouncer with Docker:
 
 ```bash
-docker compose up -d
+docker compose up --detach --wait
 ```
 
 Run the dummy Rails app:
@@ -98,16 +156,34 @@ Then open http://localhost:3000/pgbouncerhero.
 Run the test suite:
 
 ```bash
-bundle exec rake              # tests + rubocop + herb
-bundle exec appraisal rake test  # tests across Rails 7.2, 8.0, 8.1
+bundle exec rake                 # unit/integration-free tests + rubocop + herb
+bundle exec appraisal rake test  # tests across Rails 7.2, 8.0, and 8.1
+bundle exec rake build           # build and validate the gem package
+bundle exec rake test:integration # real PgBouncer admin-console tests
 ```
 
+The integration task expects PostgreSQL and PgBouncer from the Compose stack.
+Override `PGBOUNCERHERO_INTEGRATION_URL` to test another PgBouncer instance.
+The default is `postgres://pgbouncer:pgbouncer@127.0.0.1:6432/pgbouncer`.
+CI runs this suite against PgBouncer 1.23, 1.24, and 1.25.
+
 Stop Docker when done:
 
 ```bash
-docker compose down
+docker compose down --volumes
 ```
 
+### Releasing
+
+Releases use a scoped RubyGems OIDC API Key Role through GitHub Actions, with no
+long-lived RubyGems API key. The role is restricted to the `pgbouncerhero` gem,
+the `kwent/pgbouncerhero` repository, and the `rubygems.org` audience. Store its
+role token in the `RUBYGEMS_OIDC_ROLE` GitHub Actions secret. Then run the
+**Release** workflow on `master` and enter the version already committed in
+`lib/pgbouncerhero/version.rb`. The workflow verifies the version and test
+suite, exchanges GitHub's OIDC identity for a short-lived credential, publishes
+the gem, pushes the version tag, and creates the matching GitHub release.
+
 ## Contributing
 
 1. Fork it

data/app/controllers/pg_bouncer_hero/application_controller.rb

@@ -13,10 +13,11 @@ module PgBouncerHero
     def set_database
       @groups = PgBouncerHero.groups
       if params[:group] && params[:database]
-        @database = PgBouncerHero.groups[params[:group]].databases.find { |db| db.id.to_s == params[:database].to_s }
+        @group = @groups.fetch(params[:group])
+        @database = @group.databases.find { |database| database.name.parameterize == params[:database] }
       else
-        @group = @groups.first
-        @database = @groups.first.last.databases.first
+        _group_id, @group = @groups.first
+        @database = @group.databases.first
       end
     end
   end

data/app/controllers/pg_bouncer_hero/database_controller.rb

@@ -1,5 +1,7 @@
 module PgBouncerHero
   class DatabaseController < ApplicationController
+    before_action :ensure_writable!, only: %i[reload suspend resume shutdown]
+
     def summary
       if @database.connection
         @dbs = @database.summary
@@ -48,6 +50,14 @@ module PgBouncerHero
       end
     end
 
+    def state
+      if @database.connection
+        @state = @database.state
+      else
+        flash[:error] = "#{@database.name} does not look online."
+      end
+    end
+
     def reload
       execute_admin_command(:reload, "reloaded")
     end
@@ -56,15 +66,25 @@ module PgBouncerHero
       execute_admin_command(:suspend, "suspended")
     end
 
+    def resume
+      execute_admin_command(:resume, "resumed")
+    end
+
     def shutdown
-      execute_admin_command(:shutdown, "shut down")
+      execute_admin_command(:shutdown, "asked to shut down after its clients disconnect", :wait_for_clients)
     end
 
     private
 
-    def execute_admin_command(command, past_tense)
+    def ensure_writable!
+      return unless PgBouncerHero.read_only?
+
+      render plain: "PgBouncerHero is configured as read-only.", status: :forbidden
+    end
+
+    def execute_admin_command(command, past_tense, *arguments)
       if @database.connection
-        @database.public_send(command)
+        @database.public_send(command, *arguments)
         flash[:success] = "#{@database.name} has been #{past_tense}."
       else
         flash[:error] = "#{@database.name} does not look online."

data/app/views/pg_bouncer_hero/database/_menu.html.erb

@@ -7,11 +7,17 @@
       <%= link_to "Pools", pools_path(database: database.name.parameterize), class: "px-3 py-1.5 text-sm rounded-md #{is_active('pools') ? 'bg-gray-900 text-white' : 'text-gray-600 hover:text-gray-900 hover:bg-gray-100'}" %>
       <%= link_to "Clients", clients_path(database: database.name.parameterize), class: "px-3 py-1.5 text-sm rounded-md #{is_active('clients') ? 'bg-gray-900 text-white' : 'text-gray-600 hover:text-gray-900 hover:bg-gray-100'}" %>
       <%= link_to "Configuration", conf_path(database: database.name.parameterize), class: "px-3 py-1.5 text-sm rounded-md #{is_active('conf') ? 'bg-gray-900 text-white' : 'text-gray-600 hover:text-gray-900 hover:bg-gray-100'}" %>
+      <%= link_to "State", state_path(database: database.name.parameterize), class: "px-3 py-1.5 text-sm rounded-md #{is_active('state') ? 'bg-gray-900 text-white' : 'text-gray-600 hover:text-gray-900 hover:bg-gray-100'}" %>
     </div>
     <div class="flex items-center gap-2">
-      <%= button_to "Reload", reload_path(database: database.name.parameterize), method: :post, class: "px-3 py-1.5 text-sm font-medium rounded-md border border-green-300 text-green-700 hover:bg-green-50", form: { data: { turbo_confirm: "Are you sure?" } } %>
-      <%= button_to "Suspend", suspend_path(database: database.name.parameterize), method: :post, class: "px-3 py-1.5 text-sm font-medium rounded-md border border-blue-300 text-blue-700 hover:bg-blue-50", form: { data: { turbo_confirm: "Are you sure?" } } %>
-      <%= button_to "Shutdown", shutdown_path(database: database.name.parameterize), method: :post, class: "px-3 py-1.5 text-sm font-medium rounded-md border border-red-300 text-red-700 hover:bg-red-50", form: { data: { turbo_confirm: "Are you sure?" } } %>
+      <% if PgBouncerHero.read_only? %>
+        <span class="inline-flex items-center rounded-md bg-gray-100 px-2 py-1 text-xs font-medium text-gray-700 ring-1 ring-gray-300 ring-inset">Read-only</span>
+      <% else %>
+        <%= button_to "Reload", reload_path(database: database.name.parameterize), method: :post, class: "px-3 py-1.5 text-sm font-medium rounded-md border border-green-300 text-green-700 hover:bg-green-50", form: { data: { turbo_confirm: "Reload PgBouncer configuration?" } } %>
+        <%= button_to "Suspend", suspend_path(database: database.name.parameterize), method: :post, class: "px-3 py-1.5 text-sm font-medium rounded-md border border-blue-300 text-blue-700 hover:bg-blue-50", form: { data: { turbo_confirm: "Suspend all PgBouncer socket processing until Resume is selected?" } } %>
+        <%= button_to "Resume", resume_path(database: database.name.parameterize), method: :post, class: "px-3 py-1.5 text-sm font-medium rounded-md border border-green-300 text-green-700 hover:bg-green-50", form: { data: { turbo_confirm: "Resume PgBouncer socket processing?" } } %>
+        <%= button_to "Graceful shutdown", shutdown_path(database: database.name.parameterize), method: :post, class: "px-3 py-1.5 text-sm font-medium rounded-md border border-red-300 text-red-700 hover:bg-red-50", form: { data: { turbo_confirm: "Stop accepting new clients and shut down after existing clients disconnect?" } } %>
+      <% end %>
     </div>
   </div>
 </nav>

data/app/views/pg_bouncer_hero/database/_state.html.erb

@@ -0,0 +1,11 @@
+<div class="bg-white rounded-lg border border-gray-200 shadow-sm p-4">
+  <h4 class="text-base font-semibold text-gray-900 mb-3">State</h4>
+  <dl class="grid grid-cols-1 sm:grid-cols-2 gap-4">
+    <% state.each do |row| %>
+      <div>
+        <dt class="text-xs font-medium text-gray-500 uppercase tracking-wider"><%= row["key"].titleize %></dt>
+        <dd class="mt-1 text-sm text-gray-900"><%= row["value"] %></dd>
+      </div>
+    <% end %>
+  </dl>
+</div>

data/app/views/pg_bouncer_hero/database/state.html.erb

@@ -0,0 +1,4 @@
+<%= render partial: "menu", locals: {database: @database} %>
+<% if @state %>
+  <%= render partial: "state", locals: {state: @state} %>
+<% end %>

data/config/routes.rb

@@ -1,15 +1,23 @@
 PgBouncerHero::Engine.routes.draw do
+  group_exists = ->(request) { PgBouncerHero.groups.key?(request.params[:group]) }
+  database_exists = lambda do |request|
+    group = PgBouncerHero.groups[request.params[:group]]
+    group&.databases&.any? { |database| database.name.parameterize == request.params[:database] }
+  end
+
   root to: "home#index"
-  scope path: ":group", constraints: proc { |req| (PgBouncerHero.groups.keys.map(&:parameterize) + [ nil ]).include?(req.params[:group]) } do
-    scope path: ":database", constraints: proc { |req| (PgBouncerHero.groups[req.params[:group]].databases.map(&:name).map(&:parameterize) + [ nil ]).include?(req.params[:database]) } do
+  scope path: ":group", constraints: group_exists do
+    scope path: ":database", constraints: database_exists do
       get :summary, controller: :database
       get :databases, controller: :database
       get :stats, controller: :database
       get :pools, controller: :database
       get :clients, controller: :database
       get :conf, controller: :database
+      get :state, controller: :database
       post :reload, controller: :database
       post :suspend, controller: :database
+      post :resume, controller: :database
       post :shutdown, controller: :database
     end
   end

data/lib/generators/pgbouncerhero/templates/config.yml

@@ -3,6 +3,8 @@ pgbouncers:
     primary:
       # eg. postgres://user:password@host:port/pgbouncer
       # url: <%%= ENV["PGBOUNCER_PRODUCTION_PRIMARY_DATABASE_URL"] %>
+      # pool_size: 5
+      # pool_timeout: 5
     # Add more databases
     # replica:
     #   url: <%%= ENV["PGBOUNCER_PRODUCTION_REPLICA_DATABASE_URL"] %>
@@ -14,3 +16,6 @@ pgbouncers:
 
 # Time zone (defaults to app time zone)
 # time_zone: "Pacific Time (US & Canada)"
+
+# Hide and reject Reload, Suspend, Resume, and Shutdown commands
+# read_only: true

data/lib/pgbouncerhero/connection.rb

@@ -10,19 +10,60 @@ module PgBouncerHero
     end
 
     def connection
-      @connection ||= begin
-        PG.connect(
-          host: @host,
-          port: @port,
-          user: @user,
-          password: @password,
-          dbname: @dbname,
-          connect_timeout: @timeout
-        )
-      rescue StandardError => e
-        Rails.logger.error("[PGBouncerHero] Host:#{@host} | Database Name:#{@dbname} | Timeout: #{@timeout}s => #{e}")
-        nil
-      end
+      disconnect! if @connection && connection_invalid?(@connection)
+      @connection ||= connect
+    rescue StandardError => e
+      Rails.logger.error("[PGBouncerHero] Host:#{@host} | Database Name:#{@dbname} | Timeout: #{@timeout}s => #{e}")
+      nil
+    end
+
+    def connected?
+      !connection.nil?
+    end
+
+    def with_connection
+      raw_connection = connection
+      return unless raw_connection
+
+      yield raw_connection
+    rescue PG::Error
+      disconnect!
+      raise
+    end
+
+    def disconnect!
+      @connection&.finish unless @connection&.finished?
+    rescue PG::Error
+      nil
+    ensure
+      @connection = nil
+    end
+
+    def method_missing(method_name, *, **, &)
+      with_connection { |raw_connection| raw_connection.public_send(method_name, *, **, &) }
+    end
+
+    def respond_to_missing?(method_name, include_private = false)
+      PG::Connection.public_instance_methods(include_private).include?(method_name) || super
+    end
+
+    private
+
+    def connect
+      PG.connect(
+        host: @host,
+        port: @port,
+        user: @user,
+        password: @password,
+        dbname: @dbname,
+        connect_timeout: @timeout
+      )
+    end
+
+    def connection_invalid?(connection)
+      connection.finished? || connection.status != PG::CONNECTION_OK
+    rescue PG::Error
+      true
     end
   end
 end

data/lib/pgbouncerhero/database.rb

@@ -1,14 +1,23 @@
+require "connection_pool"
+require "monitor"
+
 module PgBouncerHero
   class Database
     include Methods::Basics
 
-    attr_reader :id, :config, :group
+    DEFAULT_POOL_SIZE = 5
+    DEFAULT_POOL_TIMEOUT = 5
+
+    attr_reader :id, :config, :group, :pool_size, :pool_timeout
 
     def initialize(group, id, config)
       @id = id
       @config = config || {}
-      @url = URI.parse(config["url"].to_s)
+      @url = URI.parse(@config["url"].to_s)
       @group = group
+      @pool_size = positive_integer_setting("pool_size", "PGBOUNCERHERO_POOL_SIZE", DEFAULT_POOL_SIZE)
+      @pool_timeout = positive_float_setting("pool_timeout", "PGBOUNCERHERO_POOL_TIMEOUT", DEFAULT_POOL_TIMEOUT)
+      @pool_monitor = Monitor.new
     end
 
     def name
@@ -16,7 +25,28 @@ module PgBouncerHero
     end
 
     def connection
-      @connection ||= connection_model.new(host, port, user, password, dbname).connection
+      proxy = connection_proxy
+      proxy if with_connection { true }
+    end
+
+    def with_connection
+      pool = connection_pool
+      pool.with do |managed_connection|
+        managed_connection.with_connection { |raw_connection| yield raw_connection }
+      end
+    rescue ConnectionPool::TimeoutError => e
+      Rails.logger.error("[PGBouncerHero] #{name} connection pool timed out after #{pool_timeout}s: #{e.message}")
+      nil
+    end
+
+    def disconnect!
+      pool = @pool_monitor.synchronize do
+        current_pool = @connection_pool
+        @connection_pool = nil
+        @connection_proxy = nil
+        current_pool
+      end
+      pool&.shutdown(&:disconnect!)
     end
 
     def host
@@ -41,6 +71,26 @@ module PgBouncerHero
 
     private
 
+    def execute(command)
+      with_connection { |raw_connection| raw_connection.exec(command) }
+    end
+
+    def connection_pool
+      @pool_monitor.synchronize do
+        @connection_pool ||= ConnectionPool.new(size: pool_size, timeout: pool_timeout) { build_connection }
+      end
+    end
+
+    def connection_proxy
+      @pool_monitor.synchronize do
+        @connection_proxy ||= ConnectionPool::Wrapper.new(pool: connection_pool)
+      end
+    end
+
+    def build_connection
+      connection_model.new(host, port, user, password, dbname)
+    end
+
     def connection_model
       @connection_model ||= begin
         Class.new(PgBouncerHero::Connection) do
@@ -50,5 +100,21 @@ module PgBouncerHero
         end
       end
     end
+
+    def positive_integer_setting(config_key, environment_key, default)
+      value = config.fetch(config_key, ENV.fetch(environment_key, default))
+      parsed = Integer(value)
+      raise ArgumentError, "#{config_key} must be greater than zero" unless parsed.positive?
+
+      parsed
+    end
+
+    def positive_float_setting(config_key, environment_key, default)
+      value = config.fetch(config_key, ENV.fetch(environment_key, default))
+      parsed = Float(value)
+      raise ArgumentError, "#{config_key} must be a finite number greater than zero" unless parsed.positive? && parsed.finite?
+
+      parsed
+    end
   end
 end

data/lib/pgbouncerhero/methods/basics.rb

@@ -1,6 +1,13 @@
 module PgBouncerHero
   module Methods
     module Basics
+      SHUTDOWN_MODES = {
+        nil => "",
+        immediate: "",
+        wait_for_clients: " WAIT_FOR_CLIENTS",
+        wait_for_servers: " WAIT_FOR_SERVERS"
+      }.freeze
+
       def summary
         if connection
           l = lists
@@ -12,31 +19,40 @@ module PgBouncerHero
         end
       end
       def databases
-        connection.exec("SHOW databases")
+        execute("SHOW databases")
       end
       def stats
-        connection.exec("SHOW stats")
+        execute("SHOW stats")
       end
       def lists
-        connection.exec("SHOW lists")
+        execute("SHOW lists")
       end
       def pools
-        connection.exec("SHOW pools")
+        execute("SHOW pools")
       end
       def clients
-        connection.exec("SHOW clients")
+        execute("SHOW clients")
       end
       def conf
-        connection.exec("SHOW config")
+        execute("SHOW config")
+      end
+      def state
+        execute("SHOW state")
       end
       def reload
-        connection.exec("RELOAD")
+        execute("RELOAD")
       end
       def suspend
-        connection.exec("SUSPEND")
+        execute("SUSPEND")
+      end
+      def resume
+        execute("RESUME")
       end
-      def shutdown
-        connection.exec("SHUTDOWN")
+      def shutdown(mode = nil)
+        suffix = SHUTDOWN_MODES.fetch(mode)
+        execute("SHUTDOWN#{suffix}")
+      rescue KeyError
+        raise ArgumentError, "unsupported shutdown mode: #{mode.inspect}"
       end
     end
   end

data/lib/pgbouncerhero/version.rb

@@ -1,3 +1,3 @@
 module PgBouncerHero
-  VERSION = "3.0.0"
+  VERSION = "3.1.0"
 end

data/lib/pgbouncerhero.rb

@@ -1,26 +1,44 @@
-require "pgbouncerhero/version"
-
-require "pgbouncerhero/methods/basics"
-
-require "pgbouncerhero/group"
-require "pgbouncerhero/engine" if defined?(Rails)
-
-require "pgbouncerhero/connection"
-
+require "erb"
+require "monitor"
+require "pathname"
+require "yaml"
+require "rails"
 require "pg"
 require "importmap-rails"
 require "turbo-rails"
 require "stimulus-rails"
 
+require "pgbouncerhero/version"
+require "pgbouncerhero/methods/basics"
+require "pgbouncerhero/connection"
+require "pgbouncerhero/group"
+require "pgbouncerhero/engine"
+
 module PgBouncerHero
+  class ConfigurationError < StandardError; end
+
+  BOOLEAN_SETTINGS = {
+    true => true,
+    false => false,
+    "1" => true,
+    "0" => false,
+    "true" => true,
+    "false" => false,
+    "yes" => true,
+    "no" => false,
+    "on" => true,
+    "off" => false
+  }.freeze
+  private_constant :BOOLEAN_SETTINGS
+
+  STATE_MONITOR = Monitor.new
+  private_constant :STATE_MONITOR
+
   mattr_accessor :importmap, default: Importmap::Map.new
 
   class << self
-    attr_accessor :env
-  end
-  self.env = ENV["RAILS_ENV"] || ENV["RACK_ENV"] || "development"
+    attr_reader :env
 
-  class << self
     def time_zone=(time_zone)
       @time_zone = time_zone.is_a?(ActiveSupport::TimeZone) ? time_zone : ActiveSupport::TimeZone[time_zone.to_s]
     end
@@ -29,38 +47,105 @@ module PgBouncerHero
       @time_zone || Time.zone
     end
 
+    def env=(env)
+      STATE_MONITOR.synchronize do
+        @env = env.to_s
+        reset!
+      end
+    end
+
+    def config_path
+      STATE_MONITOR.synchronize { @config_path || default_config_path }
+    end
+
+    def config_path=(path)
+      STATE_MONITOR.synchronize do
+        @config_path = path && Pathname(path)
+        reset!
+      end
+    end
+
     def config
-      @config ||= begin
-        path = "config/pgbouncerhero.yml"
-
-        config = YAML.safe_load(ERB.new(File.read(path)).result, aliases: true) if File.exist?(path)
-        config ||= {}
-
-        if config[env]
-          config[env]
-        elsif config["pgbouncers"]
-          config
-        else
-          {
-            "pgbouncers" => {
-              "default" => {
-                "primary" => {
-                  "url" => ENV["PGBOUNCERHERO_DATABASE_URL"]
-                }
-              }
-            }
-          }
+      STATE_MONITOR.synchronize { @config ||= selected_config(load_config) }
+    end
+
+    def groups
+      STATE_MONITOR.synchronize do
+        @groups ||= config.fetch("pgbouncers").to_h do |group_id, _databases|
+          [ group_id.parameterize, PgBouncerHero::Group.new(group_id, config.fetch("pgbouncers")) ]
         end
       end
     end
 
-    def groups
-      @groups ||= begin
-        mapped = config["pgbouncers"].map do |group_id, _hash|
-          [ group_id.parameterize, PgBouncerHero::Group.new(group_id, config["pgbouncers"]) ]
+    def read_only?
+      value = ENV.fetch("PGBOUNCERHERO_READ_ONLY") { config.fetch("read_only", false) }
+      BOOLEAN_SETTINGS.fetch(value.is_a?(String) ? value.downcase : value)
+    rescue KeyError
+      raise ConfigurationError, "read_only must be a boolean"
+    end
+
+    def disconnect!
+      STATE_MONITOR.synchronize do
+        @groups&.each_value do |group|
+          group.databases.each(&:disconnect!)
         end
-        Hash[mapped]
       end
     end
+
+    def reset!
+      STATE_MONITOR.synchronize do
+        disconnect!
+        @config = nil
+        @groups = nil
+      end
+    end
+
+    private
+
+    def default_config_path
+      (Rails.root || Pathname.pwd).join("config/pgbouncerhero.yml")
+    end
+
+    def load_config
+      return {} unless config_path.file?
+
+      loaded = YAML.safe_load(ERB.new(config_path.read).result, aliases: true)
+      return {} if loaded.nil?
+      return loaded if loaded.is_a?(Hash)
+
+      raise ConfigurationError, "#{config_path} must contain a YAML mapping"
+    end
+
+    def selected_config(loaded)
+      selected = loaded.fetch(env, loaded)
+      unless selected.is_a?(Hash)
+        raise ConfigurationError, "configuration for #{env.inspect} must be a YAML mapping"
+      end
+
+      return default_config unless selected.key?("pgbouncers")
+
+      pgbouncers = selected["pgbouncers"]
+      unless pgbouncers.is_a?(Hash) && pgbouncers.any? && pgbouncers.values.all? { |databases| databases.is_a?(Hash) && databases.any? }
+        raise ConfigurationError, '"pgbouncers" must contain at least one group with one database'
+      end
+
+      selected
+    end
+
+    def default_config
+      {
+        "pgbouncers" => {
+          "default" => {
+            "primary" => {
+              "url" => ENV["PGBOUNCERHERO_DATABASE_URL"]
+            }
+          }
+        }
+      }
+    end
   end
+
+  self.env = ENV["RAILS_ENV"] || ENV["RACK_ENV"] || "development"
 end
+
+at_exit { PgBouncerHero.disconnect! }

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pgbouncerhero
 version: !ruby/object:Gem::Version
-  version: 3.0.0
+  version: 3.1.0
 platform: ruby
 authors:
 - Quentin Rousseau
@@ -16,6 +16,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '7.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -23,6 +26,29 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '7.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+- !ruby/object:Gem::Dependency
+  name: propshaft
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
 - !ruby/object:Gem::Dependency
   name: importmap-rails
   requirement: !ruby/object:Gem::Requirement
@@ -30,6 +56,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '1.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -37,6 +66,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '1.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
 - !ruby/object:Gem::Dependency
   name: turbo-rails
   requirement: !ruby/object:Gem::Requirement
@@ -44,6 +76,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '1.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -51,6 +86,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '1.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
 - !ruby/object:Gem::Dependency
   name: stimulus-rails
   requirement: !ruby/object:Gem::Requirement
@@ -58,6 +96,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '1.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -65,6 +106,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '1.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
 - !ruby/object:Gem::Dependency
   name: pg
   requirement: !ruby/object:Gem::Requirement
@@ -72,6 +116,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '1.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -79,6 +126,29 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '1.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+- !ruby/object:Gem::Dependency
+  name: connection_pool
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -113,14 +183,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.0'
+        version: '6.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.0'
+        version: '6.0'
 - !ruby/object:Gem::Dependency
   name: appraisal
   requirement: !ruby/object:Gem::Requirement
@@ -203,11 +273,13 @@ files:
 - app/views/pg_bouncer_hero/database/_databases.html.erb
 - app/views/pg_bouncer_hero/database/_menu.html.erb
 - app/views/pg_bouncer_hero/database/_pools.html.erb
+- app/views/pg_bouncer_hero/database/_state.html.erb
 - app/views/pg_bouncer_hero/database/_stats.html.erb
 - app/views/pg_bouncer_hero/database/clients.html.erb
 - app/views/pg_bouncer_hero/database/conf.html.erb
 - app/views/pg_bouncer_hero/database/databases.html.erb
 - app/views/pg_bouncer_hero/database/pools.html.erb
+- app/views/pg_bouncer_hero/database/state.html.erb
 - app/views/pg_bouncer_hero/database/stats.html.erb
 - app/views/pg_bouncer_hero/database/summary.html.erb
 - app/views/pg_bouncer_hero/home/_card.html.erb
@@ -233,6 +305,7 @@ licenses:
 metadata:
   source_code_uri: https://github.com/kwent/pgbouncerhero
   changelog_uri: https://github.com/kwent/pgbouncerhero/blob/master/CHANGELOG.md
+  documentation_uri: https://github.com/kwent/pgbouncerhero#readme
   bug_tracker_uri: https://github.com/kwent/pgbouncerhero/issues
   rubygems_mfa_required: 'true'
 rdoc_options: []