Installation

energydb can be installed using pip:

pip install energydb

or if you are using uv:

uv add energydb

To also install documentation dependencies:

pip install "energydb[docs]"

Requirements

energydb requires:

  • Python 3.12 or higher

  • A reachable PostgreSQL database (version 14+) — stores the asset hierarchy, edges, and series catalog

  • A reachable ClickHouse database — stores all time-series values (via TimeDB)

See Development Setup for a one-command Docker stack that boots both.

Connecting

energydb reads TIMEDB_PG_DSN and TIMEDB_CH_URL from the environment.

# Bash/Zsh
export TIMEDB_PG_DSN='postgresql://postgres:devpassword@127.0.0.1:5433/devdb'
export TIMEDB_CH_URL='http://default:devpassword@localhost:8123/default'

# Fish
set -x TIMEDB_PG_DSN postgresql://postgres:devpassword@127.0.0.1:5433/devdb
set -x TIMEDB_CH_URL http://default:devpassword@localhost:8123/default

A .env file in the project root works as well:

TIMEDB_PG_DSN=postgresql://postgres:devpassword@127.0.0.1:5433/devdb
TIMEDB_CH_URL=http://default:devpassword@localhost:8123/default

Verification

After installation, verify that the schema is created correctly:

import energydb as edb

client = edb.Client()
client.create()  # idempotent: creates the energydb schema + ClickHouse series_values
print("ok")

If both databases are reachable, client.create() returns silently and the energydb schema and the series_values ClickHouse table are ready for use.

Next Steps

Once installed, you can:

  1. Read the SDK guide for the full Client API and the fluent scopes.

  2. Skim the Reference for autogenerated method docs.

  3. Open the Examples notebook for a runnable walkthrough.

  4. For local development (Docker stack, helper scripts, building docs), see Development Setup.