# Local development with Docker

DBGorilla can watch the Postgres running on your own machine, the database you develop against.
It takes one command.

This is the short path. For RDS, Aurora, or anything not on your machine, see
[AWS RDS and Aurora](./aws-rds-aurora.md).

## Before you start

- **Docker running.** Not just installed: the CLI checks that the engine responds.
- **Postgres running locally**, and the port it listens on.
- **A database user for DBGorilla**, and its password. A plain read-only login is not enough; see
  [Grant the right permissions](#grant-the-right-permissions) below.
- **Signed in.** `dbgorilla whoami` should print your email. If not, see
  [CLI Install and Setup](../cli-install-and-setup.md).
- **A deployment that supports collectors.** Check with `dbgorilla collector list`. If it returns
  `this deployment does not support the managed collector`, nothing below will work against it.

## Grant the right permissions

Create the user with the permissions the collector actually needs. `pg_monitor` alone is not
enough: with only that grant the collector connects and reports metrics, but captures no schema,
and nothing surfaces an error.

```sql
CREATE ROLE dbg_readonly LOGIN PASSWORD 'choose-a-password';
GRANT pg_monitor TO dbg_readonly;                          -- cluster-wide stats
GRANT USAGE ON SCHEMA public TO dbg_readonly;              -- per schema you want captured
GRANT SELECT ON ALL TABLES IN SCHEMA public TO dbg_readonly;
ALTER DEFAULT PRIVILEGES IN SCHEMA public
  GRANT SELECT ON TABLES TO dbg_readonly;                  -- tables created later
```

`pg_monitor` covers the stats views the metrics pipeline reads, but grants nothing on your tables,
and schema capture shells out to `pg_dump`, which has to `SELECT` every table it dumps. A role with
only `pg_monitor` connects and reports metrics fine, then fails every schema pass with
`permission denied for table …`, logged as a warning that retries forever, so the collector looks
healthy while capturing no schema at all.

Repeat the last three statements for every schema and database you want captured.

## Connect it

```sh
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 contacts nothing, writes nothing and starts nothing;
it prints the config it would render and the `docker run` command it would use.

### Why `--ssl-mode disable`

A stock local Postgres ships with TLS off, and the CLI defaults to `verify-full`. Without this
flag the connection check fails before anything is installed.

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

### If the check reports `pg_stat_statements` is not loaded

Install stops there. `pg_stat_statements` powers query performance data (see
[pg_stat_statements](./overview.md#pg_stat_statements)), and it has to be loaded
at server start:

```sql
ALTER SYSTEM SET shared_preload_libraries = 'pg_stat_statements';
```

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

## What it handles for you

**Docker networking.** The collector runs in a container, so `localhost` there means the
container, not your machine. The CLI rewrites `localhost` to `host.docker.internal` and tells you
it did. You type the address you already know.

**Your password stays 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 will not clobber an existing collector.** If one is already installed the command stops and
says so.

## Check on it

```sh
dbgorilla collector status
dbgorilla collector logs -f
```

The container is named `dbg-collector`, so `docker ps` and `docker logs dbg-collector` work too.

Read the `Deploy:` and `Connection:` lines rather than the exit code. `collector status` exits 0
even when it cannot reach anything.

:::tip[Check what it will collect]

Query analysis, meaning the collector running `EXPLAIN` and sample queries for you, is configured
separately from the connection. Run the install with `--dry-run` and read the `[commands]` block
in the rendered config. That is the authoritative answer for your setup.
:::

## Stopping and removing

```sh
dbgorilla collector stop        # pause, keeping its identity
dbgorilla collector start       # resume
dbgorilla collector uninstall   # remove and deprovision its identity
```

`stop` is reversible. `uninstall` is not: it discards the collector's identity on the server, and
reinstalling gives you a new collector rather than the same one back.

One exception. If you are signed out, `uninstall` cannot reach the server, so it removes the local
container and leaves the identity and local state in place, then tells you to sign in and run it
again. Nothing is orphaned, and the destructive half has not happened yet.

If `install` says a collector already exists, run `dbgorilla collector status` first. The error
suggests `uninstall`, but that destroys a working collector to solve a problem you may not have.