+ +

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.

+ +