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.71.0

Removal of the generate_short_term_login_token module API method

As announced with the release of Synapse 1.69.0, the deprecated generate_short_term_login_token module method has been removed.

Modules relying on it can instead use the create_login_token method.

Changes to the events received by application services (interest)

To align with spec (changed in MSC3905), Synapse now only considers local users to be interesting. In other words, the users namespace regex is only be applied against local users of the homeserver.

Please note, this probably doesn't affect the expected behavior of your application service, since an interesting local user in a room still means all messages in the room (from local or remote users) will still be considered interesting. And matching a room with the rooms or aliases namespace regex will still consider all events sent in the room to be interesting to the application service.

If one of your application service's users regex was intending to match a remote user, this will no longer match as you expect. The behavioral mismatch between matching all local users and some remote users is why the spec was changed/clarified and this caveat is no longer supported.

Upgrading to v1.69.0

Changes to the receipts replication streams

Synapse now includes information indicating if a receipt applies to a thread when replicating it to other workers. This is a forwards- and backwards-incompatible change: v1.68 and workers cannot process receipts replicated by v1.69 workers, and vice versa.

Once all workers are upgraded to v1.69 (or downgraded to v1.68), receipts replication will resume as normal.

Deprecation of legacy Prometheus metric names

In current versions of Synapse, some Prometheus metrics are emitted under two different names, with one of the names being older but non-compliant with OpenMetrics and Prometheus conventions and one of the names being newer but compliant.

Synapse v1.71.0 will turn the old metric names off by default. For administrators that still rely on them and have not had chance to update their uses of the metrics, it's possible to specify enable_legacy_metrics: true in the configuration to re-enable them temporarily.

Synapse v1.73.0 will remove legacy metric names altogether and it will no longer be possible to re-enable them.

The Grafana dashboard, Prometheus recording rules and Prometheus Consoles included in the contrib directory in the Synapse repository have been updated to no longer rely on the legacy names. These can be used on a current version of Synapse because current versions of Synapse emit both old and new names.

You may need to update your alerting rules or any other rules that depend on the names of Prometheus metrics. If you want to test your changes before legacy names are disabled by default, you may specify enable_legacy_metrics: false in your homeserver configuration.

A list of affected metrics is available on the Metrics How-to page.

Deprecation of the generate_short_term_login_token module API method

The following method of the module API has been deprecated, and is scheduled to be remove in v1.71.0:

def generate_short_term_login_token(
    self,
    user_id: str,
    duration_in_ms: int = (2 * 60 * 1000),
    auth_provider_id: str = "",
    auth_provider_session_id: Optional[str] = None,
) -> str:
    ...

It has been replaced by an asynchronous equivalent:

async def create_login_token(
    self,
    user_id: str,
    duration_in_ms: int = (2 * 60 * 1000),
    auth_provider_id: Optional[str] = None,
    auth_provider_session_id: Optional[str] = None,
) -> str:
    ...

Synapse will log a warning when a module uses the deprecated method, to help administrators find modules using it.

Upgrading to v1.68.0

Two changes announced in the upgrade notes for v1.67.0 have now landed in v1.68.0.

SQLite version requirement

Synapse now requires a SQLite version of 3.27.0 or higher if SQLite is configured as Synapse's database.

Installations using

• Docker images from matrixdotorg,
• Debian packages from Matrix.org, or
• a PostgreSQL database

are not affected.

Rust requirement when building from source.

Building from a source checkout of Synapse now requires a recent Rust compiler (currently Rust 1.58.1, but see also the Platform Dependency Policy).

Installations using

• Docker images from matrixdotorg,
• Debian packages from Matrix.org, or
• PyPI wheels via pip install matrix-synapse (on supported platforms and architectures)

will not be affected.

Upgrading to v1.67.0

Direct TCP replication is no longer supported: migrate to Redis

Redis support was added in v1.13.0 with it becoming the recommended method in v1.18.0. It replaced the old direct TCP connections (which was deprecated as of v1.18.0) to the main process. With Redis, rather than all the workers connecting to the main process, all the workers and the main process connect to Redis, which relays replication commands between processes. This can give a significant CPU saving on the main process and is a prerequisite for upcoming performance improvements.

To migrate to Redis add the redis config, and remove the TCP replication listener from config of the master and worker_replication_port from worker config. Note that a HTTP listener with a replication resource is still required.