[receiver/postgresql]: Add connect_database config option

[spathlavath]

Description

• Adds a connect_database config option to receiver/postgresqlreceiver
• Controls which database the receiver connects to for cluster-wide queries (database discovery, pg_stat_statements, bgwriter/WAL/replication stats, query samples, top query)
• Defaults to postgres, so existing configs are unaffected
• Independent of databases (the reporting scope) - pg_stat_statements is tracked cluster-wide, so the connection target doesn't need to match what's being monitored
• Useful when pg_stat_statements is installed in a database other than postgres, or when connecting through a dedicated monitoring-only database

Link to tracking issue

Fixes #50920

Testing

• Added unit tests: default fallback to postgres, using a configured value, and connect_database outside databases producing no validation error
• Manually verified against a local Postgres instance with pg_stat_statements installed only in a non-default database - confirmed the existing default behavior still fails the same way, and the new option fixes it

Documentation

• Updated README.md with the new option and a config example

Authorship

• I, a human, wrote this pull request description myself.

[opentelemetry-pr-dashboard]

Pull request dashboard status

Waiting on the author · refreshed 2026-09-11 12:30 UTC

Wait for the required status checks to report; this pull request moves to reviewers once the results are clean.

Status above doesn't look right?

• Just replied or pushed? Anything around or after the refresh time above may not be picked up yet — give it a few minutes.
• Should this be with reviewers? Comment /dashboard route:reviewers to route it to them.
• Anything wrong — including the routing? Report it with what you expected; it helps us improve the dashboard.

[spathlavath]

/dashboard route:reviewers

[akgrover]

@spathlavath I might be missing something. Can you help understand what value does this add when there is support for auto-discovery already.

[spathlavath]

@spathlavath I might be missing something. Can you help understand what value does this add when there is support for auto-discovery already.

@akgrover Auto-discovery and this option solve different problems.

Auto-discovery (databases: []) decides which databases get metrics reported for them. connect_database decides which single database the receiver dials into to run its cluster-wide queries, like pg_stat_statements. Right now that's hardcoded to postgres.

The problem is pg_stat_statements is tracked cluster-wide in shared memory, but the SQL view for it only exists in whichever database ran CREATE EXTENSION. We had a customer who instrumented this receiver against their Postgres instance, but their environment never touches the postgres database at all - everything runs against their own application database, so the extension only exists there. Auto-discovery works fine and lists all their databases correctly, but the very first query still fails with relation "pg_stat_statements" does not exist, because it's hardcoded to connect to postgres first.

Since the stats are cluster-wide and the view carries a dbid column, connecting to any database with the extension installed still gives correct per-database attribution for everything in databases. So this doesn't touch discovery or reporting at all - databases and exclude_databases behave exactly as before. It just makes the one connection target configurable, independent of the reporting scope, which also covers the dedicated-monitoring-database pattern some setups use.

Please go through #50920 for more details.