PgHero: a small read-only Postgres dashboard you can drop in as an image or a gem

A README that matches the project's actual size

The whole README runs to a couple of thousand characters, and the first line is the description: a performance dashboard for Postgres. There is a link to a live instance, a screenshot, a note that PgHero 4.0 was recently released with separate upgrade notes for Docker and Rails, and a line calling the project battle-tested at Instacart. After that it points at two installation guides, thanks two projects for the initial queries, and lists related projects.

That brevity is worth reading as a signal rather than a gap. The repository tree backs it up: `lib/`, `app/`, `config/`, `test/`, `guides/`, `licenses/`, plus a `Rakefile`, a `Gemfile` and `pghero.gemspec`. This is a Ruby gem with a small Sinatra-style or Rack application layered over a set of SQL queries, not a platform with a plugin system. Nothing in the tree suggests a scheduler, an agent, or a background collector, which means the architecture question answers itself: it runs when you look at it.

The project is MIT licensed, in Ruby, on the `master` branch, with five open issues against nearly nine thousand stars. Topics are not set on the repository, which is a small thing, but it does mean search engines get no help from metadata here.

The queries are the product, and their provenance is documented

The Credits section is the most informative paragraph in the README. PgHero credits Craig Kerstiens for the initial queries and Heroku for the pgextras project, with a link to both posts, and credits Bootswatch for the theme. The Heroku post is from May 2013 and Kerstiens's is from January 2013, so the queries that the dashboard runs started life as a public list of Postgres performance questions published by people who ran large databases.

That provenance cuts two ways. On one hand, the queries were written by operators who knew what they were looking at, and they cover exactly the questions a Postgres user asks first: which queries are slow, which tables are missing indexes, what is taking locks, what the cache hit rate is, and which connections are idle in transaction. On the other, a query written in 2013 has to keep working against every supported server version, which limits how clever it can be.

So the honest characterisation is that PgHero is a curated, maintained front end over a known set of diagnostic queries. That is a genuinely useful thing to have, and it is a narrower thing than a performance management system. The Bootswatch credit also tells you the UI is themed from an existing CSS framework rather than designed, which matches what the screenshots show: tables of numbers, not a dashboard product.

Docker or Rails engine, and nothing in between

Installation is the one decision the README forces. PgHero is available as a Docker image and as a Rails engine, and the documentation section links to `guides/Docker.md` and `guides/Rails.md` for each. There is no standalone binary, no package for a generic Ruby web server, and no command line tool.

The Docker route is the one most people will take, because the project is a web app that needs a database connection and nothing else. The Rails engine route exists for teams who already run Rails and want the dashboard inside an existing app rather than as a separate service with its own container. Both paths are documented in the `guides/` directory, and both have an upgrading section anchored on the 4.0 release, which suggests the jump was not entirely painless and the docs were written for people hitting it.

What neither route tells you, because the README does not say, is how PgHero authenticates to your database and to itself. That question matters and it is the first thing to resolve in `guides/Docker.md`, along with which Postgres user the dashboard needs. A read-only role is the sane answer, and a project whose queries only read makes that easy to grant.

No history, no alerts, no index recommendations

The absences are more defining than the features. There is no mention anywhere in the README of time series storage, historical metrics, threshold alerting, or scheduled email. If you deploy PgHero on Tuesday and your queries were slow on Monday, Tuesday's dashboard will not tell you. The tool answers what is happening now, which is a different job from answering what changed.

The same applies to remediation. The related projects list includes Dexter, described as the automatic indexer for Postgres, and that pairing is the clearest statement of scope in the repository: PgHero shows you the missing index, Dexter creates it. If you want an automated suggestion loop rather than a manual one, you run two tools.

The other related projects draw the boundary in the other direction. PgBouncerHero is listed as a dashboard for PgBouncer, which tells you PgHero is aimed at the Postgres server rather than at the connection pooler in front of it. pgsync and pgslice are listed as data sync and partitioning tools, so the ecosystem around the author covers the rest of the operational surface rather than being folded into the dashboard.

Because there is no GitHub releases feed attached to this repository, there is also no tag to pin. Version history is in `CHANGELOG.md` at the root, and the README links to it under History.

Where PgHero sits against paid tooling and heavier alternatives

The honest comparison is against two different kinds of thing: managed Postgres performance services, and other self-hosted dashboards. A managed service keeps history, correlates against fleet-wide data, and gives you alerting; it also needs production database credentials or a proxy in front of them, and it costs money per host. PgHero asks for the same access, keeps it inside your network, keeps no history, and costs nothing but the container.

Against other self-hosted options, the differentiator is not the charts, it is the maintenance burden. Most alternatives to PgHero in this space require a background agent, a metrics database, or a time series store to be useful. PgHero needs a Postgres connection and a web server, because it computes its numbers when you request the page. That is why it still installs in a few minutes on a database you have never profiled before.

The counterargument is real. A dashboard that recomputes on page load does not scale to a busy server, because expensive queries become more expensive as tables grow, and you cannot alert on a number nobody is polling. If your team needs a regression caught at 3am rather than noticed at 9am, PgHero is the wrong shape of tool and no amount of configuration changes that.

Project state, and the reading order for an adopter

The repository is not archived and the last push was on 2026-09-06, so this is not an abandoned project, though there are no GitHub releases published and the README points at `CHANGELOG.md` instead. The MIT licence means you can read the code, modify it, and run it inside a company without a licensing conversation, which is the main practical reason to prefer it over a hosted product.

The reading order is short. Start with `guides/Docker.md` if you are deploying the image, because it covers both the initial setup and the 4.0 upgrade path. Read `guides/Rails.md` only if you want the engine inside an existing Rails app. Then open `CHANGELOG.md` to see how fast things are moving, and skim `config/` in the repository to understand which connection and environment variables the app expects, since the README does not list them.

Finally, look at the Credits links to the original Kerstiens and Heroku posts. They are the actual specification of what this dashboard shows, and reading them tells you in ten minutes which of the panels are fundamentals of Postgres and which were fashionable in 2013. The project is small enough that that is the whole evaluation.

Editorial conclusion

PgHero is the right pick when you run Postgres, want to see slow queries and lock contention within a minute of deploying, and do not want to hand production credentials to a third party for a performance subscription. It is the wrong pick if you need historical trending, alerting on thresholds, or advice on indexes, because the queries it starts from are the ones Craig Kerstiens and the Heroku pgextras project published in 2013 and nothing in the repository suggests they have been substantially rewritten. It is not archived and the last push was on 2026-09-06, with no GitHub releases attached, so read `CHANGELOG.md` for version history and `guides/Docker.md` for the upgrade path from the 4.0 release before you replace a running instance.

Frequently asked questions

Official sources

1. ankane/pghero on GitHub
2. Issues
3. License: MIT
4. README