# Your machine (Docker)

Connect DBGorilla to the Postgres on your own machine, the database you develop against, with one
CLI command.  The CLI runs the collector for you as a Docker container.

For RDS, Aurora, or anything not on your machine, see
[AWS RDS and Aurora](/docs/connect/aws-rds-aurora/).

## Before you start

- Start Docker.  The CLI checks that the engine responds, so being installed is not enough.  It runs natively on Apple-silicon Macs.
- Start Postgres locally, and note the port it listens on.
- Create a database user for DBGorilla, and note its password.  A plain read-only login is not
  enough; see [Grant the right permissions](/docs/connect/prepare-postgresql/#grant-the-right-permissions)
  and [Database grants](/docs/connect/prepare-postgresql/#database-grants) in Prepare PostgreSQL.
- Sign in to the DBGorilla CLI.  If you have not, see
  [CLI Install and Setup](/docs/getting-started/cli-install-and-setup/).
- Check that your deployment supports collectors with `dbgorilla collector list`.  If it returns
  `this deployment does not support the managed collector`, nothing below will work against it.

## Install

```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 checks whether the database accepts TLS, then prints the config it would render and the `docker run` command it would use.  It reports that nothing was provisioned, written or started.

To write the config yourself and run the container by hand, see
[Self-managed PostgreSQL](/docs/connect/self-managed/#self-managed-postgresql).

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

A stock local Postgres ships with TLS off.  For `--target docker`, CLI 0.8.0 already defaults
`--ssl-mode` to `disable`, so the flag in the command above states the default.

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

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

On CLI 0.8.0 the install warns that query-performance data will be unavailable, and installs the
collector anyway.  `pg_stat_statements` powers query performance data (see
[pg_stat_statements](/docs/connect/prepare-postgresql/#pg_stat_statements)), and it has to be loaded
at server start:

```sql
SHOW shared_preload_libraries;
-- empty: ALTER SYSTEM SET shared_preload_libraries = 'pg_stat_statements';
-- otherwise keep every existing entry, e.g. 'auto_explain,pg_stat_statements'
```

`ALTER SYSTEM SET` replaces the whole list, so any library you leave out stops loading.

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

### Query plans and statistics are on by default

A Docker install allows `explain` and `collect_statistics`.

To choose the commands during installation, pass a flag:

| Flag | What the database gets |
|---|---|
| none | `explain` and `collect_statistics` |
| `--enable-commands` | all three commands |
| `--commands=explain` | the commands you list |
| `--enable-commands=false` or `--commands=""` | none, `explain` included |

The install writes the result to the database's `[[component]]` as a `commands` list.  That list
overrides `[commands]`.  To change it later, edit the list in the config written by the install
and restart the container:

```sh
# commands = ["explain", "collect_statistics", "execute_query"]   adds read-only checks
# commands = []                                                    turns them all off
$EDITOR ~/.config/dbgorilla/collector/collector.toml
docker restart dbg-collector
```

Use `--dry-run` before installing to print the config it would write.  The `commands` list it prints is the authoritative answer for your setup.

See [Database commands](/docs/reference/collector-commands/#database-commands) for what each
command permits, and what stays bounded regardless.

### What the install does for you

- It rewrites the address.  The collector runs in a container, so `localhost` there means the
  container, and your machine is somewhere else.  The CLI rewrites `localhost` to `host.docker.internal` and tells you it did.  You type the address you already know.
- It keeps your password 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 leaves an existing collector alone.  If one is already installed, the command stops and says so.

## Check it is working

Follow [Check on it](/docs/connect/check-it-is-working/#your-machine-docker) in Check it is
working.

## Upgrade

The commands for a running Docker collector are under
[Stopping and removing](/docs/administer/manage-collectors/#your-machine-docker) in Manage
collectors.

## Remove

What `dbgorilla collector uninstall` removes, and what stays on Home afterwards, is under
[Stopping and removing](/docs/administer/manage-collectors/#your-machine-docker) in Manage
collectors.