.. -*- mode: rst -*-
.. vim: ft=rst

.. _server-database:

========================
Global Database Settings
========================

.. versionadded:: 1.3.0

Several Bcfg2 plugins, including
:ref:`server-plugins-grouping-metadata`, :ref:`server-plugins-probes`, and
:ref:`server-plugins-statistics-reporting`, can connect use a relational
database to store data.  They use the global database settings in
``bcfg2.conf``, described in this document, to connect.

.. note::

    Although SQLite is supported as a database, it may cause
    significant thread contention (and a performance penalty) if
    you use SQLite with :ref:`server-plugins-grouping-metadata` or
    :ref:`server-plugins-probes`.  If you are using the database-backed
    features of either of those plugins, it's recommended that you use
    a higher performance database backend.


Separate Reporting Database
===========================

.. versionadded:: 1.4.0

Bcfg2 supports storing the data generated by the
:ref:`server-plugins-statistics-reporting` in a separate
database from the data generated by the other plugins (e.g.
:ref:`server-plugins-grouping-metadata` and :ref:`server-plugins-probes`).
To activate this support, set the ``reporting_engine``,
``reporting_name``, ``reporting_user``, etc.  options in the
``[database]`` section of the config file.  The valid values for the
``reporting_*``  options are the same as for the standard database
options.  See :ref:`server-database-configuration-options` for a full
listing.

.. _server-database-configuration-options:

Configuration Options
=====================

All of the following options should go in the ``[database]`` section
of ``/etc/bcfg2.conf``.

+--------------------+------------------------------------------------------------+---------------------------------------+
| Option name        | Description                                                | Default                               |
+====================+============================================================+=======================================+
| engine             | The name of the Django database backend to use. See        | "sqlite3"                             |
|                    | https://docs.djangoproject.com/en/dev/ref/settings/#engine |                                       |
|                    | for available options (note that django.db.backends is not |                                       |
|                    | included in the engine name)                               |                                       |
+--------------------+------------------------------------------------------------+---------------------------------------+
| name               | The name of the database                                   | "/var/lib/bcfg2/etc/bcfg2.sqlite"     |
+--------------------+------------------------------------------------------------+---------------------------------------+
| user               | The user to connect to the database as                     | None                                  |
+--------------------+------------------------------------------------------------+---------------------------------------+
| password           | The password to connect to the database with               | None                                  |
+--------------------+------------------------------------------------------------+---------------------------------------+
| host               | The host to connect to                                     | "localhost"                           |
+--------------------+------------------------------------------------------------+---------------------------------------+
| port               | The port to connect to                                     | None                                  |
+--------------------+------------------------------------------------------------+---------------------------------------+
| options            | Extra parameters to use when connecting to the database.   | None                                  |
|                    | Available parameters vary depending on your database       |                                       |
|                    | backend. The parameters are supplied as the value of the   |                                       |
|                    | django OPTIONS setting.                                    |                                       |
+--------------------+------------------------------------------------------------+---------------------------------------+
| reporting_engine   | The name of the Django database backend to use for the     | None                                  |
|                    | reporting database. Takes the same values as ``engine``.   |                                       |
+--------------------+------------------------------------------------------------+---------------------------------------+
| reporting_name     | The name of the reporting database                         | "/var/lib/bcfg2/etc/reporting.sqlite" |
+--------------------+------------------------------------------------------------+---------------------------------------+
| reporting_user     | The user to connect to the reporting database as           | None                                  |
+--------------------+------------------------------------------------------------+---------------------------------------+
| reporting_password | The password to connect to the reporting database with     | None                                  |
+--------------------+------------------------------------------------------------+---------------------------------------+
| reporting_host     | The host to connect to for the reporting database          | "localhost"                           |
+--------------------+------------------------------------------------------------+---------------------------------------+
| reporting_port     | The port to connect to for the reporting database          | None                                  |
+--------------------+------------------------------------------------------------+---------------------------------------+
| reporting_options  | Extra parameters to use when connecting to the reporting   | None                                  |
|                    | database. Available parameters vary depending on your      |                                       |
|                    | database backend. The parameters are supplied as the       |                                       |
|                    | value of the django OPTIONS setting.                       |                                       |
+--------------------+------------------------------------------------------------+---------------------------------------+


Database Schema Sync
====================

After making changes to the configuration options or adding a plugin
that uses the global database, you should run ``bcfg2-admin syncdb``
to resync the database schema.