When a Matrix upgrade project needs outside help
Matrix upgrade and support is the ongoing work of moving Synapse and its dependencies forward safely and keeping them supported. For most organizations that run Synapse, that means tracking upstream releases, planning each upgrade, testing it against real workloads, and keeping the Python and PostgreSQL versions under the homeserver within upstream support. The reader who needs outside help is usually facing one of three situations: a Synapse deployment that has fallen several releases behind, a Python or PostgreSQL version approaching end of life, or a team that has to keep messaging running through a large change such as a hosting move or a new identity setup.
A common split is visible across organizations that run Matrix. Small teams with prior Synapse experience often handle routine minor releases in-house, reading the upgrade notes, applying the change in a staging environment, and rolling forward during a planned window. This works well when the deployment is a single homeserver, uses SQLite or a simple PostgreSQL setup, and has no workers, federation partners or single sign-on to re-verify. Organizations with federation, a worker layout behind Redis, SSO through OpenID Connect, SAML or CAS, or compliance obligations tend to bring in a partner for the riskier upgrades and for ongoing cover, because each of those areas adds test cases that a small internal team may not be able to run before every release.
The upgrade notes are the first thing to read, and they carry the decision points that matter most. Confirm the PostgreSQL and Python versions your current release requires and compare them with your servers. Synapse 1.143.0 and later require PostgreSQL 14 or newer, and 1.142.0 and later require Python 3.10 or newer, so a deployment that skipped those dependency upgrades may need to change them before the homeserver itself can move. Check whether the target release includes database schema changes, because the upgrade notes warn that rolling back can be difficult after such changes. If it does, your plan needs a verified PostgreSQL backup taken immediately before the upgrade and a decision on whether a restore is an acceptable fallback.
Ask a potential partner what ongoing support covers, because the phrase means different things to different providers. Useful questions include who watches upstream releases and security notices, how each upgrade is tested against your workers, clients, bridges and identity provider, who approves a change to production, and how an emergency patch is handled outside the normal window. Ask how custom pieces such as pluggable modules or bots are reviewed when the homeserver changes. Ask for the test evidence that will be produced after each upgrade, and confirm which parts of the deployment remain under your team's administration. Any answer that leaves these points open should be clarified in the written scope before work begins.
The right answer depends on your team's experience with Synapse, the complexity of your deployment and how much downtime your users can absorb. If you can name the person who will read each upgrade's notes, run the verification steps and make the rollback decision, an in-house routine may be enough for minor releases. If that person does not exist, or if the next upgrade crosses a dependency boundary, a fixed-scope upgrade with a defined support period is often the lower-risk path. Plan the decision early, because the most expensive upgrades are the ones started after a dependency has already passed its end of life.
What a Matrix upgrade and support engagement includes
A Matrix upgrade engagement moves through the same sequence each time: confirm what the release requires, plan a path back, change the components in order, and prove that clients and federation still work. Ongoing support is a separate retainer that picks up after the handover, and its scope is agreed in writing.
Version and dependency assessment
We compare your current Synapse version, Python runtime, PostgreSQL version and worker layout against the requirements stated in the target release notes. Synapse drops Python and PostgreSQL versions once they reach upstream end of life, so this step shows which dependencies must move first. The deliverable is a written assessment listing each gap, the required change, and the release notes it depends on.
Upgrade plan with rollback position
The plan sets the upgrade order, the change windows, the owners for each step, and the verification gates between them. Because Synapse schema changes between releases can make rollback difficult, the plan records where a rollback is possible, where it is not, and what restore point covers the gap. The deliverable is a written plan your change board can approve before any production change.
Staged upgrade of core components
We upgrade the main process, workers, Redis and PostgreSQL in a staged order in a non-production copy first, then in production under the approved plan. Each component is checked for version compatibility with the others before it moves on. The deliverable is a change record for every stage, including versions before and after, configuration changes and any issues found during the run.
Post-upgrade verification of clients and federation
After the upgrade we test login and messaging from the client versions your users run, including Element clients and any custom builds, and check media upload and sync. Federation is verified only if your policy allows it, using the federation domain allow list and the port and delegation settings you chose. The deliverable is a test record showing what passed, what failed and what was fixed.
Operations handover
The handover gives your administrators the upgraded configuration, the updated runbook, the backup and restore steps that match the new versions, and the monitoring checks to watch after go-live. We walk your team through each step so they can repeat the upgrade in future releases. The deliverable is the runbook and a recorded handover session agreed in the scope.
Ongoing support retainer
Support is sold as a separate retainer covering future upgrades, patch monitoring for the components you run, and incident response when something breaks. The retainer scope, response expectations and what counts as an incident are agreed in writing before the retainer starts. Ask for the written scope before you compare retainer quotes, because coverage differs between providers.
What drives Matrix upgrade effort and how to keep it down
This table lists the factors that most change how much work a Synapse upgrade takes, why each one adds effort, and one practical way to reduce it. Read it before scoping an upgrade so the scope reflects your topology, not just the target version number. The main takeaway is that most effort comes from the number of environments, the database and runtime jump, and the integrations you run around Synapse, so reducing those first shortens the window more than any single tuning step.
| Driver | Why it adds effort | How to keep it down |
|---|---|---|
| Number of Synapse instances and environments | Each production, staging and test instance needs its own database check, config review and post-upgrade testing, so effort scales with the count. | Keep a staging copy that mirrors production config and data, upgrade it first, and reuse the same runbook for every environment. |
| Worker topology (generic workers, Redis and replication) | The main process and every worker must run compatible versions and share Redis replication settings, so a partial upgrade can break message flow between processes. | Upgrade all workers in one planned window, record the worker configuration before starting, and confirm Redis connectivity and replication after each step. |
| PostgreSQL version and database size | Large databases take longer to migrate, and schema changes between releases can make rollback difficult, so backup and restore timing becomes part of the window. | Confirm the current PostgreSQL version and a tested backup and restore procedure before starting, and measure migration time on the staging copy. |
| Jump crosses the Python 3.10 or PostgreSQL 14 minimums | Synapse 1.142.0 and later need Python 3.10 or newer, and 1.143.0 and later need PostgreSQL 14 or newer, so older hosts may need OS or database upgrades first. | Check your Python and PostgreSQL versions against the upgrade notes before choosing a target release, and schedule runtime upgrades as separate, earlier changes. |
| Federation status | Federated servers expect a compatible Synapse version, and a restart or schema migration can create a backlog of events to catch up on after the window. | Consider limiting federation during the window through federation_domain_whitelist, then reopen once the server is verified, and confirm the federation listener on port 8448 or delegated port 443 after restart. |
| SSO path (OIDC, SAML2, CAS or Matrix Authentication Service) | Each path has its own config and upstream provider settings, and MAS is a separate service that must be upgraded alongside Synapse, so login tests multiply. | Pin the identity provider configuration in version control, and test a fresh login, token refresh and logout for each path on staging before production. |
| Custom modules and bots | Pluggable modules and bots depend on Synapse internals and Python packages, and they can break silently when the homeserver API changes. | Pin module and dependency versions, keep them in a separate test run, and check each one against the new release notes before promoting it. |
| Client fleet and media storage | Element and other clients may need updates for compatibility, and large media stores slow backups, migrations and media-related checks. | Set a minimum client version in the rollout plan, and measure media store size and backup duration on the staging copy before scheduling the window. |
Why Synapse upgrades break and why rollback is hard
The main reason Synapse upgrades are hard to reverse is that database schema changes ship between releases. The upgrade notes warn that rolling back can be difficult for this reason, which makes the backup and restore plan matter more than the upgrade command itself. Once a newer release has migrated the PostgreSQL schema, an older Synapse build may not run against it, so reverting the code alone is often unsafe. The reliable way back is usually a database restore from a backup taken before the upgrade, paired with the matching Synapse version, configuration and signing keys. Before you schedule any change, read the target release notes and confirm whether that release includes migrations you cannot reverse, because the answer determines your restore window and approval path.
Upstream end-of-life policy forces dependency moves, and those moves often have to happen first. Synapse drops support for Python and PostgreSQL versions once they reach upstream end of life, so a homeserver release can require a runtime your host does not yet have. The supplied requirements show the pattern: Synapse 1.142.0 and later require Python 3.10 or newer, and 1.143.0 and later require PostgreSQL 14 or newer. A host running an older PostgreSQL major version may need a database upgrade before the Synapse upgrade is possible at all. Treat operating system, Python and PostgreSQL changes as separate changes with their own backups and rollback steps. Confirm the exact requirements for each target release in its notes before you book a window.
This is why the rollback plan must be finished before the upgrade is scheduled. At minimum, the plan should name the PostgreSQL backup method and frequency, the point in time that will be restored, where media files and signing keys are stored, and the exact Synapse and dependency versions to reinstall. Restore the backup into a staging environment and time the process, so the team knows how long users will be affected if a rollback is needed. Assign a decision owner who can call the rollback within a set window, and record who approves each step. Ask your internal team or any partner to prove the restore works on your own data volumes and a copy of your production configuration, not only on an empty test database.
Custom modules and worker configuration can break separately from the core upgrade, so test them as their own items. Synapse pluggable modules and bots may depend on internal interfaces that change between releases, and a module that loads cleanly on the old version can fail at startup on the new one. Worker deployments add another surface: the main process, the generic worker, the Redis connection used for replication and the listener settings must all match the new release. Build a test matrix that covers at least one client login, room messages, federation if it is enabled, media upload and each worker type you run. Confirm module compatibility with the target release notes and the module authors before scheduling, and keep module versions pinned so a rollback does not pull in changes you did not test.
How a Matrix upgrade project runs, phase by phase
The sequence moves a Synapse deployment to a chosen target release in small, checked stages, so each phase produces a record the next one depends on. Nothing reaches production until the same steps have passed on a restored copy of the production database.
Inventory the current deployment
DeployOpen engineers record the Synapse version, the Python and PostgreSQL versions, the configuration files, the worker layout and Redis setup, installed modules, bridges, and the clients your users run. They also capture the reverse proxy and federation settings. The output is a written baseline that names every component and its current version, plus a list of anything the upgrade will not touch. The step is done when your team has reviewed and signed off the baseline.
Select the target release
Engineers read the upstream upgrade notes for every release between your current version and the candidate, including any notes that warn rollback may be difficult because of schema changes. They check the candidate's Python and PostgreSQL requirements against your hosts and flag any dependency that upstream no longer supports. Your team approves the chosen version and the reasons for it. The output is a target version, a dependency plan, and a list of breaking changes that affect your configuration or modules.
Rehearse the upgrade on staging
Engineers restore a recent copy of the production database into a staging environment that mirrors your worker layout and configuration. They run the schema and application upgrade against that copy and log every error and warning. Custom modules, bridges and client connections are tested against the upgraded staging server. The rehearsal is done when the upgrade completes cleanly from the restored copy and every issue found has a fix or a documented workaround.
Prove the rollback path
Before the change window, the team confirms that the rollback path works on staging. They take a database backup immediately before the change, confirm that it restores, and write the steps to return to the previous release. Because schema changes can make rollback hard, the plan states the point of no return and names the person who decides when it is reached. The output is an approved change plan, a tested backup, and a go or no-go checklist agreed with your change approvers.
Upgrade production in controlled order
Engineers apply the change in the order set out by the baseline and the rehearsal, handling the main process and workers according to the documented layout. Each component is changed and checked before the next one is touched. Your operators watch logs and replication health throughout the window. The output is a production server running the target release, a log of every change made, and a record of any deviation from the plan.
Verify the upgraded service
Engineers run a fixed test script against production. It covers sign-in through your identity provider, sending and receiving messages in encrypted and unencrypted rooms, uploading and viewing media, federation status with the domains you allow, and worker health across the main process, Redis and each worker. Clients on the versions your users run are checked as well. The step closes when every test passes or has an agreed disposition, and the results are written down.
Hand over and set support cadence
DeployOpen hands over the runbook, the final baseline, the rollback record and the monitoring checks your team will use. Your operators walk through the upgrade with DeployOpen engineers, and each open item gets a named owner. If you take a support retainer, the agreed cadence sets how often upstream releases are reviewed, when upgrades are scheduled, and how security patches are handled. Ask for the cadence and its response terms in the written scope.
Testing workers, federation and clients after a Synapse upgrade
The post-upgrade test set should be written and agreed before the maintenance window opens, because a Synapse upgrade is only confirmed working when each check has a defined expected result. Without that list, teams tend to test whatever is convenient on the day and then accept a partial picture. Decide who signs off the window, which checks are blocking, and what happens if a check fails and the team has to decide between fixing forward and rolling back. Rollback may be difficult after schema changes, so that decision needs to be made in advance, not during the window.
Start with the process layout. If the deployment uses workers, confirm that the main process and every generic worker report healthy after restart, and that each worker is connected to Redis and receiving replication traffic. Check that client sync, federation traffic and event persistence are all being served by the workers you expect, and that no worker is silently idle or repeatedly restarting. Review the logs for replication errors and for any warnings about configuration keys that have been renamed or removed in the release you are moving to. Your Synapse upgrade notes for each version in the path will name these items.
Client and login checks come next. Sign in with a sample of accounts on Element and on any other clients your users rely on, covering desktop, web and mobile where they are in use. Send and receive messages in encrypted and unencrypted rooms, confirm that existing sessions still sync, and verify that device verification and key backup behave as users expect. Test each SSO path in use, whether that is OIDC or SAML configured directly in Synapse, CAS, or Matrix Authentication Service with an upstream provider. Log in, log out and refresh a session through each one, because identity configuration is a common casualty of a version change.
Media and federation require their own checks. Upload and download files of several sizes and types, and confirm that thumbnails and previews render, since media handling depends on storage paths and on the media repository configuration. For federation, confirm that the configured federation_domain_whitelist or delegation still resolves as intended, that a partner server can exchange messages with you in both directions, and that the federation listener on port 8448 or the delegated port 443 is reachable only from the networks you have approved. Also run a check on the administration API from an approved admin host, and confirm that it is not reachable from outside the expected network.
Treat the results as the evidence the organization keeps. Record the version and configuration in use, the date and time of each check, the account or room used, the observed result, and the name of the person who accepted it. Store these records alongside the change ticket and the backup taken before the window, so that auditors, internal reviewers or the next operator can see what was tested and what was accepted. Ask any partner who supports the upgrade to state in writing which tests they will run, which they expect you to run, and what evidence they will hand over at the end of the window.
Which Matrix upgrade tasks stay in-house and which a partner takes
This table compares each stage of a Synapse upgrade with the team that usually owns it and the skill it needs. Read it as a split of responsibilities, not a fixed contract, because the right line depends on your staffing and change process. The main takeaway is that release ownership and go or no-go decisions usually stay with your team even when a partner runs the rehearsal and the production change.
| Upgrade task | Usually owned by | Skill it needs |
|---|---|---|
| Release tracking and upgrade planning | In-house, with partner input | Synapse release notes review, Synapse configuration knowledge, risk judgment |
| Python and PostgreSQL dependency upgrades | Partner or platform engineering | Linux administration, PostgreSQL administration, Python runtime management |
| Redis version and configuration checks | Partner or platform engineering | Redis administration, Synapse worker replication knowledge |
| Staging rehearsal of the upgrade | Partner executes, in-house reviews results | Synapse configuration, scripted upgrade and rollback steps, PostgreSQL backup handling |
| Production change execution | Partner executes under your change approval | Change management, maintenance window coordination, runbook discipline |
| Worker and federation verification | Partner executes, in-house confirms policy | Synapse workers, federation and delegation testing, DNS and port 8448 or 443 checks |
| Client regression testing | In-house users with partner test scripts | Element client use, test case design, knowledge of your user workflows |
| SSO and module updates | Partner or identity team, in-house approves | Identity federation (OIDC, SAML or CAS), Synapse module configuration, identity provider administration |
| On-call response and rollback decisions | In-house on-call, partner on retainer | Incident response, Synapse log analysis, database restore awareness |
What goes wrong in Matrix upgrades and how to prevent it
Most Matrix upgrade incidents trace back to a short list of causes: untested backups, dependency floors that were not planned for, and environments that do not behave like production. Each card below names one failure, the prevention step that addresses it, and the evidence to request from any partner before work begins.
Untested database backups
A PostgreSQL backup that has never been restored is a hope, not a rollback plan. Synapse upgrades can change the database schema in ways that make reverting to an earlier release difficult, so the restore path matters more than the backup job. Prevention: restore the latest backup into an isolated environment before each upgrade and time the restore. Ask a partner for the restore test record, the recovery point they committed to, and the procedure for rolling back a failed schema migration.
Crossing dependency minimums unprepared
Recent Synapse releases require newer minimums: 1.142.0 and later need Python 3.10 or newer, and 1.143.0 and later need PostgreSQL 14 or newer. Upgrading Synapse first, then discovering the host runs an older interpreter or database, forces an emergency change. Prevention: read the upgrade notes for every release between your current version and the target, then move Python or PostgreSQL first in staging. Ask for a dependency inventory showing current and required versions, and the order of changes.
Custom modules failing silently
Synapse pluggable modules, custom templates and bots can break after a release without raising an error that anyone sees. Features stop working for users while the server reports healthy. Prevention: keep a register of every custom component with its pinned version, and run a scripted check of each one against the new release in staging. Ask a partner for the module register, the test cases covering each custom component, and how a failed check blocks promotion to production.
Worker configuration drift
In a worker deployment, the main process and each worker must agree on configuration, replication settings and Redis connection details. Hand edits on one host, or a worker added after the last release, lead to partial failures that appear as lost events or stalled clients. Prevention: manage all worker configuration from one source of truth and compare rendered files against it after each change. Ask for the configuration management approach, the drift check method, and the list of hosts and worker types it covers.
SSO callbacks breaking after changes
Login through OIDC, SAML or CAS depends on exact callback URLs registered with the identity provider. A redirect change, a new hostname, or a provider migration can stop every sign-in while the homeserver itself stays up. Prevention: inventory every registered redirect URI, test a full login with a test account in staging after each change, and keep the previous provider configuration available for rollback. Ask a partner which provider settings they verify and how they confirm sign-in for each identity source.
Federation broken by server name changes
The server_name setting fixes how user IDs and room identifiers are formed, and federation depends on it along with delegation and the choice between port 8448 and port 443. Changing it after launch affects identities already in use. Prevention: decide server name, delegation and the federation policy before go-live, then verify the federation endpoints and federation domain list after any networking change. Ask for the federation test record, including the delegation and certificate checks used.
Running out of change windows
When staging does not match production in versions, data volume, worker layout or identity setup, each upgrade needs extra validation at the last moment, and the approved change windows run out. Prevention: keep staging on the same release, topology and identity configuration as production, and refresh it from a sanitized production copy on a set cadence. Ask a partner how they keep staging aligned, how they handle data protection in copies, and how many windows a typical upgrade cycle has been planned to use.
What Matrix upgrade and support costs after go-live
Recurring cost after go-live comes from five lines, and each one needs a named owner before the system goes into production. The first is support coverage: either a support retainer with your implementation partner or internal on-call time, with someone reachable when a login or federation fault stops messages from flowing. The second is a staging environment that matches production closely enough to rehearse each Synapse upgrade. The third is PostgreSQL and Redis maintenance, including minor upgrades, vacuuming, capacity checks and, where workers are in use, Redis monitoring. The fourth is backup storage and regular restore tests. The fifth is internal skill: someone must read the release and upgrade notes and decide what each change means for your configuration.
The one-time and recurring split is easier to plan if you separate build work from run work. One-time costs typically include the initial deployment, the upgrade runbook, the client, worker and integration test plan, the backup and restore design, and a first full rehearsal of an upgrade on a copy of production data. Recurring costs repeat with every release cycle: reading notes, applying the upgrade in staging, running the test plan, scheduling a maintenance window and checking the result afterward. How often you take releases is a policy decision you set, and that choice moves the recurring figure more than almost any other. Backup and media storage also grow with usage, so their cost rises over time.
Dependency currency is the cost driver teams most often underestimate. The Synapse upgrade notes state that from version 1.143.0 onward PostgreSQL 14 or newer is required, and from 1.142.0 onward Python 3.10 or newer is required. The same notes say Synapse drops support for Python and PostgreSQL versions once they reach upstream end of life. A homeserver release can therefore force an operating system or database upgrade on a date you did not choose. Before each planned release, have your team compare the current Python and PostgreSQL versions with the stated minimums, and confirm the requirements in the release notes at that time, because they change between releases.
Subscription choices change what support is included, so confirm the terms before you budget. Element Server Suite comes in several forms: ESS Community, which is free and aimed at non-professional deployments and evaluations, and ESS Pro, aimed at professional and government use. Element also sells Synapse Pro and AGPL exception licenses for Synapse, which is the open-source server licensed under AGPL-3.0. Entitlements such as upgrade assistance, response times and warranties vary by agreement, and they decide whom you call and what you receive when a release breaks something. Ask Element in writing which entitlements apply to your edition, user count and hosting model. Do not assume that a community deployment carries the same support as a paid agreement.
When you request quotes from a partner, ask for recurring items separately from the build. Ask who performs each upgrade rehearsal, whether the staging environment is included or billed as infrastructure, who performs restores during an incident and how often restores are tested, and who reads release notes and decides on configuration changes. Ask what happens when a release requires a PostgreSQL or Python change outside the agreed scope, and who makes the rollback decision given the warning that schema changes can make rollback difficult. DeployOpen offers ongoing support, upgrades and continuous testing as retainers, and the written scope defines the boundaries of each.
How upgrades differ by starting point and environment
A single host running Synapse is the simplest starting point, and the upgrade is mostly a matter of stopping the process, taking a backup, installing the new package and starting it again. The database choice matters more than it first appears. Synapse documents SQLite as supported, but PostgreSQL is recommended for production, so a team that began on SQLite for a pilot should plan a database migration before the service carries real user traffic.
Extra steps and decisions:
- Decide whether to move from SQLite to PostgreSQL before the upgrade or as a separate change, so that a failure is easy to isolate.
- Confirm the host runs Python 3.10 or newer for Synapse 1.142.0 and later, and PostgreSQL 14 or newer for Synapse 1.143.0 and later.
- Take a consistent backup of the database and media store, and test a restore on a separate host before changing the production process.
- Read the upgrade notes for every release between your current version and the target, since schema changes may make rollback difficult.
- Choose a maintenance window and a rollback point, such as a database snapshot taken just before the schema migration runs.
Check the Python and PostgreSQL versions the operating system provides first, because many failed upgrades on a single host trace back to an interpreter or database that is older than the release requires.
A worker-based deployment splits Synapse into a main process and several workers, with Redis relaying replication between them and a load balancer routing client, federation and media traffic. An upgrade now touches every process, and processes running different Synapse versions can fail in ways a single host would never show. The restart order, the placement of Redis and the routing rules at the load balancer all become part of the change.
Extra steps and decisions:
- Confirm the target release supports your worker layout, and check the workers documentation for each worker type you run, including the generic worker that handles client, federation and event traffic.
- Decide the restart order and whether a short period of mixed versions is acceptable. A planned sequence for the main process and workers reduces replication errors during the change.
- Decide where Redis runs and how it is backed up or recovered, since every process depends on it for replication.
- Set load balancer rules so that each worker type receives only the traffic it is meant to handle, and drain each node before its upgrade.
- Plan a messaging test after each node changes: sending messages between clients on different nodes, joining a federated room if federation is enabled, and uploading media.
Check the worker configuration files and load balancer rules against the target release notes before the first node restarts.
On Kubernetes, the Element Server Suite is deployed with Helm charts, so an upgrade is a change to chart and image versions that the cluster rolls out. The chart version, the Synapse image, the database and the values file each have their own history, and they should move together. Confirm which ESS edition you run first, because ESS Community, ESS Pro and ESS TI-Messenger have different distribution and support terms.
Extra steps and decisions:
- Read the chart release notes between your current and target chart versions, and compare your values file against the new defaults.
- Decide whether database migrations run as a separate job before new pods start, and who approves that step.
- Decide how stateful components roll out, and confirm how persistent volumes for media are handled during the change.
- Pin chart versions and image versions in your deployment repository so that a cluster rebuild reproduces the same state.
- Confirm which components your edition includes, such as Synapse Pro, Matrix Authentication Service, LDAP and SCIM integration, and check each one for its own upgrade path.
Check that a staging cluster built from the same chart and values versions passes your smoke tests before the release is promoted to production.
A deployment far behind the current release must pass through each intermediate version, because upgrade notes describe changes release by release. Skipping a version can leave the database schema or configuration in a state the newer code does not expect. The sequence of steps matters as much as the final version, and dependencies such as Python and PostgreSQL may have changed support status in the meantime, since Synapse drops support for versions that reach upstream end of life.
Extra steps and decisions:
- Build a version ladder from your current release to the target, listing every release with a database or configuration change, and read each set of upgrade notes in order.
- Check Python and PostgreSQL versions first. Synapse 1.142.0 requires Python 3.10 or newer, and Synapse 1.143.0 requires PostgreSQL 14 or newer, so an older host may need an operating system or database upgrade before Synapse can move forward.
- Decide whether to upgrade in stages on the existing environment or to build a new environment at the target version and migrate data into it. Each choice has a different rollback path.
- Agree a rollback point for each stage, such as a verified backup taken before the schema change, and record which stages can be reversed in practice.
- Test each stage against a copy of production data, including media, room history and any custom modules, before repeating the process on production.
Confirm the full ladder with your test environment before scheduling the production window, since the number of stages affects the effort more than the final version does.
In an air-gapped or heavily regulated network, the upgrade starts before the server is touched. Operating system packages, Python dependencies, container images and Helm charts must be mirrored into the enclosed network from an approved source, and each artifact must be reviewed and recorded. An upgrade that works on a connected test host can stall at the first missing dependency inside the restricted environment.
Extra steps and decisions:
- Decide which artifacts are mirrored, including operating system packages, Python packages, PostgreSQL packages, Synapse or ESS container images and Helm charts.
- Set the mirror refresh cadence and decide who approves each import, including how checksums or signatures are verified against the vendor's published values.
- Record the version of every mirrored artifact in the change record so that reviewers can trace exactly what was deployed.
- Confirm that upstream end-of-life dates for Python and PostgreSQL are known, and that the mirror holds versions still supported at the target release.
- Plan how release notes, security advisories and vendor announcements reach the team inside the enclosed network, since they will not arrive automatically.
Run the full upgrade once in an environment built only from the mirror, so that any missing dependency surfaces before the production change window.
What you need to provide before an upgrade or support engagement
Before DeployOpen can plan an upgrade or quote ongoing support for a Matrix deployment, the client needs to provide read access to the running configuration and name the people who make decisions about it. The most important inputs are the Synapse configuration file, the worker layout and the database connection details needed for backup and restore testing. Without them, any plan is a guess about how the homeserver is built, and the upgrade notes cannot be checked against your actual setup. Read-only access is preferred where it is possible. Record what was shared in the engagement file so both sides work from the same inputs.
Several inputs describe what runs around Synapse. Provide the list of installed custom modules, bots and integrations, including the version or commit each one pins. Pluggable modules and bots are a common reason an upgrade breaks outside the core server. Provide the identity provider configuration as well. For Synapse, that means the oidc_providers, saml2_config or CAS settings. For Matrix Authentication Service, it means the upstream provider registrations. Also provide a staging environment or written permission to create one. A restore test on a copy of production data is the most reliable check of a schema change, and it cannot be done safely on the live server.
Name two people. The technical owner answers questions about the host, the database, the reverse proxy and the worker processes, and receives alerts during a change. The business owner approves change windows, accepts the risk of a planned interruption and signs off on test results. Also supply the list of clients and versions people actually use, including Element on web, desktop and mobile, any third-party clients and any bridge bots. Client behavior after a homeserver release is part of the acceptance test, so this list determines what must be checked before a change is closed.
Four decisions must be made before the engagement is scoped. First, support hours: state when DeployOpen responds to incidents and when planned work may run. Second, change windows: agree the recurring periods in which upgrades and restarts are allowed, and who can cancel one. Third, federation status: record whether the server federates openly, only with listed domains through federation_domain_whitelist, or not at all. This changes what a failed upgrade exposes and which federation tests are needed. Fourth, the rollback standard: decide whether the fallback is a database restore from a verified backup, a rebuild on the previous release, or forward fixes only. Upstream notes warn that rolling back across schema changes can be difficult, so this choice shapes the backup plan.
Confirm the versions in use before the first planning call. Synapse 1.143.0 and later require PostgreSQL 14 or newer, and 1.142.0 and later require Python 3.10 or newer. Upstream also drops support for Python and PostgreSQL versions once they reach end of life. If the host runs older components, the upgrade path may need a platform step first, which changes both the change window and the scope. Ask DeployOpen to list any such gaps in the written scope, so that extra work is agreed and priced separately. Keep the version inventory current, because it is the starting point for the next quote and the next upgrade.
Common questions about Matrix upgrade and support
What drives the cost of a Matrix upgrade?
The main cost drivers are the distance between your current Synapse version and the target release, any Python or PostgreSQL upgrades that release requires, and the amount of testing needed. Synapse 1.142.0 and later require Python 3.10 or newer, and 1.143.0 and later require PostgreSQL 14 or newer, so an older interpreter or database adds work before Synapse itself is touched. Other cost factors include the number of workers, bridges, custom modules and clients to retest, and whether a staging environment already exists. The project fee is one-time, and only a retainer recurs. Ask any quote to list each component, the environments covered, the rollback test and who performs each task.
How long does a Synapse upgrade project take?
The duration depends on the written scope, so no fixed timeline applies until that scope is agreed. Length follows from the versions crossed, the number of environments to rebuild, the custom code and integrations to retest, and how quickly your change process approves a maintenance window. DeployOpen agrees scope, deliverables and timelines in writing before work starts, so the timeline belongs in that document. Name the target release explicitly in the plan, and check the upgrade notes for every release between your current version and the target, since requirements can change between them.
What does a Matrix upgrade need from our internal team?
Your team supplies access and decisions that an outside engineer cannot make alone. You need a named owner for the homeserver, administrative access to the Synapse configuration, the database and the host, and confirmation that recent backups can be restored. Someone must choose the downtime window and approve the change, and users or room owners should test the clients and critical rooms that matter most to them. Plan for internal time from the start, and confirm the availability of these people in writing before the schedule is set.
Can our own team upgrade Synapse without a partner?
Yes, an internal team can upgrade Synapse if it has the skills and time to do so safely. Before starting, take a verified PostgreSQL backup, read the upgrade notes for each release you cross, and rehearse the upgrade on staging with a copy of production data. Decide in advance what rollback means, and test it, because schema changes between releases can make reverting difficult. Be honest about capacity: a single upgrade rarely fails on the first attempt, and the team needs time to fix surprises. Confirm that someone will own the upgrade through the full testing cycle.
When does a support retainer make sense over a one-off project?
A one-off project suits a single planned upgrade, a migration or a fixed scope with a clear end. A retainer suits an organization that expects regular Synapse releases, has limited internal capacity, or needs ongoing support, upgrades and continuous testing across several components. Retainers carry recurring cost, while a project is one-time, so compare the expected number of upgrades over a year with the internal effort each one would require. Ask what the retainer covers, how urgent requests are handled, and which upgrades and testing are included before deciding.
Does DeployOpen issue compliance attestations for Matrix upgrades?
No. DeployOpen does not issue audit reports, attestations or certifications. It prepares the systems, controls and evidence that an independent assessor reviews, such as version inventories, change records, test results, backup and restore evidence, and access settings for the upgrade. The assessor or certification body decides whether the evidence meets a given requirement. Before the work starts, ask which evidence will be produced, in what format, and which assessor or control framework it is intended to support.
Why is rolling back a Synapse upgrade so difficult?
Synapse upgrade notes warn that rollback can be hard because database schema changes between releases are often not reversible by simply running the older code again. The practical rollback path is usually restoring a database backup taken immediately before the upgrade, and that restore has to be tested. Any messages, membership changes or media metadata written after that backup are lost unless they are recovered or accounted for. Plan the upgrade window, backup timing and restore procedure together, and document how the team will decide to roll back.
What should we test after a Synapse upgrade?
Test every path that users and integrations depend on, not only whether the service starts. Check sign-in through your identity provider, client login and messaging, media upload and download, and federation if it is enabled. For scaled deployments, confirm that the main process, workers and Redis replication behave correctly. Also test bridges, custom modules, bots and any admin API automation. Use the upgrade notes for each release to identify configuration changes, and record the results so that the test evidence can be reviewed later.
How DeployOpen works on this
DeployOpen plans, implements, tests, documents and supports Matrix deployments inside the client's own infrastructure, including Synapse upgrades and their PostgreSQL and Python dependencies. Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts, and ongoing support is available as a retainer.
How we scope
- Inventory the current Synapse version, Python and PostgreSQL versions, worker layout and any custom modules before choosing a target release.
- Map each supported upgrade path against the upstream upgrade notes, including schema changes that may make rollback difficult.
- Agree in writing which clients, workers, identity providers and bridges are in the upgrade, and which are out of scope.
How we build
- Rehearse the upgrade on a copy of the production database and configuration, then record timings and any manual steps.
- Define a rollback plan with a tested database backup and restore procedure, and confirm the decision point before cutover.
- Test workers, federation settings, login flows and Element clients after the upgrade against a written test checklist.
How we hand over
- Deliver a runbook covering the upgrade sequence, configuration changes, verification steps and known rollback limits.
- Document the versions in use, dependency end-of-life dates to watch and the owner responsible for each component.
- Walk your operations team through the procedure and record the open items that remain after handover.
How we support
- Offer ongoing support, upgrades and monitoring of new upstream releases as a retainer, scoped in writing.
- Plan future upgrades around Python and PostgreSQL versions that upstream drops when they reach end of life.
- Confirm with the vendor or your own environment which support tier, release channel and security notice process applies to your deployment.
