Installation
============

timedb can be installed using `pip <https://pypi.org/project/pip/>`_:

.. code-block:: bash

   pip install timedb

or if you are using `uv <https://docs.astral.sh/uv/>`_:

.. code-block:: bash

   uv add timedb

To also install test dependencies:

.. code-block:: bash

   pip install "timedb[test]"


Requirements
------------

timedb requires:

- Python 3.12 or higher
- A reachable `ClickHouse <https://clickhouse.com>`_ server (see :doc:`development`
  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.

.. code-block:: bash

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

.. code-block:: fish

   # 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``.

.. code-block:: text

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


Verification
------------

.. code-block:: python

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


Next Steps
----------

1. Read the :doc:`SDK guide <sdk>` for the full ``TimeDBClient`` API.
2. Open the :doc:`example notebook <examples>` for a runnable walkthrough.
3. Skim the :doc:`reference <reference>` for autogenerated method docs.
4. For local development (Docker stack, helper scripts, building docs),
   see :doc:`development`.