pgbouncerhero 3.0.0 → 3.2.0

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

@@ -1,4 +1,6 @@
 <%= render partial: "menu", locals: {database: @database} %>
-<% if @clients %>
-  <%= render partial: "clients", locals: {database: @database, clients: @clients} %>
+<%= monitoring_panel do %>
+  <% if @clients %>
+    <%= render partial: "clients", locals: {database: @database, clients: @clients} %>
+  <% end %>
 <% end %>

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

@@ -1,4 +1,6 @@
 <%= render partial: "menu", locals: {database: @database} %>
-<% if @conf %>
-  <%= render partial: "conf", locals: {database: @database, conf: @conf} %>
+<%= monitoring_panel do %>
+  <% if @conf %>
+    <%= render partial: "conf", locals: {database: @database, conf: @conf} %>
+  <% end %>
 <% end %>

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

@@ -1,4 +1,6 @@
 <%= render partial: "menu", locals: {database: @database} %>
-<% if @dbs %>
-  <%= render partial: "databases", locals: {database: @database, databases: @dbs} %>
+<%= monitoring_panel do %>
+  <% if @dbs %>
+    <%= render partial: "databases", locals: {database: @database, databases: @dbs} %>
+  <% end %>
 <% end %>

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

@@ -1,4 +1,6 @@
 <%= render partial: "menu", locals: {database: @database} %>
-<% if @pools %>
-  <%= render partial: "pools", locals: {database: @database, pools: @pools} %>
+<%= monitoring_panel do %>
+  <% if @pools %>
+    <%= render partial: "pools", locals: {database: @database, pools: @pools} %>
+  <% end %>
 <% end %>

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

@@ -0,0 +1,6 @@
+<%= render partial: "menu", locals: {database: @database} %>
+<%= monitoring_panel do %>
+  <% if @servers %>
+    <%= render partial: "servers", locals: {database: @database, servers: @servers} %>
+  <% end %>
+<% end %>

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

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

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

@@ -1,4 +1,6 @@
 <%= render partial: "menu", locals: {database: @database} %>
-<% if @stats %>
-  <%= render partial: "stats", locals: {database: @database, stats: @stats} %>
+<%= monitoring_panel do %>
+  <% if @stats %>
+    <%= render partial: "stats", locals: {database: @database, stats: @stats} %>
+  <% end %>
 <% end %>

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

@@ -0,0 +1,6 @@
+<%= render partial: "menu", locals: {database: @database} %>
+<%= monitoring_panel do %>
+  <% if @users %>
+    <%= render partial: "users", locals: {database: @database, users: @users} %>
+  <% end %>
+<% end %>

data/app/views/pg_bouncer_hero/home/_card.html.erb

@@ -1,13 +1,16 @@
-<div class="bg-white rounded-lg border border-gray-200 shadow-sm overflow-hidden">
+<div class="bg-white rounded-lg border border-gray-200 shadow-xs overflow-hidden">
   <%= link_to databases_path(group: database.group.name.parameterize, database: database.name.parameterize), class: "block no-underline text-inherit" do %>
     <div class="px-4 py-3 flex items-center justify-between border-b border-gray-100">
       <div>
         <div class="text-base font-bold text-gray-900"><%= database.name %></div>
         <div class="text-xs text-gray-500"><%= database.host %></div>
       </div>
+      <% if database.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>
+      <% end %>
     </div>
   <% end %>
-  <turbo-frame id="card_<%= database.group.name.parameterize %>_<%= database.name.parameterize %>" src="<%= summary_path(group: database.group.name.parameterize, database: database.name.parameterize) %>" loading="lazy">
+  <turbo-frame id="card_<%= database.group.name.parameterize %>_<%= database.name.parameterize %>" src="<%= summary_path(group: database.group.name.parameterize, database: database.name.parameterize) %>">
     <%= render partial: "card_loading_content" %>
   </turbo-frame>
 </div>

data/app/views/pg_bouncer_hero/home/_card_content.html.erb

@@ -1,43 +1,60 @@
 <% if database.connection %>
   <% summary = database.summary %>
