Configuration¶

SQLTrack configuration currently only refers to the Client. The engine parameter (either postgres or sqlite) determines which engine to use. Engine-specific parameters are passed along, see SQLite and 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 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:

Default config
Config file (if any)
SQLTRACK_DSN_<PARAM> environment variables; see get_env_config() for details
kwargs given to Client

The config loading mechanism is implemented in load_config().

Default config¶

SQLTrack uses the following default configuration:

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

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 configparser to parse config files. The [DEFAULT] section header is implicitly added for convenience. Here’s an example config file:

user = alice
dbname = bob
host = postgres

Default config locations¶

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:

./sqltrack.conf
$XDG_CONFIG_HOME/sqltrack/sqltrack.conf
%APPDATA%/sqltrack/sqltrack.conf
$HOME/.config/sqltrack/sqltrack.conf
$HOME/sqltrack.conf

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

SQLite¶

Set engine=sqlite to use SQLite. The SQLite engine 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 PostgreSQL engine are listed in the libpq documentation. Some of the most important parameters are:

host
dbname
user
password
passfile

libpq also looks for certain environment variables

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.