# rails-pg-extras: PostgreSQL diagnostics for a Rails application

> rails-pg-extras is a Ruby port of Heroku's PG Extras that exposes PostgreSQL metadata, lock information, index usage, cache hit ratios and vacuum statistics as rake tasks, Ruby methods and an optional web dashboard. It suits a Rails developer chasing a slow query who needs the server's view of what is happening, not another query in the console.

**pawurb/rails-pg-extras** — Rails PostgreSQL database performance insights. Locks, index usage, buffer cache hit ratios, vacuum stats and more.

- Repository: https://github.com/pawurb/rails-pg-extras
- Stars: 1,249 · Forks: 39
- Language: Ruby
- License: MIT
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/pawurb-rails-pg-extras

## What it is and where it came from

rails-pg-extras is a Rails port of Heroku PG Extras with several additions and improvements, and the goal is stated precisely: to provide powerful insights into the PostgreSQL database for Ruby on Rails applications that are not using the Heroku PostgreSQL plugin. That framing matters, because PG Extras is a set of diagnostic SQL queries that Heroku exposes for its managed Postgres customers and that nobody else can easily get. The primary language is Ruby, the licence is MIT, the last push was on 2026-06-16, and the repository has no GitHub releases, so the gem version on rubygems is the artefact to track. The included rake tasks and Ruby methods obtain information about a Postgres instance that may be useful when analysing performance issues, covering locks, index usage, buffer cache hit ratios and vacuum statistics, and the Ruby API is what lets you integrate the tool into automatic monitoring tasks.

## The extensions it needs, and how to check them

Some of the reports depend on PostgreSQL extensions that are not installed by default, and the README is clear about which. The `calls` and `outliers` queries require the pg_stat_statements extension, and you can check whether it is enabled with a Ruby call:

```ruby
RailsPgExtras.extensions
```

which should show a line like the one the documentation gives, with the extension name, a version and a description. The `ssl_used` report requires the sslinfo extension, and the buffercache_usage queries need pg_buffercache. You can enable them all in one call:

```ruby
RailsPgExtras.add_extensions
```

The distinction here is worth understanding rather than just following. pg_stat_statements is a performance counter that has to be switched on at the server level before it records anything, so a database that has never had it enabled will return an empty result rather than an error. That is the failure mode that wastes an afternoon, because an empty table looks like a healthy database with no slow queries rather than a database that is not telling you anything.

## Rake tasks, Ruby methods, and four output formats

Every command works as a rake task or directly from Ruby, and the two forms take the same options. The rake form is `rake pg_extras:cache_hit` and the Ruby form is `RailsPgExtras.cache_hit`, and the default output is an ASCII table showing the index and table hit rate. You can change the format with the `in_format` parameter, and the options are `:display_table`, `:hash`, `:array` and `:raw`. The last one is worth noting because it is the escape hatch, since it returns the underlying PG::Result object, which means you can reach the rows yourself for anything the formatter does not give you. Some methods also accept an `args` param for customising the query, for example `RailsPgExtras.long_running_queries(args: { threshold: "200 milliseconds" })`, and by default the queries target the `public` schema, which you can change with the `schema` argument or by setting the `PG_EXTRAS_SCHEMA` environment variable.

## The diagnose report as a starting point

The README calls `diagnose` the simplest way to start using pg-extras, because it runs a set of checks and prints a report highlighting areas that may require additional investigation:

```ruby
RailsPgExtras.diagnose

$ rake pg_extras:diagnose
```

That framing is honest about what the library is. It is not an automatic fix, it is a report that points at the places worth looking at, and the documentation then says to keep reading to learn about the methods that `diagnose` uses under the hood. The order of the documentation is therefore the intended workflow. Run the report, see which check flagged something, then go and use the specific query for that area. A tool that dumped every metric at once would produce a wall of numbers, and the diagnostic report is the thing that narrows the wall down to one line worth investigating.

## The web interface, and the authentication default

There is an optional visual interface, enabled by mounting a Rails engine in `config/routes.rb`:

```ruby
  mount RailsPgExtras::Web::Engine, at: 'pg_extras'
```

and the security defaults are the part to read carefully. HTTP basic auth can be enabled by specifying `Rails.application.credentials.pg_extras.user` or the `RAILS_PG_EXTRAS_USER` environment variable, and the password likewise. Authentication is mandatory unless you set `RAILS_PG_EXTRAS_PUBLIC_DASHBOARD=true` or call `RailsPgExtras.configuration.public_dashboard = true`. That is the right default, since a dashboard that exposes lock information and long-running queries to anyone who finds the path is a genuine information leak about your database. The available web actions can be narrowed in an initializer, and the README is explicit that not all of them are enabled by default, with `kill_all` named as an example of a dangerous one you might want:

