Skip to content

PS-11133 [DOCS] - Update Upgrade/Migration docs 9.7 #714

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
patrickbirch wants to merge 1 commit into
base: 9.7
Choose a base branch
from
Open

PS-11133 [DOCS] - Update Upgrade/Migration docs 9.7 #714

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file added docs/_static/ce-flowchart.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
85 changes: 53 additions & 32 deletions docs/downgrade.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,62 +1,83 @@
# Downgrade Percona Server for MySQL

**Topic type**: Concept

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

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

## Before you downgrade

Review the following prerequisites before starting a downgrade:

* Understand the Percona Server for MySQL release model. Percona ships Long-Term Support (LTS) releases and bug-fix releases within each LTS series.

* Treat hot fixes as separate releases when you plan a downgrade.

Downgrading to a 5.7 or earlier series is not supported.
* For a replication topology, perform a rolling downgrade. Apply a single-server method to each server in turn.

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:
* Take a verified backup before any downgrade attempt.

* Performing an in-place upgrade
* Do not attempt to downgrade below 8.4. Earlier paths are not supported.

* Creating a logical dump and loading it
For the underlying MySQL guidance, see [Downgrading MySQL :octicons-link-external-16:](https://dev.mysql.com/doc/refman/{{vers}}/en/downgrading.html).

* Use MySQL Clone functionality
## Identify a supported downgrade path

* Set up replication between the versions
The following table summarizes supported downgrade paths from {{vers}} LTS.

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:
| Downgrade path | Example | Supported methods | Notes |
|---|---|---|---|
| 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. |
| To the previous LTS 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. |

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

* Set up replication between the versions.
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.

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

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:
The following methods support the paths in [Identify a supported downgrade path](#identify-a-supported-downgrade-path):

* Create a logical dump of your data and load it into the older version
* In-place: stop the server, replace binaries, and restart with the existing data directory. Available within the same LTS series only.

* Set up replication between the versions.
* Logical dump and load: export the data with `mysqldump` and load the dump into the older version.

!!! important "Important"
This downgrade path is only supported when no new server functionality has been applied to your data.
* MySQL Clone: clone data between servers within the same LTS series.

We don't support downgrades with any 8.0.x release below 8.0.34.
Releases in the range above 8.0.34 can be downgraded to any release within that range, including 8.0.34.
* Replication: configure replication from {{vers}} to the older version, validate the replica, and cut traffic over.

## Downgrading risks
For cutover and validation guidance during a downgrade, see [Upgrade strategies](./upgrade-strategies.md).

Downgrading has the following risks:
## Assess downgrade risks

!!! warning "Data loss risk"

A failed downgrade can corrupt or destroy data. Create and verify a backup before any downgrade attempt. Restore the backup if the downgrade encounters issues.

The following table lists the risks of downgrading.

| Risk | Description |
|---|---|
| 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. |
| Incompatibility | If you use any feature or improvement in the latest version, downgrading could result in incompatibility issues. |
| Performance | Downgrading may result in a loss of performance |
| Security | Newer versions have security updates that are not available in the older versions, which could lead to exposure. |
| Data loss | Data loss is possible if the downgrade encounters issues. Create a backup of your data before attempting a downgrade. |
| Incompatibility | Features used in the upgraded version can cause incompatibility. |
| Performance | Downgrading can reduce performance. |
| Security | Older versions lack security updates available in upgraded versions, which can increase exposure. |

## Further reading

The following Percona Server for MySQL pages cover related topics:

* [MySQL upgrade paths and supported methods](./mysql-upgrade-paths.md)

* [Percona Toolkit updates for {{vers}}](./percona-toolkit-9.7-updates.md)

* [Upgrade checklist for {{vers}}](./upgrade-checklist-9.7.md)

* [Upgrade from plugins to components](./upgrade-components.md)

* [Upgrade overview](./upgrade.md)
* [Upgrade checklist for {{vers}}](./upgrade-checklist-8.4.md)

* [Upgrade procedures for {{vers}}](./upgrade-procedures.md)

* [Upgrade strategies](./upgrade-strategies.md)
* [MySQL upgrade paths and supported methods](./mysql-upgrade-paths.md)
* [Upgrade from plugins to components](./upgrade-components.md)
* [Breaking and incompatible changes in {{vers}}](./8.4-breaking-changes.md)
* [Compatibility and removed items in {{vers}}](./8.4-compatibility-and-removed-items.md)
* [Defaults and tuning guidance for {{vers}}](./8.4-defaults-and-tuning.md)
* [Percona Toolkit updates for {{vers}}](./percona-toolkit-8.4-updates.md)
Loading