Creating a New Database

The databroker is above all an interface, which is not beholden to a specific storage technology. Several different storage backends are included in the databroker package (MongoDB, JSON, sqlite, HDF5) and fully tested. But as of this writing, the maintainers of databroker rely exclusively on MongoDB for large-scale production, and it has an additional production-oriented feature, described here. Therefore, these instructions apply to the MongoDB storage backend only. Brokers configured with other backends may ignore these instructions.

Creation in MongoDB

MongoDB itself does not require an explicit step for creating a new database. It will quietly create one for you the first time you connect to it. This can be dangerous (or, at best, messy) because an unnoticed typo can result in an accidental, separate database. To enforce more explicit intention in this process, databroker looks for a special “sentinel” collection when it connects to a Mongo database. If it does not find one, it will refuse to connect to that database until the user installs the sentinel — thereby affirming, “Yes, I intend to create a new database.” The sentinel also contains a version number, which may be useful for migrations in the event of any future changes to the specification.

The creation of a database in MongoDB is simple. Simply create a configuration as described in Configuration. The only requirement is that the MongoDB instance is running on the machine specified. The database need not exist yet. The next step is to install a version sentinel. This is done as follows:

import databroker

# Instantiate databroker instance
from databroker import Broker
db = Broker.named(config_name)

# install sentinels
databroker.assets.utils.install_sentinels(db.reg.config, version=1)

where config_name is the name of your configuration and version=1 refers to the version of asset registry you are using (it is currently 1 as of this writing).