Installation

timedb can be installed using pip:

pip install timedb

or if you are using uv:

uv add timedb

To also install test dependencies:

pip install "timedb[test]"

Requirements

timedb requires:

• Python 3.12 or higher

• A reachable ClickHouse server (see Development Setup for a one-command Docker stack)

Dependencies

timedb’s runtime stack is intentionally small:

• clickhouse-connect — ClickHouse HTTP client

• polars — primary DataFrame interface

• pandas — accepted on the write path for convenience

• pyarrow — Arrow-backed bulk inserts and reads

• uuid6 — UUID7 client-side run id generation

Connecting

TimeDBClient reads its connection string from the TIMEDB_CH_URL environment variable, or accepts it directly via the constructor.

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

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

A .env file in the project root works as well — timedb loads it on import via python-dotenv.

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

Verification

from timedb import TimeDBClient
td = TimeDBClient()
td.create()        # idempotent: creates series_values + run_series
print("ok")

Next Steps

1. Read the SDK guide for the full TimeDBClient API.

2. Open the example notebook for a runnable walkthrough.

3. Skim the reference for autogenerated method docs.

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