¶ Local bookmark
Local credentials are disposable and can be committed when they are throwaway. Use this for normal local inspection.
Operations
¶ Database GUI / pgweb
Opt-in database visibility, not a standing admin surface. pgweb is behind the Docker Compose tools profile, binds to 127.0.0.1, and should use bookmarks only.
pgweb behind
tools
Bound to 127.0.0.1
Prod uses replybox_ro
Start
¶ Bring up pgweb only when you need it
The profile flag is required. pgweb never starts with normal infra and reads its connections from infra/docker/pgweb/bookmarks/*.toml.
From the repository root
docker compose -f infra/docker/compose.yaml up -d
docker compose -f infra/docker/compose.yaml --profile tools up -d pgwebAccess model
¶ Bookmarks are the control surface
Open http://localhost:8085 and pick a bookmark. Local can be writable; production must be read-only at the database role level.
Production setup
¶ Create the bookmark, then let pgweb rescan
Production access should authenticate as replybox_ro, not the application's replybox user. Create that role with infra/sql/pgweb-readonly-role.sql.
One-time optional prod bookmark
cp infra/docker/pgweb/bookmarks/prod.toml.example infra/docker/pgweb/bookmarks/prod.toml
# Fill in host + password; no restart needed.Guardrails
¶ Do not turn pgweb into a general DB console
Use bookmarks only.pgweb runs with
--bookmarks-only so arbitrary connection strings cannot be typed into the UI.
Keep the port local.The tool is published on 127.0.0.1 only.
Use replybox_ro for production.Read-only UI state is not a substitute for a read-only database role.
Never commit prod.toml.Only local.toml and the production example belong in the repo.
Stop and troubleshoot
¶ Close the access surface when done
Stop
¶ Shut down pgweb explicitly
Stop the tools-profile service
docker compose -f infra/docker/compose.yaml --profile tools stop pgwebConnection refused
¶ Check DigitalOcean Trusted Sources
If production refuses the connection, check Trusted Sources on the DigitalOcean database cluster. The container egresses through this machine's public IP.