This database module stores the opsdroid memory into “state events” in a matrix room. These state events form part of the history of the room and can be queried from the room at any time, like the rest of a room, they are replicated over all participating servers in the room, making them a robust way of storing json objects.


Install opsdroid with the database_matrix and connector_matrix extras to use the matrix database, also install with connector_matrix_e2e to use the connector and database in encrypted rooms. The matrix connector must be configured to be able to use the matrix database, see that page of the docs for more information.


A minimal configuration is:


In its default configuration the database will put events into the room named “main” in the connector configuration.

An example of all the configuration options, with their default values is:

    default_room: main
    single_state_key: True
    should_encrypt: True

In general we recommend setting single_state_key: False, the default is True for backwards compatibility reasons but the downsides of setting it to False have now been removed.


Interacting with opsdroid databases happens through opsdroid’s memory, see the memory page for more details.

An addition to the usual use of memory, the matrix database provides a context manager memory_in_room to perform some operations in a different rooms. The room can be specified with a matrix room alias, the name of a room in the connector config or a matrix room id.

db = opsdroid.get_database("matrix")
with db.memory_in_room(new_room):

Use room state in the given room rather than the default.

There is also a decorator for skill functions to use the memory of the room where the event was received from. It uses the .target attribute of the third argument to the skill function, which is the matrix event.

from opsdroid.database.matrix import memory_in_event_room

async def skill_func(opsdroid, config, message):
opsdroid.database.matrix.memory_in_event_room(wrapper=None, enabled=None, adapter=None, proxy=<class 'FunctionWrapper'>)

Use room state from the room the message was received in rather than the default.

How it Works

State Events and State Keys

Matrix state events are used to store metadata about the room, such as its members, its name and topic. The matrix database uses state events to store arbitary data you save to opsdroid memory. In this section we describe a little about how this fits into the matrix protocol for those who are interested.

Matrix state events have three main components:

  • a type, which for the opsdroid matrix database is dev.opsdroid.database

  • a “state key” which distinguishes state events with the same type

  • content which is a json object

Matrix state events form a key value store where the key is a combination of the type and state event, i.e. ("dev.opdroid.database", "") or ("dev.opsdroid.database", "reminders").

In the default configuration the state key is not used, the whole database is stored in a single json object in the content of the dev.opsdroid.database event with state_key: "". This means that if one key is changed then the whole event is resent. When the single_state_key: False option is set, the key given to the opsdroid memory is used as the state key, this allows directly querying the matrix API for the value corresponding to that key.


In encrypted Matrix rooms, state events (used by the database) are not encrypted. This means that anything put into the matrix database in an encrypted room would not be encrypted. To prevent this the matrix database sends the values you put into your database into the room as regular events, which are encrypted, and then references these events from the database (which is still a state event). This has two effects you should be aware of:

  1. The keys in your database are not encrypted, do not put sensitive information in the key.

  2. If opsdroid can’t decrypt the event, it will be dropped from the database. This means that if you need long term storage in your encrypted rooms you must take steps to save the matrix connectors store (where the decryption keys are kept), so back up your store and keep it safe!

If you would rather your database not be encrypted in an encrypted room, you can set the should_encrypt: False config option.