Metadata-Version: 2.1
Name: nornir_sql
Version: 0.0.2
Summary: nornir_sql
Author-email: Viktor Kertesz <viktor.kertesz@exxonmobil.com>
Requires-Python: >=3.6,<4
Description-Content-Type: text/x-rst
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: nornir >=3,<4
Requires-Dist: sqlalchemy >=1.4,<2
Requires-Dist: black==20.8b1 ; extra == "dev"
Requires-Dist: pytest-cov==2.11.1 ; extra == "dev"
Requires-Dist: pytest==6.2.3 ; extra == "dev"
Requires-Dist: pylint ; extra == "dev"
Requires-Dist: flit>=3.2 ; extra == "dev"
Requires-Dist: invoke ; extra == "dev"
Requires-Dist: Sphinx<3.6 ; extra == "dev"
Requires-Dist: sphinx_rtd_theme ; extra == "dev"
Project-URL: Documentation, https://viktorkertesz.github.io/nornir_sql
Project-URL: Source, https://github.com/viktorkertesz/nornir_sql
Provides-Extra: dev

====================
Nornir SQL Inventory
====================
Welcome to Nornir SQL inventory plugin!

If your device inventory is spread across SQL database tables and you would like to use it as Nornir inventory, you may
consider looking on this project.

------

| Documentation: `<https://viktorkertesz.github.io/nornir_sql>`__
| Source code: `<https://github.com/viktorkertesz/nornir_sql>`__

------

Installation
------------
.. install_instructions

Install from pipy

.. code-block:: console

    pip install nornir-sql

Install from `GitHUB <https://github.com/viktorkertesz/nornir_sql>`__

.. code-block:: console

    pip install git+https://github.com/viktorkertesz/nornir_sql.git

Install from GitHUB clone for development

.. code-block:: console

    git clone https://github.com/viktorkertesz/nornir_sql.git
    cd nornir_sql
    pip install -e .[dev]

.. install_instructions_end

Simple example
--------------

.. code-block:: python

    from nornir import InitNornir

    host_query = """\
    SELECT ciname AS name, ip AS hostname, region AS 'data.region'
    FROM host_table
    WHERE status='deployed'
    """

    inventory = {
        "plugin": "SQLInventory",
        "options": {
            "sql_connection": "sqlite:///inventory.db",
            "hosts_query": hosts_query,
        }
    }

    nr = InitNornir(inventory=inventory)
    print(nr.inventory.hosts['FW1']['region'])

Configuration
-------------
.. configuration

This plugin is based on SQLAlchemy and supports all databases that SQLAlchemy does.

These configuration options can be used:

#. | ``sql_connection``: SQLAlchemy connection string
   | Format: ``{driver}://[user]:[password]@{DBSERVER}/{DATABASE}``
   | SQLite example:
   | ``sqlite:///somedb.db``
   | MSSQL example with domain user authentication:
   | ``mssql+pymssql://ACME\\dbuser:verysecret@DBSRV1/INFRA``
#. | ``hosts_query``: Select statement which returns hosts inventory elements.
   | The select must return at minimum the ``name`` field!
   | Field names must match the expected Nornir inventory elements!
   | The ``data`` elements are expected in ``data.[element]`` format. Quotation is needed!
   | If ``groups`` are returned, the following ``groups_query`` also has to be specified!
#. | ``groups_query``: Select statement which returns groups inventory elements.
   | Same requirements apply as for the ``hosts_query``.
#. | ``defaults``: This is a dictionary which contains inventory elements. These will be applied to hosts.

.. configuration_end
