.. _sardana-howto-environment-backends:

================================
Selecting an environment backend
================================

The MacroServer persists the :ref:`macro environment <macro-environment>`
in a database. The storage backend is selected with the
:ref:`EnvironmentDb <sardana-macroserver-api-environmentdb>` attribute.
In case Sardana is used with Tango this configuration is accessible via the
``EnvironmentDb`` `~sardana.tango.macroserver.MacroServer.MacroServer`
device property. Three backends are available: *shelve* (default),
*Redis* and *Tango DB*.

The backend is chosen based on the format of the ``EnvironmentDb`` value:

=============================== ===========================================
``EnvironmentDb`` value         Backend
=============================== ===========================================
``<file system path>``          shelve (default)
``redis://...`` / ``rediss://`` Redis
``property`` / ``property:...`` Tango DB (free object properties)
=============================== ===========================================

The MacroServer needs to be restarted in order to apply a change of the
``EnvironmentDb`` property.

Shelve backend (default)
------------------------

By default the environment is stored in a file using the Python
:mod:`shelve` module. The ``EnvironmentDb`` value is interpreted as the
path of this file, by default:
``/tmp/tango-<user>/<ds_exec_name>/<ds_inst_name>/macroserver.properties``.
The path may contain the ``%(ds_exec_name)s``, ``%(ds_inst_name)s`` and
``%(ds_name)s`` substitution patterns. The parent directory is created
automatically if it does not exist.

.. warning::
    Many systems clean the ``/tmp`` directory on reboot. If you want your
    environment to survive reboots, configure the ``EnvironmentDb``
    property to point to a persistent location, e.g.::

        import tango
        db = tango.Database()
        db.put_device_property(
            "macroserver/demo1/1",
            {"EnvironmentDb": "/var/lib/sardana/demo1/macroserver.properties"})

The underlying :mod:`dbm` implementation used by shelve can be
selected with the `~sardana.sardanacustomsettings.MS_ENV_SHELVE_BACKEND`
custom setting:

- `None` (default) - first try ``gnu`` and if not available fall back to
  ``dumb``
- ``"gnu"`` - better performance, but requires an additional package,
  e.g. ``python3-gdbm`` on Debian
- ``"dumb"`` - worst performance but directly available with Python 3

.. note::
    If the MacroServer cannot store/retrieve the environment from the
    configured path at startup, it sets up a new unique temporary path,
    stores it permanently in the ``EnvironmentDb`` property and uses it
    from then on. Check the server logs if your environment unexpectedly
    appears empty.

Redis backend
-------------

To store the environment in a `Redis <https://redis.io>`_ database, set the
``EnvironmentDb`` property to a Redis URI, e.g.::

    redis://localhost:6379/0

Both ``redis://`` and ``rediss://`` (TLS) URIs are supported. The keys are
prefixed with the MacroServer name, so multiple MacroServers may share the
same Redis database. This backend requires the ``redis`` Python package
(redis-py) to be installed.

.. note::
    If the Redis server cannot be reached at startup, the MacroServer
    aborts its initialization (it does not fall back to another backend).

Tango DB backend
----------------

To store the environment as free object properties in the Tango database,
set the ``EnvironmentDb`` property to::

    property

In this case the properties are stored under the object named after the
MacroServer. Alternatively you can choose the object name explicitly::

    property:<object name>

This backend does not require any extra service nor package - the
environment lives in the same Tango DB as the rest of your configuration
and is backed up together with it.