Development Setup

1) Clone the repository

If you have not cloned the project yet:

git clone https://github.com/rebase-energy/timedb.git
cd timedb

2) Installation

Set up your preferred Python virtual environment first, then install the package in editable mode with development dependencies.

Create a virtual environment (choose one):

uv venv

python -m venv .venv

Activate it:

# Bash/Zsh
source .venv/bin/activate

# Fish
source .venv/bin/activate.fish

Using standard pip:

pip install -e ".[notebooks,docs,test]"

Using uv (optional, faster dependency management):

uv pip install -e ".[notebooks,docs,test]"

If you skip virtual environment activation, uv will fail with No virtual environment found.

To run scripts inside your environment:

python file.py
# or
uv run file.py

3) Database Environment

TimeDB is a stateless library on top of ClickHouse (port 8123) — it stores all time-series values there. There is no PostgreSQL dependency; series metadata lives in the calling application (e.g. energydb).

Spin up ClickHouse locally using Docker:

cd local-db/
docker compose up -d

Verify the container is running:

docker ps

You should see timedb_clickhouse (port 8123).

4) Configuration

The application requires the TIMEDB_CH_URL environment variable.

Fastest option (recommended): from the repository root, copy the example environment file.

cp .env.example .env

The variable is already set correctly for the local Docker setup:

TIMEDB_CH_URL=http://default:devpassword@localhost:8123/default

Alternatively, export the variable directly in your shell:

# Bash/Zsh
export TIMEDB_CH_URL='http://default:devpassword@localhost:8123/default'

# Fish
set -x TIMEDB_CH_URL http://default:devpassword@localhost:8123/default

5) Next Steps

Now you can try the examples in examples/, or build your own script using the SDK/API.

6) Database Management & Tools

Helper scripts (Bash and Fish)

If you are using the local Docker setup, use scripts in local-db/:

./restart-db.sh or ./restart-db.fish: Restarts the container while preserving existing data.
./clean-restart-db.sh or ./clean-restart-db.fish: Removes the container, volume, and data, then starts fresh.

Manual inspection

Connect to ClickHouse with the HTTP interface:

curl http://localhost:8123/ping

Or with the native client:

docker exec -it timedb_clickhouse clickhouse-client

7) Building Documentation

Generate HTML documentation with Sphinx:

sphinx-build -b html docs/ docs/_build/html

The built site will be available at docs/_build/html/.