PostgreSQL Setup

Basira requires a dedicated database user with read access to PostgreSQL performance views. pg_stat_statements is required for query-level telemetry. auto_explain is optional and only needed for log-derived plan capture.

1. Create Monitoring User

Connect to your PostgreSQL instance as a superuser and run:

CREATE USER basira_monitor WITH PASSWORD 'your-secure-password';
GRANT pg_monitor TO basira_monitor;
GRANT pg_read_all_stats TO basira_monitor;
GRANT CONNECT ON DATABASE your_database TO basira_monitor;

These two roles together give the agent the minimum permissions it needs:

• pg_monitor (PostgreSQL 10+) — read access to pg_stat_activity, pg_locks, pg_stat_replication, pg_stat_bgwriter, pg_stat_wal, pg_stat_io, pg_settings, and other system views
• pg_read_all_stats — required for pg_stat_statements (not included in pg_monitor)

A full setup script is available at scripts/create-pg-monitor-user.sql.

2. Enable pg_stat_statements

pg_stat_statements tracks query execution statistics. Add it to your postgresql.conf:

shared_preload_libraries = 'pg_stat_statements'
pg_stat_statements.track = all
pg_stat_statements.max = 10000

Then restart PostgreSQL and create the extension:

CREATE EXTENSION IF NOT EXISTS pg_stat_statements;

Verify

SELECT count(*) FROM pg_stat_statements;

3. Optional: Enable auto_explain

auto_explain lets Basira ingest slow query plans from PostgreSQL logs. If you only want query stats, active sessions, table stats, wait events, WAL stats, and I/O stats, you can skip this step.

If you want log-derived plans, add this to postgresql.conf:

shared_preload_libraries = 'pg_stat_statements,auto_explain'
auto_explain.log_min_duration = 100   # log queries slower than 100ms
auto_explain.log_analyze = on
auto_explain.log_format = json
auto_explain.log_nested_statements = on

Restart PostgreSQL after making changes.

Verify

Run a slow query and check the PostgreSQL logs for auto_explain output.

4. Version Notes

Basira collects more telemetry when the server exposes it:

• PostgreSQL 14+: pg_stat_wal
• PostgreSQL 16+: pg_stat_io
• PostgreSQL 17+: checkpoint stats via pg_stat_checkpointer + pg_stat_bgwriter

5. Network Access

Ensure the Basira agent can reach your PostgreSQL instance:

• Direct connection: Allow the agent's IP in pg_hba.conf
• Cloud providers: Add the agent's security group/VPC to your database's allowed connections
• SSL: We recommend sslmode=require at minimum

⚠ Do not use cluster or load-balancer endpoints as the agent DSN. Aurora cluster endpoints, pgBouncer pools, and similar proxies can route connections to different physical instances between polls. This breaks pg_stat_statements deltas, mixes active-query snapshots across nodes, and produces inconsistent telemetry. Always connect to a specific instance endpoint — the primary writer, or a named read replica.

Next Steps

Once your database is configured, install the Basira agent and point it at your PostgreSQL instance.