-  <div class="px-4 py-3 flex items-start gap-6">
-    <div class="space-y-1 text-sm text-gray-700">
-      <div>
-        <% number = summary.select { |row| row["list"] == "users" }.first["items"] %>
-        <%= pluralize(number, "user") %>
-      </div>
-      <div>
-        <% number = summary.select { |row| row["list"] == "databases" }.first["items"].to_i - 1 %>
-        <%= pluralize(number, "database") %>
-      </div>
-      <div>
-        <% number = summary.select { |row| row["list"] == "pools" }.first["items"].to_i - 1 %>
-        <%= pluralize(number, "pool") %>
+  <% health = fleet_health(summary) %>
+  <div data-fleet-health data-status="<%= health[:status] %>" data-severity="<%= health[:severity] %>" data-waiting-clients="<%= health[:waiting_clients] %>" data-high-utilization="<%= health[:max_utilization] >= 80 %>">
+    <div class="px-4 py-3 flex items-start gap-6">
+      <div class="space-y-1 text-sm text-gray-700">
+        <div>
+          <% number = summary.select { |row| row["list"] == "users" }.first["items"] %>
+          <%= pluralize(number, "user") %>
+        </div>
+        <div>
+          <% number = summary.select { |row| row["list"] == "databases" }.first["items"].to_i - 1 %>
+          <%= pluralize(number, "database") %>
+        </div>
+        <div>
+          <% number = summary.select { |row| row["list"] == "pools" }.first["items"].to_i - 1 %>
+          <%= pluralize(number, "pool") %>
+        </div>
+        <div>
+          <% if health[:waiting_clients].positive? %>
+            <span class="inline-flex items-center rounded-md bg-yellow-50 px-2 py-1 text-xs font-medium text-yellow-800 ring-1 ring-yellow-200 ring-inset"><%= pluralize(health[:waiting_clients], "waiting client") %></span>
+          <% else %>
+            <span class="text-xs text-gray-400">No clients waiting</span>
+          <% end %>
+        </div>
       </div>
-    </div>
-    <div class="flex-1 space-y-2">
-      <% summary.select { |row| row.key?(:databases_details) }.first[:databases_details].each do |db| %>
-        <div class="flex items-center gap-2 text-sm">
-          <span class="font-medium text-gray-900 w-24 truncate"><%= db["name"] %></span>
-          <div class="flex-1">
-            <% current = db["current_connections"].to_i %>
-            <% max = db["max_connections"].to_i %>
-            <% pct = max > 0 ? (current.to_f / max * 100).round : 0 %>
-            <div class="w-full bg-gray-200 rounded-full h-2.5">
-              <div class="bg-green-500 h-2.5 rounded-full" style="width: <%= pct %>%"></div>
+      <div class="flex-1 space-y-2">
+        <% summary.select { |row| row.key?(:databases_details) }.first[:databases_details].each do |db| %>
+          <div class="flex items-center gap-2 text-sm">
+            <span class="font-medium text-gray-900 w-24 truncate"><%= db["name"] %></span>
+            <div class="flex-1">
+              <% current = db["current_connections"].to_i %>
+              <% max = db["max_connections"].to_i %>
+              <% pct = max > 0 ? (current.to_f / max * 100).round : 0 %>
+              <div class="w-full bg-gray-200 rounded-full h-2.5">
+                <div class="<%= pct >= 80 ? "bg-amber-500" : "bg-green-500" %> h-2.5 rounded-full" style="width: <%= [pct, 100].min %>%"></div>
+              </div>
+              <div class="text-xs text-gray-500 mt-0.5"><%= current %> / <%= max %> connections</div>
             </div>
-            <div class="text-xs text-gray-500 mt-0.5"><%= current %> / <%= max %> connections</div>
           </div>
-        </div>
+        <% end %>
+      </div>
+    </div>
+    <div class="px-4 py-2 border-t border-gray-100 flex items-center justify-between">
+      <% if health[:waiting_clients].positive? %>
+        <span class="inline-flex items-center rounded-md bg-yellow-50 px-2 py-1 text-xs font-medium text-yellow-800 ring-1 ring-yellow-200 ring-inset"><%= pluralize(health[:waiting_clients], "client") %> waiting</span>
+      <% elsif health[:max_utilization] >= 80 %>
+        <span class="inline-flex items-center rounded-md bg-amber-50 px-2 py-1 text-xs font-medium text-amber-800 ring-1 ring-amber-300 ring-inset"><%= health[:max_utilization] %>% utilized</span>
+      <% else %>
+        <span class="inline-flex items-center rounded-md bg-green-50 px-2 py-1 text-xs font-medium text-green-700 ring-1 ring-green-600/20 ring-inset">Healthy</span>
       <% end %>
+      <span class="text-xs text-gray-400">Last refresh: <%= Time.now.strftime("%H:%M:%S %Z") %></span>
     </div>
   </div>
-  <div class="px-4 py-2 border-t border-gray-100 flex items-center justify-between">
-    <span class="inline-flex items-center rounded-md bg-green-50 px-2 py-1 text-xs font-medium text-green-700 ring-1 ring-green-600/20 ring-inset">Online</span>
-    <span class="text-xs text-gray-400">Last refresh: <%= Time.now.strftime("%H:%M:%S %Z") %></span>
-  </div>
 <% else %>
