Installation

One container or one binary — the UI and the API always ship together. Prebuilt release downloads aren't published yet; the alpha builds from source in a couple of minutes.

Docker (recommended)

The repository ships a three-stage Dockerfile that bundles the web UI into a static Go binary on an Alpine base, running as a non-root user:

terminal

git clone https://github.com/aoncodev/PGQViewer.git
cd PGQViewer
docker build -t pgqviewer .
docker run --rm -p 127.0.0.1:8080:8080 -v pgqviewer-data:/data pgqviewer

Open http://localhost:8080 and fill in the connection form with your PostgreSQL 19 server. The -v pgqviewer-data:/data volume persists your saved connections between runs.

Networking notes

Your database must be reachable from inside the container. For a PostgreSQL running on the same machine, use host host.docker.internal in the connection form — and on Linux, add the host-gateway mapping:

terminal — Linux

docker run --rm -p 127.0.0.1:8080:8080 \
  --add-host=host.docker.internal:host-gateway \
  -v pgqviewer-data:/data pgqviewer

Publish on loopback or a trusted network only

The endpoint is unauthenticated and opens outbound database connections for whoever reaches it. Keep the port on 127.0.0.1 (as above) unless every peer on the network is trusted.

From source: one self-contained binary

pnpm build builds the renderer, copies it into the Go tree, and compiles everything into a single executable with the web UI embedded. The binary is CGO-free (the SQLite app store uses a pure-Go driver), so it cross-compiles to Linux, macOS, and Windows without a C toolchain.

terminal

pnpm install
pnpm build          # renderer → embedded web UI → single Go binary
server/bin/pgqviewer-server --http :8080

Server flags

Flag	Behaviour
`--http <addr>`	Bind to a fixed address, e.g. `--http :8080` (used by Docker and the dev stack).
`(no flags)`	Auto-port mode: binds `127.0.0.1:0`, the OS picks a free port, and the server prints `LISTEN=127.0.0.1:<port>` to stdout so a wrapping script can discover the address.
`--log-level`	`debug` \| `info` \| `warn` \| `error` (default `info`). Logs are JSON on stderr.

Hot-reloading dev stack

For working on PGQViewer itself: the Go API on 127.0.0.1:8080 and the Vite dev server on localhost:5173, concurrently.

terminal

pnpm install
pnpm dev            # Go API on :8080 + Vite dev server on :5173

Requirements

To run: Docker, or nothing at all if you built the binary.
To build: Node 22 + pnpm 11 for the renderer, Go 1.25 for the server.
To view anything: a PostgreSQL 19 instance (Beta 1 or newer) with at least one CREATE PROPERTY GRAPH defined. PGQViewer does not ship a demo database.