Your machine (Docker)

Connect DBGorilla to the Postgres on your own machine, the database you develop against, with one CLI command. The CLI runs the collector for you as a Docker container.

For RDS, Aurora, or anything not on your machine, see AWS RDS and Aurora.

Before you start

• Start Docker. The CLI checks that the engine responds, so being installed is not enough. It runs natively on Apple-silicon Macs.
• Start Postgres locally, and note the port it listens on.
• Create a database user for DBGorilla, and note its password. A plain read-only login is not enough; see Grant the right permissions and Database grants in Prepare PostgreSQL.
• Sign in to the DBGorilla CLI. If you have not, see CLI Install and Setup.
• Check that your deployment supports collectors with dbgorilla collector list. If it returns this deployment does not support the managed collector, nothing below will work against it.

Install

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 checks whether the database accepts TLS, then prints the config it would render and the docker run command it would use. It reports that nothing was provisioned, written or started.

To write the config yourself and run the container by hand, see Self-managed PostgreSQL.

Why --ssl-mode disable

A stock local Postgres ships with TLS off. For --target docker, CLI 0.8.0 already defaults --ssl-mode to disable, so the flag in the command above states the default.

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

If the check reports pg_stat_statements is not loaded

On CLI 0.8.0 the install warns that query-performance data will be unavailable, and installs the collector anyway. pg_stat_statements powers query performance data (see pg_stat_statements), and it has to be loaded at server start:

SHOW shared_preload_libraries;
-- empty: ALTER SYSTEM SET shared_preload_libraries = 'pg_stat_statements';
-- otherwise keep every existing entry, e.g. 'auto_explain,pg_stat_statements'

ALTER SYSTEM SET replaces the whole list, so any library you leave out stops loading.

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

Query plans and statistics are on by default

A Docker install allows explain and collect_statistics.

To choose the commands during installation, pass a flag:

Flag	What the database gets
none	explain and collect_statistics
--enable-commands	all three commands
--commands=explain	the commands you list
--enable-commands=false or --commands=""	none, explain included

The install writes the result to the database’s [[component]] as a commands list. That list overrides [commands]. To change it later, edit the list in the config written by the install and restart the container:

# commands = ["explain", "collect_statistics", "execute_query"]   adds read-only checks
# commands = []                                                    turns them all off
$EDITOR ~/.config/dbgorilla/collector/collector.toml
docker restart dbg-collector

Use --dry-run before installing to print the config it would write. The commands list it prints is the authoritative answer for your setup.

See Database commands for what each command permits, and what stays bounded regardless.

What the install does for you

• It rewrites the address. The collector runs in a container, so localhost there means the container, and your machine is somewhere else. The CLI rewrites localhost to host.docker.internal and tells you it did. You type the address you already know.
• It keeps your password 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 leaves an existing collector alone. If one is already installed, the command stops and says so.

Check it is working

Follow Check on it in Check it is working.

Upgrade

The commands for a running Docker collector are under Stopping and removing in Manage collectors.

Remove

What dbgorilla collector uninstall removes, and what stays on Home afterwards, is under Stopping and removing in Manage collectors.