# Your first database

This walkthrough starts a throwaway PostgreSQL in Docker, connects DBGorilla to it, and ends with
your own queries on the Queries page.  It takes about ten minutes, a few of them waiting.

To connect a database you already run, skip to [Choose your setup](/docs/connect/).

## Before you start

- The CLI installed and signed in.  `dbgorilla whoami` prints your email and organization.  If
  not, see [Install the CLI](/docs/getting-started/cli-install-and-setup/).
- Docker running.
- Port 5432 free on your machine.

## 1. Start PostgreSQL

```sh
docker run -d --name first-postgres -e POSTGRES_PASSWORD=postgres -p 5432:5432 postgres:18
docker exec first-postgres pg_isready -U postgres
```

You should see `accepting connections`.  If you see `no response`, wait a few seconds and run the
second command again.

## 2. Turn on pg_stat_statements

DBGorilla reads query performance from this extension.
[pg_stat_statements](/docs/connect/prepare-postgresql/#pg_stat_statements) explains why.  A new
container has nothing in `shared_preload_libraries`, so the short form applies:

```sh
docker exec first-postgres psql -U postgres -c "ALTER SYSTEM SET shared_preload_libraries = 'pg_stat_statements';"
docker restart first-postgres
docker exec first-postgres pg_isready -U postgres
docker exec first-postgres psql -U postgres -c "CREATE EXTENSION pg_stat_statements;"
```

You should see `ALTER SYSTEM`, then `accepting connections`, then `CREATE EXTENSION`.  If
`pg_isready` says `no response`, wait a few seconds and run it again before the last command.

## 3. Create a login for DBGorilla

Run the statements from [Database grants](/docs/connect/prepare-postgresql/#database-grants).  In
this container the tables belong to `postgres`, so use `postgres` where that page says
`app_owner`:

```sh
docker exec -i first-postgres psql -U postgres <<'SQL'
CREATE ROLE dbg_readonly LOGIN PASSWORD 'replace-me';
GRANT pg_monitor TO dbg_readonly;
GRANT USAGE ON SCHEMA public TO dbg_readonly;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO dbg_readonly;
ALTER DEFAULT PRIVILEGES FOR ROLE postgres IN SCHEMA public
  GRANT SELECT ON TABLES TO dbg_readonly;
SQL
```

You should see `CREATE ROLE`, `GRANT ROLE`, `GRANT`, `GRANT` and `ALTER DEFAULT PRIVILEGES`.

## 4. Install the collector

```sh
dbgorilla collector install \
  --target docker \
  --name "local dev postgres" \
  --db-host localhost \
  --db-port 5432 \
  --db-user dbg_readonly \
  --ssl-mode disable
```

At the password prompt, type `replace-me`.

The install checks the database first, then starts a container named `dbg-collector`.  You should
see a list of checks marked `✓`, then:

```text
✓ Container started: dbg-collector
Verifying connection.
✓ Collector connected (connected)

Collector installed. Next:
```

Two `⚠` lines about `track_io_timing` and `track_functions` are expected on a stock PostgreSQL
and do not stop the install.  What each flag does is on
[Your machine (Docker)](/docs/connect/docker/#install).

## 5. Check the collector

```sh
dbgorilla collector status
```

You should see these three lines:

```text
Container:  running
Connection: connected
Workload:   collecting (pg_stat_statements in the postgres maintenance DB)
```

If you see something else, go to [Collector](/docs/troubleshooting/collector/) in Troubleshooting.

## 6. Run some queries

`pgbench` comes with the PostgreSQL image.  This creates its sample tables, then runs a mixed
read and write load for one minute:

```sh
docker exec first-postgres pgbench -i -U postgres postgres
docker exec first-postgres pgbench -U postgres -c 4 -T 60 postgres
```

The second command prints a summary when the minute is up, ending in a `tps =` line.

## 7. See it in DBGorilla

1. Open DBGorilla.  **Home** lists your databases under **Components**.  You should see
   **local dev postgres**, marked **Connected**, with **Postgres 18** and **Self-hosted**.
2. Click **local dev postgres**.  The overview shows **Connected** under **Availability**, with
   live connection, query and transaction counts.
3. In the sidebar, under the component's own items, click the database **postgres**, then
   **Queries**.

**Top Queries** lists the `pgbench` statements, such as
`UPDATE pgbench_branches SET bbalance = bbalance + $1 WHERE bid = $2`, with their total time,
calls and average time.

If the page says **No Queries**, wait five minutes and reload.  A new database's queries take a
few minutes to reach this page.

## Clean up

To keep using this database, leave it running and carry on.

To remove everything, uninstall the collector as described in
[Stopping and removing](/docs/administer/manage-collectors/#your-machine-docker), then remove the
database container:

```sh
dbgorilla collector uninstall
docker rm -f first-postgres
```

`uninstall` asks you to confirm.  Afterwards **local dev postgres** stays on **Home**, marked
**Disconnected**.  To remove it:

1. Click your name at the bottom of the sidebar, then **Admin Portal**.
2. Click **Components**.
3. Click the arrow beside **local dev postgres**, then **Delete Component**, then **Delete**.

## Next

- Connect the database you actually run: [Choose your setup](/docs/connect/).
- Use DBGorilla from your editor: [Connect your editor](/docs/integrations/editor/).
- Read the Queries page in depth: [Query performance](/docs/using-dbgorilla/query-performance/).