Local development with Docker

DBGorilla can watch the Postgres running on your own machine, the database you develop against. It takes one command.

This is the short path. For RDS, Aurora, or anything not on your machine, see AWS RDS and Aurora.

Before you start

• Docker running. Not just installed: the CLI checks that the engine responds.
• Postgres running locally, and the port it listens on.
• A database user for DBGorilla, and its password. A plain read-only login is not enough; see Grant the right permissions below.
• Signed in. dbgorilla whoami should print your email. If not, see CLI Install and Setup.
• A deployment that supports collectors. Check with dbgorilla collector list. If it returns this deployment does not support the managed collector, nothing below will work against it.

Grant the right permissions

Create the user with the permissions the collector actually needs. pg_monitor alone is not enough: with only that grant the collector connects and reports metrics, but captures no schema, and nothing surfaces an error.

CREATE ROLE dbg_readonly LOGIN PASSWORD 'choose-a-password';
GRANT pg_monitor TO dbg_readonly;                          -- cluster-wide stats
GRANT USAGE ON SCHEMA public TO dbg_readonly;              -- per schema you want captured
GRANT SELECT ON ALL TABLES IN SCHEMA public TO dbg_readonly;
ALTER DEFAULT PRIVILEGES IN SCHEMA public
  GRANT SELECT ON TABLES TO dbg_readonly;                  -- tables created later

pg_monitor covers the stats views the metrics pipeline reads, but grants nothing on your tables, and schema capture shells out to pg_dump, which has to SELECT every table it dumps. A role with only pg_monitor connects and reports metrics fine, then fails every schema pass with permission denied for table …, logged as a warning that retries forever, so the collector looks healthy while capturing no schema at all.

Repeat the last three statements for every schema and database you want captured.

Connect it

dbgorilla collector install \
  --target docker \
  --name "local dev postgres" \
  --db-host localhost \
  --db-port 5432 \
  --db-user dbg_readonly \
  --ssl-mode disable

Leave --db-password off and the CLI prompts for it without echoing.

Leave --db-name off and it watches every database on the server.

Add --dry-run to see what would happen. It contacts nothing, writes nothing and starts nothing; it prints the config it would render and the docker run command it would use.

Why --ssl-mode disable

A stock local Postgres ships with TLS off, and the CLI defaults to verify-full. Without this flag the connection check fails before anything is installed.

Use disable for a database on your own machine only. Anything reachable from elsewhere wants verify-full.

If the check reports pg_stat_statements is not loaded

Install stops there. pg_stat_statements powers query performance data (see pg_stat_statements), and it has to be loaded at server start:

ALTER SYSTEM SET shared_preload_libraries = 'pg_stat_statements';

Then restart Postgres (a reload is not enough for this setting) and run the install again.

What it handles for you

Docker networking. The collector runs in a container, so localhost there means the container, not your machine. The CLI rewrites localhost to host.docker.internal and tells you it did. You type the address you already know.

Your password stays out of the config file. The generated collector.toml holds a ${COLLECTOR_DB_PASSWORD} reference. The value goes to a separate file at mode 0600 and reaches the container through Docker’s --env-file, never on a command line where ps would show it.

It will not clobber an existing collector. If one is already installed the command stops and says so.

Check on it

dbgorilla collector status
dbgorilla collector logs -f

The container is named dbg-collector, so docker ps and docker logs dbg-collector work too.

Read the Deploy: and Connection: lines rather than the exit code. collector status exits 0 even when it cannot reach anything.

Check what it will collect

Query analysis, meaning the collector running EXPLAIN and sample queries for you, is configured separately from the connection. Run the install with --dry-run and read the [commands] block in the rendered config. That is the authoritative answer for your setup.

Stopping and removing

dbgorilla collector stop        # pause, keeping its identity
dbgorilla collector start       # resume
dbgorilla collector uninstall   # remove and deprovision its identity

stop is reversible. uninstall is not: it discards the collector’s identity on the server, and reinstalling gives you a new collector rather than the same one back.

One exception. If you are signed out, uninstall cannot reach the server, so it removes the local container and leaves the identity and local state in place, then tells you to sign in and run it again. Nothing is orphaned, and the destructive half has not happened yet.

If install says a collector already exists, run dbgorilla collector status first. The error suggests uninstall, but that destroys a working collector to solve a problem you may not have.