Skip to main content

​
Browsing the Postgres DB via psql

The Demos node persists chain state in PostgreSQL. How you reach it depends on which install track you used:
  • Track 1 — Docker Compose (recommended). Postgres runs as a service inside the compose network. You shell into the container with docker compose exec, and credentials are baked in.
  • Track 2 — bare metal ./run (advanced). Postgres runs as a sidecar container with its port mapped to localhost:5332. You connect from the host with a local psql client.
Both tracks ship the same default credentials (from .env.example):
VariableDefault
PG_USERdemosuser
PG_PASSWORDdemospassword
PG_DATABASEdemos
The defaults are fine for solo / local development. Change PG_PASSWORD in .env before exposing anything beyond your own machine. Postgres is never meant to be reachable from the public internet on either track.
In Track 1, PG_HOST=postgres and PG_PORT=5432 — those are the in-network service name and the container-internal port. You do not need a psql client installed on the host; the Postgres image already ships one. From the repo root, with the stack running: 
docker compose exec postgres psql -U demosuser -d demos
That drops you straight into the demos database as demosuser. No password prompt — docker compose exec runs inside the container, where the credentials are already provisioned. If you prefer a one-shot query: 
docker compose exec postgres psql -U demosuser -d demos -c '\dt'

​
Connecting from a host-side client (optional)

If you want to use a desktop GUI like DBeaver or psql on the host, expose the container port by adding a host mapping in docker-compose.override.yml, then point your client at localhost:<mapped-port> with the same credentials. This is not the default and you should only do it on a trusted local machine.

​
Track 2: Bare metal ./run (advanced)

In Track 2, only Postgres runs in Docker (as a sidecar managed by ./run), and its port is mapped to the host as 5332. Set these in .env for the bare-metal path:
  • PG_HOST=localhost
  • PG_PORT=5332
You will need a psql client installed on the host. On Debian/Ubuntu: 
sudo apt install -y postgresql-common
sudo /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh
sudo apt-get install -y postgresql-client-16
Then connect: 
psql -h localhost -p 5332 -U demosuser -d demos
Enter demospassword at the prompt. A helper script lives under postgres_5332/ in the repo for managing the sidecar (start, stop, clean). Use it for lifecycle operations; use psql directly for queries.

​
First commands inside psql

Once you are in the demos=# prompt, list the tables: 
demos=# \dt
You will see the chain’s persistent tables. The most useful ones for day-to-day inspection:
TableWhat’s in it
blocksForged blocks, indexed by number
transactionsAll transactions accepted into a block
mempooltxPending transactions waiting to be included
validatorsActive validator set with stake/status
consensusConsensus round state and signatures
gcr_main / gcr_storageprogram / gcr_hashesGCR account state, storage-program state, and the rolling state hashes
pgp_key_serverIdentity-attestation key material
Some quick exploratory queries: 
-- Latest 10 blocks
SELECT number, hash, status FROM blocks ORDER BY number DESC LIMIT 10;

-- Validator set
SELECT * FROM validators;

-- Recent transactions
SELECT hash, type, "from" FROM transactions ORDER BY "blockNumber" DESC LIMIT 20;

-- Count GCR accounts
SELECT COUNT(*) FROM gcr_main;
Exit with \q.
Schema details (column names, indexes, JSONB shapes) live in the node source under src/model/entities/. Treat them as internal to the node — they can change between releases without notice.