####
ORM
####

The Object Relational Model (ORM) defines the mapping between python objects and the SQL database

The objects themselves act as abstractions over whatever underlying filesystem is being used.
For example, a ``Space`` roughly corresponds to an independent fileset in PixStor.


.. warning::

    In general, you should not use these objects directly - use the REST interface instead.

    The REST interface will be (mostly) stable across release versions with only compatible changes being made,
    whereas the backend code may undergo breaking changes between releases.


ORM Diagram
================

.. figure:: _static/ORM_Class_Diagram.png
   :width: 800
   :alt: PixStor Management ORM Diagram

   Fig 1. The Object Relational Model (ORM) Diagram


Comparison to CLI PixStor
================================

To help existing PixStor  administrators, we can roughly match the APMgmt objects and concepts in PixStor as follows:

  - **Datastore**: storage pool
  - **Exposer**: filesystem, samba or nfs share
  - **ILM Step**: file placement policy rule
  - **Profiles**: file placement policy
  - **Space**: independent and dependent filesets
  - **Snapshot**: snapshot
  - **Template**: directory structure, which can include dependent filesets
  - **Provider**: remote storage location
  - **Replica**: sync with a remote location (provider)

.. attention::

    However, the APMgmt objects represent abstract concepts.
    How they are implemented at the filesystem layer does not match completely with PixStor, and is subject to change.


API Documentation
==================

.. only:: internal

    Common
    -------

    Common holds the ORM base classes, as well as some functions used by ORM

    .. automodule:: arcapix.management.orm.common
        :inherited-members:
        :members:


Datastores
-----------

.. automodule:: arcapix.management.orm.datastores
    :inherited-members:
    :members:

Exposers
---------

.. automodule:: arcapix.management.orm.exposers
    :inherited-members:
    :members:


ILM Steps
-----------

In general, the Information Life-Cycle (ILM) ORM isn't used directly, but via the Profile that the particular Step belongs to.

.. automodule:: arcapix.management.orm.lifecycle
    :inherited-members:
    :members:


Profiles
---------

.. automodule:: arcapix.management.orm.profiles
    :inherited-members:
    :members:


Providers
---------

.. automodule:: arcapix.management.orm.providers
    :inherited-members:
    :members:


Replicas
---------

.. automodule:: arcapix.management.orm.replicas
    :inherited-members:
    :members:


Spaces
-------

.. hint::

    If a fileset is created via the Nexus UI, it will only be a Space if it's a 'templated' fileset.
    'Basic' filesets created in the Nexus UI are not Spaces at present.

.. automodule:: arcapix.management.orm.spaces
    :inherited-members:
    :members:


Snapshots
---------

.. hint::

    Snapshots only refer to "one-off" snapshots. Periodic snapshots will be covered (in a future release) by profiles.

.. automodule:: arcapix.management.orm.snapshots
    :inherited-members:
    :members:


Templates
----------

.. automodule:: arcapix.management.orm.templates
    :inherited-members:
    :members: