energydb-inspect

A local visual inspector for energydb: a read-only dashboard over your Postgres + ClickHouse showing the asset tree, timeseries plots, a map of the assets, and the raw rows plus the SQL "under the hood".

Inspect your energydb

Point it at any energydb. It is strictly read-only by default, so it is safe against production:

uvx energydb-inspect --pg-dsn postgresql://… --ch-url http://…
# or: pip install energydb-inspect && energydb-inspect --pg-dsn … --ch-url …

The dashboard opens at http://localhost:8000.

You can also pass the connection via the environment or a .env in the working directory. Prefer this for real credentials, so they don't show up in ps/shell history:

# .env
TIMEDB_PG_DSN=postgresql://…
TIMEDB_CH_URL=http://…

Only a .env in the current directory is read (no parent-directory search).

uvx energydb-inspect

The tables are read from the ENERGYDB_SCHEMA schema, default public (matching energydb's own default). Set it if your energydb was created with a different schema:

ENERGYDB_SCHEMA=energydb uvx energydb-inspect --pg-dsn postgresql://… --ch-url http://…

Try it on a throwaway database

Spin up energydb's local-db (in the energydb repo, under local-db/):

docker compose up -d        # Postgres :5433 + ClickHouse :8123

Point the inspector at it. INSPECT_WRITABLE=1 enables the Reset button against the throwaway DB:

# .env
TIMEDB_PG_DSN=postgresql://postgres:devpassword@localhost:5433/devdb
TIMEDB_CH_URL=http://default:devpassword@localhost:8123/default
INSPECT_WRITABLE=1

uvx energydb-inspect        # dashboard at http://localhost:8000 (empty until you add data)

To fill it with a demo portfolio, run the example notebook below and watch the dashboard update live.

INSPECT_WRITABLE only works against a local database; to enable it against a remote host, also set INSPECT_TRUSTED_DB=1.

The example notebook

The repo ships a guided marimo notebook, energydb_inspect/notebooks/demo.py, that builds the demo portfolio step by step. It is run separately with marimo (from a checkout):

uv run --extra notebook python -m marimo edit energydb_inspect/notebooks/demo.py

It opens at http://localhost:2718. Run the cells top to bottom against a writable database (the local-db above) and watch the tree, map and plots fill in live in the dashboard.

Develop from source

git clone https://github.com/rebase-energy/energydb-inspect && cd energydb-inspect
uv sync

Run the backend (read-only API; also serves the built dashboard if web/dist has been bundled into energydb_inspect/_static) and the Vite dev server (hot reload) in two terminals:

INSPECT_WRITABLE=1 uv run python -m uvicorn energydb_inspect.app:app --reload --port 8000
cd web && npm install && npm run dev        # http://localhost:5173

On NixOS, bun/node may not be on PATH; use nix shell nixpkgs#bun -c bun run dev.

Web demo (in-browser, no database)

A zero-backend build of the dashboard exists for hosting a public "what is energydb" demo. See docs/HOSTING.md.