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 using pip then upgrade to the latest version by running:

  pip install --upgrade matrix-synapse

• If Synapse was installed from source, then:

  1. Obtain the latest version of the source code. Git users can run git pull to do this.

  2. If you're running Synapse in a virtualenv, make sure to activate it before upgrading. For example, if Synapse is installed in a virtualenv in ~/synapse/env then run:

     source ~/synapse/env/bin/activate
     pip install --upgrade .

     Include any relevant extras between square brackets, e.g. pip install --upgrade ".[postgres,oidc]".

  3. If you're using poetry to manage a Synapse installation, run:

     poetry install

     Include any relevant extras with --extras, e.g. poetry install --extras postgres --extras oidc. It's probably easiest to run poetry install --extras all.

  4. 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.62.0

New signatures for spam checker callbacks

As a followup to changes in v1.60.0, the following spam-checker callbacks have changed signature:

• user_may_join_room
• user_may_invite
• user_may_send_3pid_invite
• user_may_create_room
• user_may_create_room_alias
• user_may_publish_room
• check_media_file_for_spam

For each of these methods, the previous callback signature has been deprecated.

Whereas callbacks used to return bool, they should now return Union["synapse.module_api.NOT_SPAM", "synapse.module_api.errors.Codes"].

For instance, if your module implements user_may_join_room as follows:

async def user_may_join_room(self, user_id: str, room_id: str, is_invited: bool)
    if ...:
        # Request is spam
        return False
    # Request is not spam
    return True

you should rewrite it as follows:

async def user_may_join_room(self, user_id: str, room_id: str, is_invited: bool)
    if ...:
        # Request is spam, mark it as forbidden (you may use some more precise error
        # code if it is useful).
        return synapse.module_api.errors.Codes.FORBIDDEN
    # Request is not spam, mark it as such.
    return synapse.module_api.NOT_SPAM

Upgrading to v1.61.0

Removal of deprecated community/groups

This release of Synapse will remove deprecated community/groups from codebase.

Worker endpoints

For those who have deployed workers, following worker endpoints will no longer exist and they can be removed from the reverse proxy configuration:

• ^/_matrix/federation/v1/get_groups_publicised$
• ^/_matrix/client/(r0|v3|unstable)/joined_groups$
• ^/_matrix/client/(r0|v3|unstable)/publicised_groups$
• ^/_matrix/client/(r0|v3|unstable)/publicised_groups/
• ^/_matrix/federation/v1/groups/
• ^/_matrix/client/(r0|v3|unstable)/groups/

Upgrading to v1.60.0

Adding a new unique index to state_group_edges could fail if your database is corrupted

This release of Synapse will add a unique index to the state_group_edges table, in order to prevent accidentally introducing duplicate information (for example, because a database backup was restored multiple times).

Duplicate rows being present in this table could cause drastic performance problems; see issue 11779 for more details.

If your Synapse database already has had duplicate rows introduced into this table, this could fail, with either of these errors: