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):

Variable	Default
`PG_USER`	`demosuser`
`PG_PASSWORD`	`demospassword`
`PG_DATABASE`	`demos`

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.

Track 1: Docker Compose (recommended)

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:

Table	What’s in it
`blocks`	Forged blocks, indexed by `number`
`transactions`	All transactions accepted into a block
`mempooltx`	Pending transactions waiting to be included
`validators`	Active validator set with stake/status
`consensus`	Consensus round state and signatures
`gcr_main` / `gcr_storageprogram` / `gcr_hashes`	GCR account state, storage-program state, and the rolling state hashes
`pgp_key_server`	Identity-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.

Internal Mechanisms

Validator Lifecycle

Network Governance

Global Change Registry

Consensus Mechanism

Network Forks

L2PS Privacy Subnets

ZK Identity

Architecture

Communications Stack

API Reference

Operations

Incentives

MCP Server

Bridges

Developers Testbed

Miscellaneous

Browsing The Postgres DB via psql

Browsing the Postgres DB via psql

Track 1: Docker Compose (recommended)

Connecting from a host-side client (optional)

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

First commands inside `psql`

​Browsing the Postgres DB via psql

​Track 1: Docker Compose (recommended)

​Connecting from a host-side client (optional)

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

​First commands inside psql

Browsing the Postgres DB via psql

Track 1: Docker Compose (recommended)

Connecting from a host-side client (optional)

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

First commands inside `psql`