-  <div class="px-4 py-6 text-center">
+  <% health = fleet_health(nil) %>
+  <div class="px-4 py-6 text-center" data-fleet-health data-status="<%= health[:status] %>" data-severity="<%= health[:severity] %>" data-waiting-clients="0" data-high-utilization="false">
     <span class="inline-flex items-center rounded-md bg-red-50 px-2 py-1 text-xs font-medium text-red-700 ring-1 ring-red-600/20 ring-inset">Offline</span>
   </div>
 <% end %>

data/app/views/pg_bouncer_hero/home/index.html.erb

@@ -1,18 +1,38 @@
-<div class="bg-white rounded-lg border border-gray-200 shadow-sm mb-6">
-  <div class="px-4 py-3 border-b border-gray-200">
-    <h2 class="text-lg font-semibold text-gray-900">Overview</h2>
+<div data-controller="fleet polling" data-polling-interval-value="60000" data-fleet-total-value="<%= @groups.values.sum { |group| group.databases.size } %>" data-action="turbo:frame-load->fleet#refresh turbo:frame-load->polling#refreshed">
+  <div class="bg-white rounded-lg border border-gray-200 shadow-xs mb-6">
+    <div class="px-4 py-3 border-b border-gray-200 flex flex-wrap items-center justify-between gap-2">
+      <div>
+        <h2 class="text-lg font-semibold text-gray-900">Fleet health</h2>
+        <p class="text-sm text-gray-500" data-fleet-target="headline" aria-live="polite">Checking <%= pluralize(@groups.values.sum { |group| group.databases.size }, "instance") %>…</p>
+      </div>
+      <span class="text-xs text-gray-400" data-polling-target="status">Loading current status…</span>
+    </div>
+    <div class="grid grid-cols-1 sm:grid-cols-3 divide-y sm:divide-y-0 sm:divide-x divide-gray-200">
+      <div class="px-4 py-3">
+        <div class="text-xs font-medium uppercase tracking-wider text-gray-500">Offline</div>
+        <div class="text-xl font-semibold text-red-700" data-fleet-target="offline">—</div>
+      </div>
+      <div class="px-4 py-3">
+        <div class="text-xs font-medium uppercase tracking-wider text-gray-500">Waiting clients</div>
+        <div class="text-xl font-semibold text-yellow-800" data-fleet-target="waiting">—</div>
+      </div>
+      <div class="px-4 py-3">
+        <div class="text-xs font-medium uppercase tracking-wider text-gray-500">High utilization</div>
+        <div class="text-xl font-semibold text-amber-800" data-fleet-target="utilization">—</div>
+      </div>
+    </div>
   </div>
-</div>
 
-<div data-controller="polling" data-polling-interval-value="60000">
   <% @groups.each do |_, group| %>
     <div class="mb-8">
       <h3 class="text-xl font-semibold text-gray-900 mb-4 pb-2 border-b border-gray-200">
         <%= group.name %>
       </h3>
-      <div class="grid grid-cols-1 md:grid-cols-2 gap-4">
-        <% group.databases.each do |database| %>
-          <%= render partial: "card", locals: { database: database } %>
+      <div class="grid grid-cols-1 md:grid-cols-2 gap-4" data-fleet-target="group">
+        <% group.databases.each_with_index do |database, index| %>
+          <div data-fleet-target="item" data-fleet-original-index="<%= index %>">
+            <%= render partial: "card", locals: { database: database } %>
+          </div>
         <% end %>
       </div>
     </div>

data/app/views/shared/_data_table_toolbar.html.erb

@@ -0,0 +1,13 @@
+<div class="flex items-start gap-3 flex-wrap">
+  <label class="sr-only" for="<%= table_id %>_search">Search <%= title.downcase %></label>
+  <input id="<%= table_id %>_search" type="search" placeholder="Search <%= title.downcase %>…" class="w-56 rounded-md border border-gray-300 bg-white px-3 py-1.5 text-sm text-gray-700" data-data-table-target="query" data-action="input->data-table#filter">
+  <details class="relative text-sm text-gray-700">
+    <summary class="cursor-pointer rounded-md border border-gray-300 bg-white px-3 py-1.5 font-medium">Columns</summary>
+    <div class="absolute right-0 z-20 mt-2 w-max min-w-64 rounded-md border border-gray-200 bg-white p-3 text-xs shadow-lg">
+      <div class="grid grid-cols-2 gap-x-4 gap-y-2" data-data-table-target="columnMenu"></div>
+      <button type="button" class="mt-3 w-full border-t border-gray-200 pt-2 text-left font-medium text-gray-600 hover:text-gray-900" data-action="data-table#resetColumns">Reset columns</button>
+    </div>
+  </details>
+  <span class="py-1.5 text-xs text-gray-500" data-data-table-target="status"><%= row_count %> rows</span>
+</div>
+<p class="mt-3 text-sm text-gray-500" data-data-table-target="empty" hidden>No rows match this search.</p>

