ankane/pghero · error · PgHero::Error

pg_query required for filter_data

Error message

pg_query required for filter_data

What it means

PgHero's filter_data feature (masking sensitive data in query text) needs the pg_query gem to parse SQL. When filter_data resolves to truthy - via the database's config key, the global PgHero config, or ENV["PGHERO_FILTER_DATA"] - Database#filter_data attempts require "pg_query"; if the gem is not in the bundle it raises Error "pg_query required for filter_data".

Source

Thrown at lib/pghero/database.rb:110

    end

    # must check keys for booleans
    def filter_data
      unless defined?(@filter_data)
        @filter_data =
          if config.key?("filter_data")
            config["filter_data"]
          elsif PgHero.config.key?("filter_data")
            PgHero.config.key?("filter_data")
          else
            PgHero.filter_data
          end

        if @filter_data
          begin
            require "pg_query"
          rescue LoadError
            raise Error, "pg_query required for filter_data"
          end
        end
      end

      @filter_data
    end

    private

    # check adapter lazily
    def connection_model
      unless @adapter_checked
        # rough check for Postgres adapter
        # keep this message generic so it's useful
        # when empty url set in Docker image pghero.yml
        unless @connection_model.connection_db_config.adapter.to_s.match?(/postg/i)
          raise Error, "Invalid connection URL"
        end

View on GitHub (pinned to 7edb57986f)

Solutions

1. Add gem "pg_query" to the Gemfile and run bundle install
2. If you do not actually need data filtering, remove the filter_data key from pghero.yml and unset PGHERO_FILTER_DATA
3. Verify with Gem.loaded_specs.key?("pg_query") in the environment where the error occurs

Example fix

# Gemfile - before
gem "pghero"

# Gemfile - after
gem "pghero"
gem "pg_query"
# then run: bundle install

# fail fast at boot when the feature is on but the gem is absent
if PgHero.filter_data && !Gem.loaded_specs.key?("pg_query")
  raise "filter_data is enabled but the pg_query gem is not in the bundle"
end

begin
  PgHero.database.filter_data
rescue PgHero::Error => e
  # degrade gracefully: disable filtering rather than breaking the dashboard
  Rails.logger.warn("#{e.message} - disabling filter_data")
  retry_without_filter_data
end

When it happens

Trigger: Setting filter_data: true in config/pghero.yml (per-database or top level) without gem "pg_query" in the Gemfile; setting the PGHERO_FILTER_DATA environment variable (e.g. in Docker/k8s) in an app whose bundle lacks pg_query.

Common situations: Enabling data filtering after reading the security docs but skipping the gem step; environment variables copied from another deployment that did include the gem; CI environments built from a reduced Gemfile.

Related errors

• Unknown format
• Invalid sort
• Invalid config file
• Invalid connection URL
• Spec not found: #{config["spec"]}

AI-assisted analysis of ankane/pghero@7edb57986f (2026-08-21). Data as JSON: /api/errors/d9d109809e5daaa3. Report an issue: GitHub.