Installation

timedb can be installed using pip:

pip install timedb

or if you are using uv:

uv add timedb

Requirements

timedb requires:

Python 3.9 or higher
PostgreSQL database (version 12+)
For API functionality: FastAPI and uvicorn (included in dependencies)

Dependencies

timedb includes the following key dependencies:

psycopg[binary]>=3.1 - PostgreSQL adapter (psycopg3)
pandas>=2.0.0 - Data manipulation
pint>=0.23 - Unit handling and conversion
pint-pandas>=0.3 - Pandas integration for Pint units
fastapi>=0.104.0 - API framework (for REST API server)
uvicorn[standard]>=0.24.0 - ASGI server (for REST API server)
typer>=0.9.0 - CLI framework

Database Setup

Before using timedb, you need a PostgreSQL database. You can use:

A local PostgreSQL instance
A cloud-hosted database (e.g., Neon, Supabase, AWS RDS)
A Docker container running PostgreSQL

Set up your database connection using one of these environment variables:

TIMEDB_DSN - Preferred connection string
DATABASE_URL - Alternative connection string (for compatibility with platforms like Heroku)

Example connection strings:

# Using TIMEDB_DSN
export TIMEDB_DSN="postgresql://user:password@localhost:5432/timedb"

# Or using DATABASE_URL
export DATABASE_URL="postgresql://user:password@localhost:5432/timedb"

You can also use a .env file in your project root:

TIMEDB_DSN=postgresql://user:password@localhost:5432/timedb

The python-dotenv package (included in dependencies) will automatically load this file.

Verification

After installation, verify that timedb is installed correctly:

timedb --help

You should see the timedb CLI help message with available commands.

Create the database schema:

timedb create tables

Or using Python:

import timedb as td
td.create()

Next Steps

Once installed, you can:

Explore the Examples to learn by doing
Use the CLI to manage your database schema
Use the SDK to interact with your database from Python
Set up the API server to serve data via REST API