data/config/routes.rb

@@ -1,15 +1,29 @@
 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 :servers, controller: :database
+      get :users, controller: :database
       get :conf, controller: :database
+      get :state, controller: :database
       post :reload, controller: :database
       post :suspend, controller: :database
+      post :resume, controller: :database
+      post :pause_database, controller: :database
+      post :reconnect_database, controller: :database
+      post :wait_close_database, controller: :database
+      post :resume_database, controller: :database
       post :shutdown, controller: :database
     end
   end

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

@@ -3,6 +3,9 @@ pgbouncers:
     primary:
       # eg. postgres://user:password@host:port/pgbouncer
       # url: <%%= ENV["PGBOUNCER_PRODUCTION_PRIMARY_DATABASE_URL"] %>
+      # pool_size: 5
+      # pool_timeout: 5
+      # read_only: true
     # Add more databases
     # replica:
     #   url: <%%= ENV["PGBOUNCER_PRODUCTION_REPLICA_DATABASE_URL"] %>
@@ -14,3 +17,7 @@ pgbouncers:
 
 # Time zone (defaults to app time zone)
 # time_zone: "Pacific Time (US & Canada)"
+
+# Hide and reject administrative commands for every PgBouncer unless an
+# individual PgBouncer sets read_only explicitly
+# 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
@@ -35,12 +65,36 @@ module PgBouncerHero
       @url.password if @url
     end
 
+    def read_only?
+      PgBouncerHero.read_only_for?(self)
+    end
+
     def dbname
       @url.path[1..-1] if @url
     end
 
     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 +104,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,42 +1,118 @@
 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
           d = databases
+          p = pools
           l = l.as_json
           d = d.as_json.reject { |a| a["name"] == "pgbouncer" }
+          p = p.as_json
           l.push({ databases_details: d })
+          l.push({ pools_details: p })
           l
         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 servers
+        execute("SHOW servers")
+      end
+      def users
+        execute("SHOW users")
       end
       def conf
-        connection.exec("SHOW config")
+        execute("SHOW config")
+      end
+      def state
+        execute("SHOW state")
       end
       def reload
-        connection.exec("RELOAD")
+        instrument_admin_command(:reload) { execute("RELOAD") }
       end
       def suspend
-        connection.exec("SUSPEND")
+        instrument_admin_command(:suspend) { execute("SUSPEND") }
+      end
+      def pause(database_name)
+        execute_database_command(:pause, "PAUSE", database_name)
+      end
+      def reconnect(database_name)
+        execute_database_command(:reconnect, "RECONNECT", database_name)
+      end
+      def wait_close(database_name)
+        execute_database_command(:wait_close, "WAIT_CLOSE", database_name)
       end
-      def shutdown
-        connection.exec("SHUTDOWN")
+      def resume(database_name = nil)
+        return instrument_admin_command(:resume) { execute("RESUME") } if database_name.nil?
+
+        execute_database_command(:resume, "RESUME", database_name)
+      end
+      def shutdown(mode = nil)
+        instrument_admin_command(:shutdown, mode: mode || :immediate) do
+          suffix = SHUTDOWN_MODES.fetch(mode)
+          execute("SHUTDOWN#{suffix}")
+        rescue KeyError
+          raise ArgumentError, "unsupported shutdown mode: #{mode.inspect}"
+        end
+      end
+
+      private
+
+      def execute_database_command(action, command, database_name)
+        name = database_name.to_s
+        instrument_admin_command(action, target_database: name) do
+          raise ArgumentError, "database name must not be empty" if name.empty?
+
+          execute("#{command} #{PG::Connection.quote_ident(name)}")
+        end
+      end
+
+      def instrument_admin_command(action, target_database: nil, **attributes)
+        payload = {
+          group: group.name,
+          database: name,
+          action: action,
+          target_database: target_database,
+          **attributes
+        }
+
+        error = nil
+        result = ActiveSupport::Notifications.instrument(PgBouncerHero::ADMIN_COMMAND_EVENT, payload) do
+          begin
+            command_result = yield
+            payload[:outcome] = command_result.nil? ? :unavailable : :success
+            command_result
+          rescue StandardError => command_error
+            error = command_error
+            payload[:outcome] = :error
+            payload[:error_class] = command_error.class.name
+            nil
+          end
+        end
+        raise error if error
+
+        result
       end
     end
   end

data/lib/pgbouncerhero/version.rb

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