Skip to main content

Use your own PostgreSQL

The monitoring bundle runs its own PostgreSQL by default. To keep the logs in a database you already operate (backed up, monitored, maybe managed), point both halves at it: Grafana reads from it, Hop writes to it.

Requires PostgreSQL 12 or later.

1. Create the database and a user​

As a database administrator:

CREATE USER hop_logging WITH PASSWORD 'a-strong-password';
CREATE DATABASE logging OWNER hop_logging;

The Hop side always connects to a database named logging. Any user name works. The user needs INSERT, UPDATE and SELECT on the two logging tables, and CREATE on the database if the bundle should create the tables for you.

2. Create the tables​

Either let the bundle do it on every start (step 3 needs nothing extra), or apply the schema yourself, for example when the user above has no CREATE rights:

psql -h db.internal -U hop_logging -d logging -f sql/init-logging.sql

The script is idempotent: it creates what is missing, migrates older layouts, and leaves your data alone. Run it again after each upgrade.

3. Point Grafana at it​

In .env, remove the COMPOSE_PROFILES=logging-db line, so the bundled database no longer starts, and describe yours:

LOGGING_DB_HOST=db.internal
LOGGING_DB_PORT=5432
LOGGING_DB_NAME=logging
LOGGING_DB_USER=hop_logging
LOGGING_DB_PASSWORD=a-strong-password
LOGGING_DB_SSLMODE=require

Then start, or restart, the stack:

docker compose -f docker-compose-monitoring.yml up -d

If you applied the schema by hand and do not want the stack to try, add --scale logging-db-init=0.

4. Point Hop at it​

Run the installer with the same host, port and user, once per project:

./install-logging.sh --project-home /path/to/project --project-name sales \
  --environment-file /path/to/project/environments/prod.json \
  --logging-host db.internal --logging-port 5432 \
  --logging-user hop_logging --logging-password 'a-strong-password'

--logging-host is resolved from wherever Hop runs. If Hop runs in a container, use a host name that container can reach, not localhost.

Check it​

Run a workflow, then on the database:

SELECT type, count(*) FROM log_object
WHERE start_date > now() - interval '15 minutes' GROUP BY type;

You should see at least a WORKFLOW row. If you see nothing, see Troubleshooting.