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.

Before you start

• The CLI installed and signed in. dbgorilla whoami prints your email and organization. If not, see Install the CLI.
• Docker running.
• Port 5432 free on your machine.

1. Start PostgreSQL

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 explains why. A new container has nothing in shared_preload_libraries, so the short form applies:

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. In this container the tables belong to postgres, so use postgres where that page says app_owner:

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

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:

✓ 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).

5. Check the collector

dbgorilla collector status

You should see these three lines:

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

If you see something else, go to 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:

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, then remove the database container:

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.
• Use DBGorilla from your editor: Connect your editor.
• Read the Queries page in depth: Query performance.