AWS RDS and Aurora

A collector is a small process that sits next to your database, reads its statistics, and sends them to DBGorilla. It is what turns DBGorilla from a tool your editor talks to into something that knows about your actual data.

This page covers the two targets the CLI deploys for you:

	Where the collector runs	Use it when
Docker (default)	A container on your machine	The database is local, or reachable from your laptop
AWS	One Fargate task in your own AWS account	The database is RDS or Aurora

The AWS path runs entirely under your own AWS credentials. The CLI reuses whatever aws sso login or AWS_PROFILE already resolves, and nothing sensitive passes through DBGorilla.

Two shorter paths cover common cases:

• The Postgres on your own laptop: Local development with Docker.
• PostgreSQL running in Kubernetes: Kubernetes, which uses the Helm chart. There is no --target kubernetes; the CLI does not deploy into a cluster, and nothing on this page applies there.

Read this before running anything

dbgorilla collector uninstall is not the opposite of install. It deprovisions the collector’s identity on the server, permanently. Reinstalling gets you a new collector, not the old one back. To pause a collector, use dbgorilla collector stop.

This matters because when a collector already exists, install fails with an error that recommends uninstall by name. Run dbgorilla collector status first.

Before you start

1. You are signed in. dbgorilla whoami should print your email. If not, see CLI Install and Setup.

2. Docker is running (Docker target only). The CLI runs docker info and fails if the engine does not respond.

3. A database login with the right grants. A login with pg_monitor alone is not enough: the collector connects and reports metrics, then silently captures no schema at all. It needs LOGIN, pg_monitor, USAGE on each schema, and SELECT on the tables you want captured. The full SQL is in Collector Installation.

4. pg_stat_statements is loaded. Required for query-level features; see pg_stat_statements. The preflight stops the install if it is not. Loading it needs ALTER SYSTEM SET shared_preload_libraries and a full server restart, not a reload, so do it before you start rather than halfway through.

5. Your deployment supports collectors. Not all do. Check with:

   dbgorilla collector list

   If you get this deployment does not support the managed collector, stop here. Nothing in this document will work against that deployment.

You do not need a connection string. There is no --dsn flag; the CLI asks for the pieces separately and prompts for anything you leave out.

Install it

dbgorilla collector install

Answer the prompts. The CLI checks your sign-in, Docker and the database, runs a read-only preflight, mints the collector’s identity, writes collector.toml and collector.env to ~/.config/dbgorilla/collector/, then pins the image to an exact digest and starts it. Secrets go into the env file (mode 0600) rather than onto the command line, where ps would show them.

If the container fails to start, the CLI undoes all of it: the identity it just minted, the keychain entries and both files. Then it tells you to fix Docker and re-run. A failed install does not leave a half-configured collector behind.

The container is named dbg-collector. On AWS, the CloudFormation stack is named dbgorilla-collector. Both names appear in error messages.

A local Postgres usually needs --ssl-mode disable

The default is verify-full, which is right for a managed or remote database. A stock local Postgres (the official Docker image, Postgres.app, Homebrew) ships with TLS off, so both verify-full and require fail the preflight with server does not support SSL. For that case:

dbgorilla collector install --ssl-mode disable

Only use disable for a database on your own machine. For anything reached over a network it sends the password and every query in clear text.

Seeing what it would do

dbgorilla collector install --dry-run

This renders the config and prints the exact docker run command, without contacting DBGorilla, writing any file, or starting anything. It does not check Docker; it prints a docker run command even on a machine that has none. It previews the configuration, not your environment.

On AWS

dbgorilla collector install --target aws --dry-run   # validate, deploy nothing
dbgorilla collector install --target aws             # discover the database, deploy

The CLI finds your RDS instance or Aurora cluster, works out the networking, and deploys the published CloudFormation template. You can read that template before running anything: latest.yaml

The CLI carries no copy of its own, so the file at that URL is exactly what gets deployed. It needs HTTPS access to that bucket; if your network will not allow it, host the template yourself and pass --template-url.

To watch several databases with one collector, list them in a file and pass --config. Only the instance ID is required per entry. Everything else is discovered from RDS.

One default differs between the two paths

On a local install, leaving the database name empty means every database on the server. In a multi-database AWS config file, leaving databases unset means only the instance’s default database. Same idea, opposite defaults.

Day-to-day

dbgorilla collector status      # what it is and whether it is connected
dbgorilla collector logs -f     # follow the logs
dbgorilla collector stop        # pause it; the identity is kept
dbgorilla collector start       # resume
dbgorilla collector restart

stop and start are reversible. The container stops; the config, the secrets and the identity stay where they are.

status always exits 0

It returns success even when the collector is unreachable, its stack is gone, or the control plane has never heard from it. Read the output, not the exit code. dbgorilla collector status && echo ok prints ok for a dead collector.

The two lines that matter are Deploy: (whether it is running at all) and Connection: (whether DBGorilla can see it; not yet seen by control plane means no).

logs reads docker logs locally and CloudWatch Logs on AWS. The AWS form needs valid AWS credentials. If yours have expired, logs fails even though the collector is fine.

Launching the AWS template by hand

To deploy from the AWS console instead of the CLI, write the config yourself and encode it:

dbgorilla collector encode-config config.toml

The console renders stack parameters as a single line, so the config has to be base64. Paste the output into the stack’s CollectorConfig parameter. The command validates the file first and checks that the result stays under CloudFormation’s 4096-character parameter limit.

Secrets do not go in the config file. Reference them as ${DBG_SERVER_SECRET} and ${DBG_DB_PASSWORD}, and supply the real values through the stack’s ServerSecret and DbPassword parameters.

dbgorilla collector install --target aws does all of this for you. Use encode-config only when launching the template by hand.

Removing it

dbgorilla collector uninstall

This stops and removes the container (or deletes the CloudFormation stack), deprovisions the identity on the server, and clears the local config and secrets. It asks for confirmation first.

If you are signed out, it removes the container but keeps the identity and your local state, and tells you to sign in and run it again, so the identity is never left orphaned.

Flags to leave alone at first

Flag	Why
--yes	Skips the confirmation on uninstall. That is the only prompt protecting an irreversible action.
--force	Installs even though the database preflight failed. The preflight is the safety net.
--commands="", --enable-commands=false	Turns query analysis off. The collector connects fine and produces no insight, with no error to tell you why.
--insecure	Turns off TLS checking, and persists once used with login.
--run-grant	Runs database grants for you, as an admin user. Without it the SQL is printed for you to review.