ankane/pghero · critical · PgHero::Error

Invalid connection URL

Error message

Invalid connection URL

What it means

The first time a PgHero::Database touches its connection, connection_model checks that the resolved ActiveRecord database config's adapter matches /postg/i. Anything else - mysql2, sqlite3, or a blank/default adapter produced by an empty or unparsable url - raises Error "Invalid connection URL". The comment in the source notes the message is deliberately generic because the common case is an empty url in the Docker image's pghero.yml.

Source

Thrown at lib/pghero/database.rb:127

          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
        @adapter_checked = true
      end

      @connection_model
    end

    # just return the model
    # do not start a connection
    def build_connection_model
      url = config["url"]

      # resolve spec
      if !url && config["spec"]
        config_options = {env_name: PgHero.env, name: config["spec"], include_hidden: true}
        resolved = ActiveRecord::Base.configurations.configs_for(**config_options)
        raise Error, "Spec not found: #{config["spec"]}" unless resolved
        url = resolved.configuration_hash

View on GitHub (pinned to 7edb57986f)

Solutions

1. Set a full Postgres URL in config/pghero.yml: url: postgres://user:pass@host:5432/dbname
2. For the Docker image, provide the URL via the PGHERO_DATABASE_URL (or DATABASE_URL) environment variable
3. If using spec:, confirm the matching database.yml entry uses the postgresql adapter in the current RAILS_ENV
4. Test the URL outside pghero, e.g. psql "postgres://user:pass@host:5432/dbname" -c 'select 1'

Example fix

# config/pghero.yml - before
databases:
  primary:
    url: ""

# after
databases:
  primary:
    url: postgres://user:pass@host:5432/dbname

# validate the url shape before pghero tries to connect
url = PgHero.config.dig("databases", "primary", "url").to_s
raise "pghero url must start with postgres:// or postgresql://" unless url.start_with?("postgres://", "postgresql://")

begin
  PgHero.database.connection_model
rescue PgHero::Error => e
  # catch at health-check level: configuration is wrong, retrying will not help
  report_config_error("pghero database connection: #{e.message}")
end

When it happens

Trigger: config/pghero.yml with url: "" or a url missing the postgres:// scheme, so Rails resolves a non-Postgres (default) adapter; a url starting with mysql:// or sqlite:; a spec: entry that resolves to a non-Postgres block in database.yml; running the pghero Docker image without setting PGHERO_DATABASE_URL/DATABASE_URL.

Common situations: Standalone pghero container deployments where the env var is forgotten; migrating an app from MySQL and pghero still pointed at the old url; ERB in pghero.yml evaluating to an empty string in a missing environment.

Related errors

• Invalid config file
• Spec not found: #{config["spec"]}
• Database not found: #{database_id}
• Invalid query hash: #{query_hash}
• pg_query required for filter_data

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