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 operationSynapse runs on its database in the background after it starts. It's usually used to rundatabase operations that would take too long if they were run at the same time as schemaupdates (which are run on startup) and delay Synapse's startup too much: populating atable 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'sregister_background_update_controller_callbacks method. Only the first module (in orderof appearance in Synapse's configuration file) calling this method can register backgroundupdate 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 nameof the update, the name of the database, and a flag to indicate whether the backgroundupdate will happen in one go and may take a long time (e.g. creating indices). If this lastargument is set toFalse, 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, inmilliseconds.

The context manager will be exited when the iteration completes. Note that the durationreturned by the context manager is a target, and an iteration may take substantially longeror shorter. If theone_shot flag is set toTrue, the duration returned is ignored.

Note: Unlike most module callbacks in Synapse, this one issynchronous. This isbecause 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 andof the database. The module must return the number of elements to process in this firstiteration.

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 andof the database. The module must return an integer representing the minimum number ofelements to process in this iteration. This number must be at least 1, and is used toensure that progress is always made.

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