Configuration
=================================================================

SQLTrack configuration currently only refers to the
:py:class:`.Client`. The ``engine`` parameter (either
``postgres`` or ``sqlite``) determines which :py:mod:`engine
<sqltrack.engines>` to use. Engine-specific parameters are passed
along, see :ref:`configuration:SQLite` and
:ref:`configuration:PostgreSQL` below for details. Configuration
can be given either directly as dictionary and ``kwargs``, or as
path to a config file.

If a dictionary is given, ``kwargs`` can add or overwrite
existing parameters. This option is intended to hardcode the
configuration, thus no other sources of parameters are
considered.

Otherwise, SQLTrack will attempt to load config parameters from a
file. If no path is given, the environment variable
``SQLTRACK_CONFIG_PATH`` is used. If neither path nor
``SQLTRACK_CONFIG_PATH`` are given, some
:ref:`configuration:Default config locations` are checked.
Besides the config file, the default config, environment
variables, and ``kwargs`` are also considered. Conflicts between
parameters set through different methods are resolved in the
following order, from lowest to highest priority:

1. :ref:`configuration:Default config`
2. Config file (if any)
3. ``SQLTRACK_DSN_<PARAM>`` environment variables; see
   :py:func:`.get_env_config` for details
4. ``kwargs`` given to :py:class:`.Client`

The config loading mechanism is implemented in
:py:func:`.load_config`.



Default config
-----------------------------------------------------------------

SQLTrack uses the following default configuration::

    DEFAULT_CONFIG = {
        "engine": "postgres",
        "dbpath": "sqltrack.db",
        "user": getpass.getuser(),
        "dbname": getpass.getuser(),
    }

:py:func:`getpass.getuser` is essentially a more robust version
of ``$USER`` that also considers some fancy alternatives ways to
determine the actual username.



Config file syntax
-----------------------------------------------------------------

SQLTrack uses :py:mod:`configparser` to parse config files. The
``[DEFAULT]`` section header is implicitly added for convenience.
Here's an example config file:

.. code-block:: ini

    user = alice
    dbname = bob
    host = postgres



Default config locations
-----------------------------------------------------------------

:py:class:`.Client` accepts configuration either directly as
dictionary or via ``kwargs``, or a path to a config file. The
path can also be set through the ``SQLTRACK_CONFIG_PATH``
environment variable.

If no path is given explicitly, these default location are
checked, in this order:

1.  ``./sqltrack.conf``
2. ``$XDG_CONFIG_HOME/sqltrack/sqltrack.conf``
3. ``%APPDATA%/sqltrack/sqltrack.conf``
4. ``$HOME/.config/sqltrack/sqltrack.conf``
5. ``$HOME/sqltrack.conf``

The first path that exists is used. If none of them exists
SQLTrack reverts to the default configuration. You can use
:py:func:`.find_config_file` to verify the correct file is used.



SQLite
-----------------------------------------------------------------

Set ``engine=sqlite`` to use SQLite. The :py:mod:`SQLite engine
<sqltrack.engines.sqlite>` accepts one parameter ``dbpath``, the
path where the database is stored. It defaults to
``"sqltrack.db"``.



PostgreSQL
-----------------------------------------------------------------

Set ``engine=postgres`` (the default) to use PostgreSQL.
Parameters accepted by the :py:mod:`PostgreSQL engine
<sqltrack.engines.postgres>` are listed in the `libpq
documentation
<https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-PARAMKEYWORDS>`_.
Some of the most important parameters are:

* host
* dbname
* user
* password
* passfile

``libpq`` also looks for certain `environment variables
<https://www.postgresql.org/docs/current/libpq-envars.html>`_

The PostgreSQL engine also accept a convenience parameter
``schema``. It is an alias for
``options=--search_path=<SCHEMA>``, meaning identifiers (names of
tables, etc.) resolve to the given schema.