# 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](/docs/connect/infrastructure-as-code/#deploying-from-terraform-cdk-or-pulumi); it creates the same stack. For the Postgres on your own laptop, see [Your machine (Docker)](/docs/connect/docker/). For PostgreSQL in Kubernetes, see [Kubernetes](/docs/connect/kubernetes/), which uses the Helm chart. The chart handles deployment into a cluster. :::danger[Do not run `uninstall` to fix an install error] What `uninstall` destroys, and what to run instead, is on [Manage collectors](/docs/administer/manage-collectors/#your-machine-docker). ::: ## Before you start 1. Sign in to the DBGorilla CLI. If you have not, see [CLI Install and Setup](/docs/getting-started/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](/docs/connect/prepare-postgresql/#database-grants). 4. Load `pg_stat_statements`. Query-level features need it; see [pg_stat_statements](/docs/connect/prepare-postgresql/#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: ```sh 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 ```sh 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`](https://dbgorilla-cfn-us-east-1.s3.us-east-1.amazonaws.com/collector/fargate/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. :::note[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](/docs/reference/collector-configuration/#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: ```sh 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](/docs/connect/infrastructure-as-code/#what-you-need-first). ```toml [dbgorilla] agent_id = "" tenant_id = "" 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: ```toml [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](#with-the-cli). The Terraform, AWS CDK and Pulumi versions are on [Infrastructure as code](/docs/connect/infrastructure-as-code/#aws). #### 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](/docs/connect/prepare-mysql/). ```toml [dbgorilla] agent_id = "" tenant_id = "" 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](/docs/connect/self-managed/#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](#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](/docs/administer/manage-collectors/#aws) in Manage collectors. ## Upgrade The commands for a running collector are under [Day-to-day](/docs/administer/manage-collectors/#aws) in Manage collectors. For a stack you deploy from Terraform, CDK or Pulumi, see [Upgrading and removing](/docs/connect/infrastructure-as-code/#upgrading-and-removing) in Infrastructure as code. ## Remove What `dbgorilla collector uninstall` deletes is under [Removing it](/docs/administer/manage-collectors/#aws) in Manage collectors. ## Next To manage this stack from Terraform, CDK or Pulumi, see [Deploying from Terraform, CDK or Pulumi](/docs/connect/infrastructure-as-code/#aws).