.. -*- 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 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/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 comma separated    |                               |
|             | key=value pairs.                                           |                               |
+-------------+------------------------------------------------------------+-------------------------------+


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.

