.. -*- mode: rst -*-

.. _server-database:

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

.. versionadded:: 1.3.0

Several Bcfg2 plugins, including
:ref:`server-plugins-grouping-metadata`,
:ref:`server-plugins-probes-index`, 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-index`.  If you are using the
    database-backed features of either of those plugins, it's
    recommended that you use a higher performance database backend.


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

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

+-------------+------------------------------------------------------------+-------------------------------+
| Option name | Description                                                | Default                       |
+=============+============================================================+===============================+
| engine      | The full name of the Django database backend to use. See   | "django.db.backends.sqlite3"  |
|             | https://docs.djangoproject.com/en/dev/ref/settings/#engine |                               |
|             | for available options                                      |                               |
+-------------+------------------------------------------------------------+-------------------------------+
| name        | The name of the database                                   | "/var/lib/bcfg2/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                          |
+-------------+------------------------------------------------------------+-------------------------------+

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.