# 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](./local-docker.md).
- PostgreSQL running in Kubernetes: [Kubernetes](./kubernetes.md), 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.

:::danger[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](../cli-install-and-setup.md).
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](./overview.md#database-grants).
4. **`pg_stat_statements` is loaded.** Required for query-level features; see
   [pg_stat_statements](./overview.md#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:

   ```sh
   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

```sh
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.

:::caution[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:

```sh
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

```sh
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

```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, and deploys the
published CloudFormation template. You can read that 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`.

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[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

```sh
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.

:::caution[`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:

```sh
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

```sh
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. |