synapse/docs/usage/administration/admin_api/background_updates.md

Background Updates API

This API allows a server administrator to manage the background updates being run against the database.

Status

This API gets the current status of the background updates.

The API is:

GET /_synapse/admin/v1/background_updates/status

Returning:

{
    "enabled": true,
    "current_updates": {
        "<db_name>": {
            "name": "<background_update_name>",
            "total_item_count": 50,
            "total_duration_ms": 10000.0,
            "average_items_per_ms": 2.2,
        },
    }
}

enabled whether the background updates are enabled or disabled.

db_name the database name (usually Synapse is configured with a single database named 'master').

For each update:

name the name of the update. total_item_count total number of "items" processed (the meaning of 'items' depends on the update in question). total_duration_ms how long the background process has been running, not including time spent sleeping. average_items_per_ms how many items are processed per millisecond based on an exponential average.

Enabled

This API allows pausing background updates.

Background updates should not be paused for significant periods of time, as this can affect the performance of Synapse.

Note: This won't persist over restarts.

Note: This won't cancel any update query that is currently running. This is usually fine since most queries are short lived, except for CREATE INDEX background updates which won't be cancelled once started.

The API is:

POST /_synapse/admin/v1/background_updates/enabled

with the following body:

{
    "enabled": false
}

enabled sets whether the background updates are enabled or disabled.

The API returns the enabled param.

{
    "enabled": false
}

There is also a GET version which returns the enabled state.

Run

This API schedules a specific background update to run. The job starts immediately after calling the API.

The API is:

POST /_synapse/admin/v1/background_updates/start_job

with the following body:

{
    "job_name": "populate_stats_process_rooms"
}

The following JSON body parameters are available:

• job_name - A string which job to run. Valid values are:
  • populate_stats_process_rooms - Recalculate the stats for all rooms.
  • regenerate_directory - Recalculate the user directory if it is stale or out of sync.