upgrade.md

Upgrading Synapse

Before upgrading check if any special steps are required to upgrade from the version you currently have installed to the current version of Synapse. The extra instructions that may be required are listed later in this document.

• Check that your versions of Python and PostgreSQL are still supported.

  Synapse follows upstream lifecycles for Python and PostgreSQL, and removes support for versions which are no longer maintained.

  The website https://endoflife.date also offers convenient summaries.

• If Synapse was installed using prebuilt packages, you will need to follow the normal process for upgrading those packages.

• If Synapse was installed from source, then:

  1. Activate the virtualenv before upgrading. For example, if Synapse is installed in a virtualenv in ~/synapse/env then run:

     source ~/synapse/env/bin/activate

  2. If Synapse was installed using pip then upgrade to the latest version by running:

     pip install --upgrade matrix-synapse

     If Synapse was installed using git then upgrade to the latest version by running:

     git pull
     pip install --upgrade .

  3. Restart Synapse:

     ./synctl restart

To check whether your update was successful, you can check the running server version with:

# you may need to replace 'localhost:8008' if synapse is not configured
# to listen on port 8008.

curl http://localhost:8008/_synapse/admin/v1/server_version

Rolling back to older versions

Rolling back to previous releases can be difficult, due to database schema changes between releases. Where we have been able to test the rollback process, this will be noted below.

In general, you will need to undo any changes made during the upgrade process, for example:

• pip:

  source env/bin/activate
  # replace `1.3.0` accordingly:
  pip install matrix-synapse==1.3.0

• Debian:

  # replace `1.3.0` and `stretch` accordingly:
  wget https://packages.matrix.org/debian/pool/main/m/matrix-synapse-py3/matrix-synapse-py3_1.3.0+stretch1_amd64.deb
  dpkg -i matrix-synapse-py3_1.3.0+stretch1_amd64.deb

Upgrading to v1.47.0

Removal of old Room Admin API

The following admin APIs were deprecated in Synapse 1.34 (released on 2021-05-17) and have now been removed:

• POST /_synapse/admin/v1/<room_id>/delete

Any scripts still using the above APIs should be converted to use the Delete Room API.

Deprecation of the user_may_create_room_with_invites module callback

The user_may_create_room_with_invites is deprecated and will be removed in a future version of Synapse. Modules implementing this callback can instead implement user_may_invite and use the get_room_state module API method to infer whether the invite is happening in the context of creating a room.

We plan to remove this callback in January 2022.

Upgrading to v1.45.0

Changes required to media storage provider modules when reading from the Synapse configuration object

Media storage provider modules that read from the Synapse configuration object (i.e. that read the value of hs.config.[...]) now need to specify the configuration section they're reading from. This means that if a module reads the value of e.g. hs.config.media_store_path, it needs to replace it with hs.config.media.media_store_path.