Configuration¶

Configuration files make it easy to quickly set up Broker instances with the expression Broker.named('example') where ‘example’ is the name of a configuration file.

Search Path¶

The databroker looks for configuration files in three locations, in this order:

~/.config/databroker (under the user’s home directory)
python/../etc/databroker, where python is the current Python binary reported by sys.executable (This allows config to be provided inside a virtual environment.)
/etc/databroker/

NOTE: For Windows, we only look in: %APPDATA%\databroker.

A configuration file must be located in one of these directories, and it must be named with the extension .yml. Configuration files are formatted as YAML files.

Examples¶

This configuration file sets up a simple databroker backed by sqlite files. This can be used immediately with no extra setup or installation.

description: 'lightweight personal database'
metadatastore:
    module: 'databroker.headersource.sqlite'
    class: 'MDS'
    config:
        directory: 'some_directory'
        timezone: 'US/Eastern'
assets:
    module: 'databroker.assets.sqlite'
    class: 'Registry'
    config:
        dbpath: 'some_directory/assets.sqlite'

This configuration file sets up a databroker that connects to a MongoDB server. This requires more work to set up.

description: 'heavyweight shared database'
metadatastore:
    module: 'databroker.headersource.mongo'
    class: 'MDS'
    config:
        host: 'localhost'
        port: 27017
        database: 'some_example_database'
        timezone: 'US/Eastern'
assets:
    module: 'databroker.assets.mongo'
    class: 'Registry'
    config:
        host: 'localhost'
        port: 27017
        database: 'some_example_database'

In these examples, the classes used happen to be from the databroker package itself, but classes from other packages can be used just as well, as long as they present the expected API. (This API is not yet documented outside of the source code.)

Registering Handlers¶

Configuration files may optionally include a section specifying ‘handlers’, classes that load externally stored data. These may be registered at runtime or here in configuration.

handlers:
    FOO:
        module: 'databroker.assets.path_only_handlers'
        class: 'RawHandler'

Coping with Moved Files or Different Mount Points¶

Optionally, you may set a root_map, which comes in handy when the handlers involves mounted files that have been moved to a different mount point in the file system.

root_map:
    old_root: new_root
    old_root2: new_root2

where old_root and old_root2 are the old mount points and new_root and new_root2 their respective new mount points.

Warning

Future versions of databroker will provide better support for multiple asset registries and multiple sources of Event data, and this configuration file format will change. If possible, old configuration files will still be supported.

Helper Functions¶

See Configuration Utilities in the API documentation.