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

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

.. code-block:: bash

   pip install energydb

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

.. code-block:: bash

   uv add energydb

To also install documentation dependencies:

.. code-block:: bash

   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 :doc:`development` for a one-command Docker stack that boots both.


Connecting
----------

energydb reads ``TIMEDB_PG_DSN`` and ``TIMEDB_CH_URL`` from the environment.

.. code-block:: bash

   # 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'

.. code-block:: fish

   # 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:

.. code-block:: text

   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:

.. code-block:: python

   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 :doc:`SDK guide <sdk>` for the full ``Client`` API and the fluent scopes.
2. Skim the :doc:`Reference <reference>` for autogenerated method docs.
3. Open the :doc:`Examples <examples>` notebook for a runnable walkthrough.
4. For local development (Docker stack, helper scripts, building docs),
   see :doc:`development`.