PgBouncerHero

A graphical user interface for your PgBouncers.

Requirements

• Ruby >= 3.2
• Rails >= 7.2
• Propshaft (asset pipeline)
• importmap-rails

Installation

Add to your application's Gemfile:

gem "pgbouncerhero"

And mount the engine in your config/routes.rb:

mount PgBouncerHero::Engine, at: "pgbouncerhero"

Basic Authentication

Set the following variables in your environment or an initializer.

ENV["PGBOUNCERHERO_USERNAME"] = "zelda"
ENV["PGBOUNCERHERO_PASSWORD"] = "triforce"

Devise

authenticate :user, ->(user) { user.admin? } do
  mount PgBouncerHero::Engine, at: "pgbouncerhero"
end

One PgBouncer

export PGBOUNCERHERO_DATABASE_URL=postgres://user:password@host:port/pgbouncer

Multiple PgBouncers

Generate a config file:

rails generate pgbouncerhero:config

Or create config/pgbouncerhero.yml manually:

pgbouncers:
  production:
    primary:
      url: <%= ENV["PGBOUNCER_PRODUCTION_PRIMARY_DATABASE_URL"] %>
    replica:
      url: <%= ENV["PGBOUNCER_PRODUCTION_REPLICA_DATABASE_URL"] %>
  staging:
    primary:
      url: <%= ENV["PGBOUNCER_STAGING_PRIMARY_DATABASE_URL"] %>
    replica:
      url: <%= ENV["PGBOUNCER_STAGING_REPLICA_DATABASE_URL"] %>

Development

Start PostgreSQL and PgBouncer with Docker:

docker compose up -d

Run the dummy Rails app:

PGBOUNCERHERO_DATABASE_URL=postgres://pgbouncer:pgbouncer@localhost:6432/pgbouncer \
  bundle exec rackup test/dummy/config.ru -p 3000

Then open http://localhost:3000/pgbouncerhero.

Run the test suite:

bundle exec rake              # tests + rubocop + herb
bundle exec appraisal rake test  # tests across Rails 7.2, 8.0, 8.1

Stop Docker when done:

docker compose down

Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am "Add some feature")
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

Authors

• Quentin Rousseau

License

Copyright (c) 2025 Quentin Rousseau

MIT License. See LICENSE.txt for details.