AWS RDS and Aurora

Set up the collector for RDS or Aurora. The CLI deploys it as one Fargate task in your own AWS account, under your own AWS credentials. It reuses whatever aws sso login or AWS_PROFILE already resolves, and nothing sensitive passes through DBGorilla. If your account is managed from Terraform, CDK or Pulumi instead, skip the CLI and use Deploying from Terraform, CDK or Pulumi; it creates the same stack.

For the Postgres on your own laptop, see Your machine (Docker). For PostgreSQL in Kubernetes, see Kubernetes, which uses the Helm chart. The chart handles deployment into a cluster.

Do not run uninstall to fix an install error

What uninstall destroys, and what to run instead, is on Manage collectors.

Before you start

1. Sign in to the DBGorilla CLI. If you have not, see CLI Install and Setup.

2. Make your AWS credentials resolve. The CLI uses the same credential chain as the AWS CLI. If aws sts get-caller-identity works in your shell, so will the install.

3. Create 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 Database grants.

4. Load pg_stat_statements. Query-level features need it; see pg_stat_statements. The preflight stops the install if it is not loaded. On RDS and Aurora you load it through the parameter group’s shared_preload_libraries, and the change needs an instance reboot; a reload is not enough. Do this before you start, so the reboot does not land during the install.

5. Check that your deployment supports collectors. Not all deployments do. Run:

   dbgorilla collector list

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

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

Install

With the CLI

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, mints the collector’s identity, and deploys the published CloudFormation template. The stack is named dbgorilla-collector, which is the name that appears in error messages. You can read the 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.

--dry-run renders the config and prints what would be deployed without contacting DBGorilla or AWS. It previews the configuration. It does not check your environment.

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.

Leaving databases unset watches only the default database

In a multi-database config file, an entry with no databases list watches the instance’s default database, not every database on it. List the ones you want.

This is the CLI’s --config file. In collector.toml itself, an empty databases list does the opposite and watches every database; see Database address and TLS.

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 every command off for every database, explain included. The collector still connects and produces no insight, without reporting an error.
--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.

Without the CLI

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 must be base64-encoded. 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.

Keep secrets out of 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.

AWS RDS and Aurora PostgreSQL

This config is for RDS for PostgreSQL or Aurora PostgreSQL, with the collector logging in through IAM. The database user needs rds_iam and pg_monitor; see AWS RDS and Aurora.

[dbgorilla]
agent_id  = "<agent id from the app>"
tenant_id = "<tenant id from the app>"
secret    = "${DBG_SERVER_SECRET}"

[[component]]
name   = "prod-rds"
engine = "postgres"

[component.provider]
type        = "aws_rds"
region      = "us-east-1"
instance_id = "prod-pg"

[component.auth]
method = "iam"
user   = "dbg_collector"

[component.connect]
host      = "prod-pg.abc123.us-east-1.rds.amazonaws.com"
port      = 5432
databases = ["app"]

[topology]
interval = "60s"

[commands]
enabled = true
allowed = ["explain", "collect_statistics"]   # see https://www.dbgorilla.com/docs/reference/collector-commands/#database-commands

For an Aurora cluster, replace the provider block and point host at the cluster endpoint. The writer and readers are discovered from it:

[component.provider]
type       = "aws_aurora"
region     = "us-east-1"
cluster_id = "prod-aurora"

To have the CLI write and deploy this config, see With the CLI.

The Terraform, AWS CDK and Pulumi versions are on Infrastructure as code.

AWS RDS for MySQL

This config is for RDS for MySQL with IAM login. The database user is IAM-enabled and carries the MySQL grants on MySQL.

[dbgorilla]
agent_id  = "<agent id from the app>"
tenant_id = "<tenant id from the app>"
secret    = "${DBG_SERVER_SECRET}"

[[component]]
name   = "prod-rds-mysql"
engine = "mysql"

[component.provider]
type        = "aws_rds"
region      = "us-east-1"
instance_id = "prod-mysql"

[component.auth]
method = "iam"
user   = "dbg_iam_user"

[component.connect]
host      = "prod-mysql.abc.us-east-1.rds.amazonaws.com"
port      = 3306
databases = ["app"]

[topology]
interval = "60s"

[commands]
enabled = true
allowed = ["explain", "collect_statistics"]   # see https://www.dbgorilla.com/docs/reference/collector-commands/#database-commands

Run it with the same docker run as Self-managed PostgreSQL, on a host whose AWS identity is allowed rds-db:connect for this user. secrets.env holds only DBG_SERVER_SECRET; IAM login has no password.

AWS RDS with IAM authentication

The complete file is under AWS RDS for MySQL.

Check it is working

dbgorilla collector status and the two lines of its output to read are under Day-to-day in Manage collectors.

Upgrade

The commands for a running collector are under Day-to-day in Manage collectors. For a stack you deploy from Terraform, CDK or Pulumi, see Upgrading and removing in Infrastructure as code.

Remove

What dbgorilla collector uninstall deletes is under Removing it in Manage collectors.

Next

To manage this stack from Terraform, CDK or Pulumi, see Deploying from Terraform, CDK or Pulumi.