synapse/docs/modules/background_update_controller_callbacks.md

Background update controller callbacks

Background update controller callbacks allow module developers to control (e.g. rate-limit) how database background updates are run. A database background update is an operation Synapse runs on its database in the background after it starts. It's usually used to run database operations that would take too long if they were run at the same time as schema updates (which are run on startup) and delay Synapse's startup too much: populating a table with a big amount of data, adding an index on a big table, deleting superfluous data, etc.

Background update controller callbacks can be registered using the module API's register_background_update_controller_callbacks method. Only the first module (in order of appearance in Synapse's configuration file) calling this method can register background update controller callbacks, subsequent calls are ignored.

The available background update controller callbacks are:

on_update

First introduced in Synapse v1.49.0

def on_update(update_name: str, database_name: str, one_shot: bool) -> AsyncContextManager[int]

Called when about to do an iteration of a background update. The module is given the name of the update, the name of the database, and a flag to indicate whether the background update will happen in one go and may take a long time (e.g. creating indices). If this last argument is set to False, the update will be run in batches.

The module must return an async context manager. It will be entered before Synapse runs a background update; this should return the desired duration of the iteration, in milliseconds.

The context manager will be exited when the iteration completes. Note that the duration returned by the context manager is a target, and an iteration may take substantially longer or shorter. If the one_shot flag is set to True, the duration returned is ignored.

Note: Unlike most module callbacks in Synapse, this one is synchronous. This is because asynchronous operations are expected to be run by the async context manager.

This callback is required when registering any other background update controller callback.

default_batch_size

First introduced in Synapse v1.49.0

async def default_batch_size(update_name: str, database_name: str) -> int

Called before the first iteration of a background update, with the name of the update and of the database. The module must return the number of elements to process in this first iteration.

If this callback is not defined, Synapse will use a default value of 100.

min_batch_size

First introduced in Synapse v1.49.0

async def min_batch_size(update_name: str, database_name: str) -> int

Called before running a new batch for a background update, with the name of the update and of the database. The module must return an integer representing the minimum number of elements to process in this iteration. This number must be at least 1, and is used to ensure that progress is always made.

If this callback is not defined, Synapse will use a default value of 100.