From 8de3283ebe520e945ccfb66242f4795ecdd0d1f4 Mon Sep 17 00:00:00 2001 From: Twilight Sparkle <19155609+Twi1ightSparkle@users.noreply.github.com> Date: Thu, 22 Feb 2024 17:36:41 +0000 Subject: [PATCH] Add docs on upgrading from a very old version (#16951) Co-authored-by: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> --- changelog.d/16951.doc | 1 + docs/upgrade.md | 20 ++++++++++++++++++++ docs/usage/administration/admin_faq.md | 5 +++++ 3 files changed, 26 insertions(+) create mode 100644 changelog.d/16951.doc diff --git a/changelog.d/16951.doc b/changelog.d/16951.doc new file mode 100644 index 0000000000..a7fb33979d --- /dev/null +++ b/changelog.d/16951.doc @@ -0,0 +1 @@ +Add docs on upgrading from a very old version. \ No newline at end of file diff --git a/docs/upgrade.md b/docs/upgrade.md index 7f67ef8806..640fed3ae3 100644 --- a/docs/upgrade.md +++ b/docs/upgrade.md @@ -97,6 +97,26 @@ v1.61.0. <!-- REPLACE_WITH_SCHEMA_VERSIONS --> +## Upgrading from a very old version + +You need to read all of the upgrade notes for each version between your current +version and the latest so that you can update your dependencies, environment, +config files, etc. if necessary. But you do not need to perform an +upgrade to each individual version that was missed. + +We do not have a list of which versions must be installed. Instead, we recommend +that you upgrade through each incompatible database schema version, which would +give you the ability to roll back the maximum number of versions should anything +go wrong. See [Rolling back to older versions](#rolling-back-to-older-versions) +above. + +Additionally, new versions of Synapse will occasionally run database migrations +and background updates to update the database. Synapse will not start until +database migrations are complete. You should wait until background updates from +each upgrade are complete before moving on to the next upgrade, to avoid +stacking them up. You can monitor the currently running background updates with +[the Admin API](usage/administration/admin_api/background_updates.html#status). + # Upgrading to v1.100.0 ## Minimum supported Rust version diff --git a/docs/usage/administration/admin_faq.md b/docs/usage/administration/admin_faq.md index 5c9ee7d0aa..092dcc1c84 100644 --- a/docs/usage/administration/admin_faq.md +++ b/docs/usage/administration/admin_faq.md @@ -120,6 +120,11 @@ for file in $source_directory/*; do done ``` +How do I upgrade from a very old version of Synapse to the latest? +--- +See [this](../../upgrade.html#upgrading-from-a-very-old-version) section in the +upgrade docs. + Manually resetting passwords --- Users can reset their password through their client. Alternatively, a server admin -- GitLab