Skip to content

Commit 1b05c72

Browse files
committed
PS-11133 [DOCS] - Update Upgrade/Migration docs 9.7
modified: docs/downgrade.md modified: docs/index-keywords.md modified: docs/mysql-upgrade-paths.md modified: docs/percona-toolkit-9.7-updates.md modified: docs/upgrade-checklist-9.7.md modified: docs/upgrade-components.md modified: docs/upgrade-procedures.md modified: docs/upgrade-strategies.md modified: docs/upgrade.md
1 parent 6ef9435 commit 1b05c72

9 files changed

Lines changed: 1254 additions & 530 deletions

‎docs/downgrade.md‎

Lines changed: 51 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -2,61 +2,77 @@
22

33
--8<--- "get-help-snip.md"
44

5-
<!-- Clarify whether the following instruction is valid for 9.7-->
5+
[Need help planning a downgrade? Percona Support can assist :octicons-link-external-16:](https://www.percona.com/services/support).
66

7-
Downgrading to a 5.7 or earlier series is not supported.
7+
## Before you downgrade
88

9-
Between versions within the same Long-Term Support (LTS) series, you can downgrade from 8.4.y LTS to 8.4.x LTS using the following methods:
9+
Review the following prerequisites before starting a downgrade.
1010

11-
* Performing an in-place upgrade
11+
- Understand the MySQL release model for Long-Term Support (LTS) and Innovation releases.
1212

13-
* Creating a logical dump and loading it
13+
- Treat Monthly Rapid Update (MRU) releases and hot fixes as separate releases when you plan a downgrade.
1414

15-
* Use MySQL Clone functionality
15+
- For a replication topology, perform a rolling downgrade. Apply a single-server method to each server in turn.
1616

17-
* Set up replication between the versions
17+
- Take a verified backup before any downgrade attempt.
1818

19-
Between one LTS or Bugfix series to the previous LTS or Bugfix series, such as moving from 8.4.x LTS to 8.0.y, you have two primary options:
19+
- Do not attempt to downgrade to 5.7 or an earlier series. The path is not supported.
2020

21-
* Create a logical dump of your data and load it into the older version
21+
For the underlying MySQL guidance, see [Downgrading MySQL :octicons-link-external-16:](https://dev.mysql.com/doc/refman/{{vers}}/en/downgrading.html).
2222

23-
* Set up replication between the versions.
23+
## Identify a supported downgrade path
2424

25-
!!! important "Important"
26-
This downgrade path is only supported when no new server functionality has been applied to your data.
25+
The following table summarizes supported downgrade paths from {{vers}} LTS.
2726

28-
Between an LTS or Bugfix series to an earlier Innovation series (after the previous LTS release), such as from 8.4.x LTS to 8.3.0 Innovation, you have the following options:
27+
| Downgrade path | Example | Supported methods | Notes |
28+
|---|---|---|---|
29+
| Within the same LTS series | {{vers}}.y LTS to {{vers}}.x LTS | In-place, logical dump and load, MySQL Clone, or replication | Same-LTS downgrades have the most flexibility. |
30+
| To the previous LTS or Bugfix series | {{vers}}.x LTS to 8.4.y | Logical dump and load, or replication | Use this path as a rollback only. The data must contain no features from the upgraded version. |
31+
| To an Innovation release after the previous LTS series | {{vers}}.x LTS to a 9.x Innovation release (for example, 9.6) | Logical dump and load, or replication | Use this path as a rollback only. The data must contain no features from the upgraded version. |
2932

30-
* Create a logical dump of your data and load it into the older version
33+
!!! important "Rollback constraint"
3134

32-
* Set up replication between the versions.
35+
Cross-series paths fit a rollback scenario only. If you have run any feature unique to {{vers}} against the data, do not use a cross-series downgrade. Restore from a pre-upgrade backup instead.
3336

34-
!!! important "Important"
35-
This downgrade path is only supported when no new server functionality has been applied to your data.
37+
## Choose a downgrade method
3638

37-
We don't support downgrades with any 8.0.x release below 8.0.34.
38-
Releases in the range above 8.0.34 can be downgraded to any release within that range, including 8.0.34.
39+
The following methods support the paths in [Identify a supported downgrade path](#identify-a-supported-downgrade-path).
3940

40-
## Downgrading risks
41+
- In-place: stop the server, replace binaries, and restart with the existing data directory. Available within the same LTS series only.
4142

42-
Downgrading has the following risks:
43+
- Logical dump and load: export the data with `mysqldump` and load the dump into the older version.
44+
45+
- MySQL Clone: clone data between servers within the same LTS series.
46+
47+
- Replication: configure replication from {{vers}} to the older version, validate the replica, and cut traffic over.
48+
49+
For cutover and validation guidance during a downgrade, see [Upgrade strategies](./upgrade-strategies.md).
50+
51+
## Assess downgrade risks
52+
53+
The following table lists the risks of downgrading.
4354

4455
| Risk | Description |
4556
|---|---|
46-
| Data loss | If the downgrade process has issues, you may lose your data. It is crucial that you back up your data before attempting to downgrade. |
47-
| Incompatibility | If you use any feature or improvement in the latest version, downgrading could result in incompatibility issues. |
48-
| Performance | Downgrading may result in a loss of performance |
49-
| Security | Newer versions have security updates that are not available in the older versions, which could lead to exposure. |
57+
| Data loss | Data loss is possible if the downgrade encounters issues. Create a backup of your data before attempting a downgrade. |
58+
| Incompatibility | Features used in the upgraded version can cause incompatibility. |
59+
| Performance | Downgrading can reduce performance. |
60+
| Security | Older versions lack security updates available in upgraded versions, which can increase exposure. |
5061

5162
## Further reading
5263

53-
* [Upgrade overview](./upgrade.md)
54-
* [Upgrade checklist for {{vers}}](./upgrade-checklist-8.4.md)
55-
* [Upgrade procedures for {{vers}}](./upgrade-procedures.md)
56-
* [Upgrade strategies](./upgrade-strategies.md)
57-
* [MySQL upgrade paths and supported methods](./mysql-upgrade-paths.md)
58-
* [Upgrade from plugins to components](./upgrade-components.md)
59-
* [Breaking and incompatible changes in {{vers}}](./8.4-breaking-changes.md)
60-
* [Compatibility and removed items in {{vers}}](./8.4-compatibility-and-removed-items.md)
61-
* [Defaults and tuning guidance for {{vers}}](./8.4-defaults-and-tuning.md)
62-
* [Percona Toolkit updates for {{vers}}](./percona-toolkit-8.4-updates.md)
64+
The following Percona Server for MySQL pages cover related topics.
65+
66+
- [MySQL upgrade paths and supported methods](./mysql-upgrade-paths.md)
67+
68+
- [Percona Toolkit updates for {{vers}}](./percona-toolkit-9.7-updates.md)
69+
70+
- [Upgrade checklist for {{vers}}](./upgrade-checklist-9.7.md)
71+
72+
- [Upgrade from plugins to components](./upgrade-components.md)
73+
74+
- [Upgrade overview](./upgrade.md)
75+
76+
- [Upgrade procedures for {{vers}}](./upgrade-procedures.md)
77+
78+
- [Upgrade strategies](./upgrade-strategies.md)

0 commit comments

Comments
 (0)