```ruby
RailsPgExtras.configure do |config|
  config.enabled_web_actions = %i[kill_all pg_stat_statements_reset add_extensions]
end
```

Note that the list in the example is the set you opt into, and the safe default is the smaller one.

## Multiple databases, and connecting somewhere else entirely

By default the gem uses the application's default `ActiveRecord::Base.connection`, typically the `primary` one, for running the metadata queries, the rake tasks and the web UI. For a Rails application with multiple databases the web UI can switch connections dynamically, reading the available database names from `ActiveRecord::Base.configurations` for the current environment and selecting one through the `db_key` query parameter, with the example paths given as `/pg_extras?db_key=primary` and `/pg_extras?db_key=animals`. The parameter is thread-local per request, so it is described as safe under concurrency. To reach a database that is not in `database.yml`, which is also the case when using the rake tasks or the Ruby API outside the web UI, you can provide an explicit URL through the `RAILS_PG_EXTRAS_DATABASE_CONFIG` environment variable, or assign it directly with a method call, and the assignment also accepts the symbol `:rails_pg_extras`.

## The wider family, and the MCP interface

The project is one member of a family with the same core idea in different languages, and the README lists the alternatives. The core dependency is a Ruby version, then there are Rust, NodeJS and Elixir versions, a Python Flask version from a different author, and a Haskell version. The reason to have the family rather than one gem is that the diagnostic queries are the portable part and the wiring into each framework is not, so the same query set serves a Rails application, a Flask application and an Elixir application. Separately, there is a rails-pg-extras-mcp gem providing an MCP, Model Context Protocol, interface, which enables PostgreSQL metadata and performance analysis with LLM support. That is a notable direction for a diagnostics tool, since the output of these reports is exactly the kind of thing a language model can interpret and summarise, and the gem is shipped separately from the main project.

## Conclusion

Adopt rails-pg-extras if you self-host Postgres behind Rails and want the diagnostic queries that Heroku's add-on provides, as rake tasks, Ruby methods and a web dashboard. Skip it if your Postgres is a Heroku or managed instance where the add-on already provides these views. Before you rely on the `calls` and `outliers` reports, enable pg_stat_statements with `RailsPgExtras.add_extensions`, and if you enable the web UI, remember that authentication is mandatory unless you explicitly set `RAILS_PG_EXTRAS_PUBLIC_DASHBOARD=true`, and that dangerous actions such as `kill_all` are disabled by default.

## FAQ

### What is rails-pg-extras?

A Rails port of Heroku PG Extras with several additions and improvements, providing insights into PostgreSQL for Ruby on Rails applications that are not using the Heroku PostgreSQL plugin. It covers locks, index usage, buffer cache hit ratios and vacuum statistics through rake tasks, Ruby methods and an optional web interface.

### Which PostgreSQL extensions does rails-pg-extras need?

The calls and outliers queries need pg_stat_statements, ssl_used needs sslinfo, and the buffercache_usage queries need pg_buffercache. You can enable them all with `RailsPgExtras.add_extensions` and check what is installed with `RailsPgExtras.extensions`.

### How do I add the rails-pg-extras web interface?

Mount the engine in config/routes.rb with `mount RailsPgExtras::Engine, at: 'pg_extras'`. HTTP basic auth is mandatory unless you set RAILS_PG_EXTRAS_PUBLIC_DASHBOARD=true, and you can narrow the available web actions in an initializer with config.enabled_web_actions, since dangerous ones such as kill_all are off by default.

### Can rails-pg-extras query more than one database?

Yes. The web UI reads the available database names from ActiveRecord::Base.configurations and selects one through the db_key query parameter, which is thread-local per request. For the rake tasks and the Ruby API you can set an explicit URL through RAILS_PG_EXTRAS_DATABASE_CONFIG or assign RailsPgExtras.database_config directly.

## Sources

- [Issues](https://github.com/pawurb/rails-pg-extras/issues)
- [License: MIT](https://github.com/pawurb/rails-pg-extras/blob/main/LICENSE)
- [pawurb/rails-pg-extras on GitHub](https://github.com/pawurb/rails-pg-extras)
- [README](https://github.com/pawurb/rails-pg-extras/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/pawurb-rails-pg-extras