[Advanced] Storage Plugin development

A storage plugin is the glue code that tells Errbot how to store the persistent data the plugins and the bot itself are producing. Starting with Errbot 3.3.0, storage plugins can be developed out of the main repository. This documentation is there to guide you making a new storage plugin so you can connect Errbot to your favorite database.

Architecture

Storage plugins are instantiated in 2 stages.

The first stage is storage plugin discovery and is similar to normal bot plugins:

  • Errbot scans errbot/storage and config.BOT_EXTRA_STORAGE_PLUGINS_DIR for .plug files pointing to plugins implementing StoragePluginBase.

  • Once the correct plugin from config.STORAGE is found, it is built with the bot config as its __init__ parameter.

  • By calling super().__init__ on StoragePluginBase, Errbot will populate self._storage_config from config.STORAGE_CONFIG. This configuration should contain the custom parameters needed by your plugin to be able to connect to your database/storage ie. url, port, path, credentials … You need to document them clearly so your users can set config.STORAGE_CONFIG correctly.

  • As you can see in StoragePluginBase, you just have to implement the open method there.

The second stage is opening the storage, which is done using the open method:

  • Various parts of Errbot may need separate key/value storage, the open method has a namespace to track those. For example, the internal BotPluginManager will open the namespace core to store the bot plugins and their config, the installed repos, etc.

  • open needs to return a StorageBase, which exposes the various actions that Errbot can call on the storage (set, get, …).

  • You don’t need to track the lifecycle of the storage, it will be enforced externally: no double-close, double-open, get after close, etc.

Plugins are collections.MutableMapping and use StoreMixin as an adapter from the mapping accessors to the StorageBase implementation.

Testing

Storage plugins are completely independent from Errbot itself. It should be easy to instantiate and test them externally.

Example

You can have a look at the internal shelf implementation ShelfStorage