Skip to content

Commit ee291e1

Browse files
patrickbirchpatrickbirch
committed
PS-10273 [DOCS] - Update 8.0 to 8.4 migration documents
 On branch ps-10273-8.4 new file: docs/8.4-breaking-changes.md new file: docs/8.4-compatibility-and-removed-items.md new file: docs/8.4-defaults-and-tuning.md new file: docs/8.4-removed-features.md new file: docs/mysql-upgrade-paths.md new file: docs/percona-toolkit-8.4-updates.md modified: docs/upgrade-components.md new file: docs/upgrade-prechecks-8.4.md modified: docs/upgrade-strategies.md new file: docs/upgrade-validation-8.4.md modified: docs/upgrade.md
1 parent 45a181e commit ee291e1

12 files changed

+602
-3
lines changed

‎docs/8.4-breaking-changes.md‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
# {{vers}} breaking and incompatible changes
2+
3+
Review these items before upgrading from 8.0 to {{vers}}. Each entry includes the impact and recommended action.
4+
5+
## Authentication and user management
6+
7+
Impact:
8+
9+
* `mysql_native_password` is disabled by default in {{vers}}; new users default to `caching_sha2_password`.
10+
* `default_authentication_plugin` is removed.
11+
12+
Action:
13+
14+
* Identify accounts and applications using `mysql_native_password` and plan migration to `caching_sha2_password`.
15+
* If necessary for compatibility, start with `--mysql-native-password=ON` temporarily; remove after accounts are migrated.
16+
* Validate driver/client support for `caching_sha2_password` and TLS.
17+
18+
## Replication terminology and commands
19+
20+
Impact:
21+
22+
* MASTER/SLAVE terms and statements are removed.
23+
* Use replacements such as `START REPLICA`, `SHOW REPLICA STATUS`, and `CHANGE REPLICATION SOURCE TO`.
24+
25+
Action:
26+
27+
* Update operational scripts, automation, and runbooks to new commands.
28+
* Re-test replication lifecycle: provisioning, change-source, failover.
29+
30+
## Spatial indexes
31+
32+
Impact:
33+
34+
* A known issue can corrupt a spatial index after certain update/delete sequences across an upgrade.
35+
36+
Action:
37+
38+
* Drop spatial indexes before upgrade; re-create them after upgrade and verify integrity.
39+
40+
## New reserved keywords
41+
42+
Impact:
43+
44+
* New reserved words (for example, `MANUAL`, `PARALLEL`, `QUALIFY`, `TABLESAMPLE`) may conflict with unquoted identifiers and break queries.
45+
46+
Action:
47+
48+
* Scan schemas and queries for unquoted usage; quote or rename objects.
49+
* See: [keywords index](./index-keywords.md)
50+
51+
## Data type restrictions
52+
53+
Impact:
54+
55+
* `AUTO_INCREMENT` is not permitted on `FLOAT` or `DOUBLE`.
56+
57+
Action:
58+
59+
* Convert such columns to integer types before upgrading.
60+
61+
## See also
62+
63+
* [Pre-upgrade checks for {{vers}}](./upgrade-prechecks-8.4.md)
64+
* [Post-upgrade validation for {{vers}}](./upgrade-validation-8.4.md)
65+
* [{{vers}} defaults and tuning guidance](./8.4-defaults-and-tuning.md)
66+
* [Upgrade from plugins to components](./upgrade-components.md)
67+
* [Percona Toolkit updates for {{vers}}](./percona-toolkit-8.4-updates.md)
68+
* [Removed features and variables in {{vers}}](./8.4-removed-features.md)
69+
* [{{vers}} compatibility and removed items](./8.4-compatibility-and-removed-items.md)
70+
71+

‎docs/8.4-compatibility-and-removed-items.md‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
# {{vers}} compatibility and removed items
2+
3+
A successful migration requires identifying and addressing all removed parameters, variables, and functions. Using removed items in configuration files or application code will cause errors and prevent server startup or application execution.
4+
5+
## Removed server and replication system variables
6+
7+
| Variable Name | Description | Replacement |
8+
| --- | --- | --- |
9+
| `avoid_temporal_upgrade` | Whether ALTER TABLE should upgrade pre-5.6.4 temporal columns | N/A |
10+
| `binlog_transaction_dependency_tracking` | Source of dependency information for multithreaded applier | Functionality is now internal |
11+
| `character-set-client-handshake` | Do not ignore client-side character set value sent during handshake | N/A |
12+
| `default_authentication_plugin` | Default authentication plugin | `authentication_policy` |
13+
| `expire_logs_days` | Purge binary logs after a number of days | `binlog_expire_logs_seconds` |
14+
| `group_replication_ip_whitelist` | List of hosts permitted to connect to the group | N/A |
15+
| `group_replication_primary_member` | Primary member UUID when in single-primary mode | N/A |
16+
| `group_replication_recovery_complete_at` | Recovery policies when handling cached transactions | N/A |
17+
| `have_openssl` | Whether the server supports SSL connections | N/A |
18+
| `have_ssl` | Whether the server supports SSL connections | N/A |
19+
| `innodb_api_...` variables | All innodb_api variables related to built-in memcached functionality | N/A |
20+
21+
## Removed server options, SQL statements, and status variables
22+
23+
| Item Name | Type | Replacement |
24+
| --- | --- | --- |
25+
| `admin-ssl` | Server Option | `--tls-version` and `--admin-tls-version` |
26+
| `authentication_fido_rp_id` | Server Option | N/A |
27+
| `--language` | Server Option | N/A |
28+
| `--old` and `--new` | Server Option | N/A |
29+
| `Com_change_master` | Status Variable | `Com_change_replication_source` |
30+
| `Com_show_master_status` | Status Variable | `Com_show_binary_log_status` |
31+
| `Com_show_slave_status` | Status Variable | `Com_show_replica_status` |
32+
| `Com_slave_start` | Status Variable | `Com_replica_start` |
33+
| `Com_slave_stop` | Status Variable | `Com_replica_stop` |
34+
| `CHANGE MASTER TO` | SQL Statement | `CHANGE REPLICATION SOURCE TO` |
35+
| `SHOW SLAVE STATUS` | SQL Statement | `SHOW REPLICA STATUS` |
36+
| `START SLAVE` | SQL Statement | `START REPLICA` |
37+
| `STOP SLAVE` | SQL Statement | `STOP REPLICA` |
38+
| `WAIT_UNTIL_SQL_THREAD_AFTER_GTIDS()` | SQL Function | `WAIT_FOR_EXECUTED_GTID_SET()` |
39+
40+
## Third-party tool compatibility
41+
42+
### Percona XtraBackup (PXB)
43+
44+
* **Version-specific backups**: Percona XtraBackup 8.4 creates backups of MySQL 8.4, Percona Server for MySQL 8.4, and Percona XtraDB Cluster 8.4 only.
45+
* **Compatibility**: Does not support backing up databases from MySQL 8.0 or 9.x servers.
46+
* **Action**: Upgrade XtraBackup to version 8.4 before or during the database upgrade.
47+
48+
### Percona Operator for MySQL
49+
50+
* **Upgrade method**: Create a new PXC 8.4 installation using the Percona Operator for PXC 8.4.
51+
* **Data migration**: Recover data from an 8.0 backup, then establish asynchronous replication between clusters.
52+
* **In-place upgrade**: Not recommended; may work but is not guaranteed.
53+
54+
### ProxySQL
55+
56+
* **MySQL 8.4 support**: Recent versions support MySQL 8.4 and include Group Replication support for 8.4 and 9.x.
57+
* **Authentication**: ProxySQL 2.6+ supports `caching_sha2_password` (default in 8.4).
58+
* **Replication terminology**: Compatible with REPLICA/SOURCE syntax; can monitor replica lag and manage traffic accordingly.
59+
60+
## Pre-upgrade validation
61+
62+
Use these tools to identify compatibility issues:
63+
64+
* **mysqlsh upgrade checker**: Identifies many removed parameters and compatibility issues.
65+
* **Manual review**: Cross-reference your configuration files and application code against the removed items tables above.
66+
* **Third-party tooling**: Verify versions of backup utilities, proxies, and monitoring solutions.
67+
68+
## See also
69+
70+
* [Removed features and variables in {{vers}}](./8.4-removed-features.md)
71+
* [Pre-upgrade checks for {{vers}}](./upgrade-prechecks-8.4.md)
72+
* [{{vers}} breaking changes](./8.4-breaking-changes.md)
73+
* [Percona Toolkit updates for {{vers}}](./percona-toolkit-8.4-updates.md)

‎docs/8.4-defaults-and-tuning.md‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
# {{vers}} defaults and tuning guidance
2+
3+
MySQL {{vers}} updates several server defaults to align with modern CPUs, memory sizes, and SSD/NVMe storage. An in-place upgrade that blindly reuses an 8.0-era `my.cnf` may forgo these improvements or cause unexpected performance behaviors. Review and re-evaluate configuration on {{vers}}—or generate a new config—rather than carrying old settings forward.
4+
5+
## Notable InnoDB default changes
6+
7+
| InnoDB System Variable Name | New Default ({{vers}}) | Previous Default (8.0) |
8+
| --- | --- | --- |
9+
| `innodb_adaptive_hash_index` | OFF | ON |
10+
| `innodb_change_buffering` | none | all |
11+
| `innodb_doublewrite_files` | 2 | `innodb_buffer_pool_instances * 2` |
12+
| `innodb_flush_method` on Linux | O_DIRECT if supported, otherwise fsync | fsync |
13+
| `innodb_io_capacity` | 10000 | 200 |
14+
| `innodb_log_buffer_size` | 67108864 (64 MiB) | 16777216 (16 MiB) |
15+
| `innodb_numa_interleave` | ON | OFF |
16+
| `temptable_max_ram` | 3% of total memory (1–4 GiB range) | 1073741824 (1 GiB) |
17+
| `innodb_parallel_read_threads` | available logical processors / 8 (min 4) | 4 |
18+
19+
Why it matters:
20+
21+
* Higher `innodb_io_capacity` leverages SSD/NVMe for IO-bound workloads; legacy spinning disks may need a lower value.
22+
* Larger `innodb_log_buffer_size` reduces redo flush frequency—helpful for write-heavy workloads.
23+
* `innodb_adaptive_hash_index` default OFF favors predictability; AHI can become a contention source under concurrency.
24+
* NUMA interleaving defaults ON to reduce imbalance on multi-socket systems.
25+
26+
## Configuration review checklist
27+
28+
Use this to adapt an 8.0 configuration to {{vers}}:
29+
30+
* Remove overrides that merely reassert old 8.0 defaults unless they are proven necessary.
31+
* Re-evaluate IO settings (`innodb_io_capacity`, flush method) based on storage type and observed latency.
32+
* Confirm redo/undo settings and log buffer meet current write patterns.
33+
* Validate parallel read threads relative to CPU topology and workload.
34+
* Generate a fresh config for {{vers}} when possible; only reapply carefully justified overrides.
35+
36+
## Practical evaluation steps
37+
38+
* Benchmark with your workload: baseline on 8.0 → restore to {{vers}} → run the same tests.
39+
* Compare Performance Schema and wait events for regressions or new hotspots.
40+
* Adjust a single variable at a time; document changes and impacts.
41+
42+
## See also
43+
44+
* [Pre-upgrade checks for {{vers}}](./upgrade-prechecks-8.4.md)
45+
* [{{vers}} breaking changes](./8.4-breaking-changes.md)
46+
* [Post-upgrade validation for {{vers}}](./upgrade-validation-8.4.md)
47+
48+

‎docs/8.4-removed-features.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
# Removed features and variables in {{vers}}
2+
3+
MySQL {{vers}} removes several legacy statements, variables, and features to streamline the server and align with modern standards. Use this page to identify dependencies and plan replacements before upgrading.
4+
5+
## Replication statements and status variables
6+
7+
Removed:
8+
9+
* MASTER/SLAVE statements and status variables (for example, `START SLAVE`, `SHOW SLAVE STATUS`, `CHANGE MASTER TO`, and related counters such as `Com_show_slave_status`).
10+
11+
Replacement:
12+
13+
* Use REPLICA/SOURCE equivalents: `START REPLICA`, `SHOW REPLICA STATUS`, `CHANGE REPLICATION SOURCE TO` and updated status fields.
14+
15+
Action:
16+
17+
* Update scripts, automation, and monitoring that reference removed statements or counters.
18+
19+
## Authentication variables
20+
21+
Removed:
22+
23+
* `default_authentication_plugin`.
24+
25+
Replacement:
26+
27+
* New users default to `caching_sha2_password`; configure authentication via supported mechanisms without this variable.
28+
29+
Action:
30+
31+
* Ensure drivers and clients support `caching_sha2_password`.
32+
33+
## Removed SQL function
34+
35+
Removed:
36+
37+
* `WAIT_UNTIL_SQL_THREAD_AFTER_GTIDS()` (deprecated in 8.0).
38+
39+
Replacement:
40+
41+
* `WAIT_FOR_EXECUTED_GTID_SET()`.
42+
43+
Action:
44+
45+
* Replace function usage in procedures, scripts, and runbooks.
46+
47+
## Binary log retention variable
48+
49+
Removed:
50+
51+
* `expire_logs_days`.
52+
53+
Replacement:
54+
55+
* `binlog_expire_logs_seconds`.
56+
57+
Action:
58+
59+
* Adjust configuration and automation to use seconds-based retention.
60+
61+
## Memcached-related variables and APIs
62+
63+
Removed:
64+
65+
* Built-in memcached integration variables (for example, `daemon_memcached`, `innodb_api`, and related settings).
66+
67+
Replacement:
68+
69+
* Externalize caching at the application tier or separate cache services.
70+
71+
Action:
72+
73+
* Remove dependencies on the built-in memcached functionality.
74+
75+
## See also
76+
77+
* [{{vers}} breaking changes](./8.4-breaking-changes.md)
78+
* [{{vers}} compatibility and removed items](./8.4-compatibility-and-removed-items.md)
79+
* [Pre-upgrade checks for {{vers}}](./upgrade-prechecks-8.4.md)
80+
* [Post-upgrade validation for {{vers}}](./upgrade-validation-8.4.md)
81+

‎docs/mysql-upgrade-paths.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# MySQL upgrade paths and supported methods
2+
3+
MySQL supports different upgrade paths depending on the source and target versions. Choose the appropriate method based on your current version and target.
4+
5+
## Upgrade path matrix
6+
7+
| Upgrade Path | Path Examples | Supported Upgrade Methods |
8+
| --- | --- | --- |
9+
| Within an LTS or Bugfix series | 8.0.37 to 8.0.41 or 8.4.0 to 8.4.4 | In-place upgrade, logical dump and load, replication, and MySQL Clone |
10+
| From an LTS or Bugfix series to the next LTS series | 8.0.37 to 8.4.x LTS | In-place upgrade, logical dump and load, and replication |
11+
| From an LTS or Bugfix release to an Innovation release before the next LTS series | 8.0.34 to 8.3.0 or 8.4.0 to 9.0.0 | In-place upgrade, logical dump and load, and replication |
12+
| From the Innovation series to the next LTS series | 8.3.0 to 8.4 LTS | In-place upgrade, logical dump and load, and replication |
13+
| From an Innovation series to an Innovation release after the next LTS series | Not allowed, two steps are required: 8.3.0 to 8.4 LTS, and 8.4 LTS to 9.x Innovation | In-place upgrade, logical dump and load, and replication |
14+
15+
## Key considerations
16+
17+
* **LTS to LTS**: Direct upgrade from 8.0 LTS to 8.4 LTS is supported with multiple methods.
18+
* **Innovation to Innovation**: Cannot skip LTS releases; must upgrade through the LTS series first.
19+
* **MySQL Clone**: Only available for upgrades within the same major version series.
20+
* **Replication**: Available for most upgrade paths but requires careful planning for cross-version replication.
21+
22+
## Choosing your upgrade method
23+
24+
* **In-place upgrade**: Fastest but highest risk; requires downtime.
25+
* **Logical dump and load**: Cleanest but slowest for large datasets; requires downtime.
26+
* **Replication**: Minimal downtime but requires additional infrastructure; good for high-availability setups.
27+
* **MySQL Clone**: Fastest for same-series upgrades; requires compatible versions.
28+
29+
## See also
30+
31+
* [8.0 → {{vers}} migration methods](./upgrade-strategies.md#80--vers-migration-methods)
32+
* [Pre-upgrade checks for {{vers}}](./upgrade-prechecks-8.4.md)
33+
* [{{vers}} breaking changes](./8.4-breaking-changes.md)

‎docs/percona-toolkit-8.4-updates.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# Percona Toolkit updates for {{vers}}
2+
3+
Percona Toolkit has been updated to support MySQL {{vers}}, addressing terminology, deprecations, and authentication improvements. If your automation or runbooks use these tools, plan updates alongside the database upgrade.
4+
5+
## Terminology alignment
6+
7+
* Toolkit commands and output now use REPLICA/SOURCE terminology consistent with MySQL {{vers}}.
8+
9+
## Renamed tools
10+
11+
* `pt-slave-find` → `pt-replica-find`
12+
* `pt-slave-restart` → `pt-replica-restart`
13+
14+
Aliases with the old names remain for a transition period; update scripts and runbooks to the new names.
15+
16+
## Deprecated tool
17+
18+
* `pt-slave-delay` is deprecated. Use built-in delayed replication features in MySQL {{vers}} instead.
19+
20+
## Authentication and SSL
21+
22+
* Improved SSL handling and consistent support for `caching_sha2_password` and `sha256_password` authentication plugins.
23+
24+
## What to change in your environment
25+
26+
* Search automation and scripts for `pt-slave-*` and replace with `pt-replica-*`.
27+
* Remove dependencies on `pt-slave-delay`; use native delayed replication.
28+
* Validate Toolkit connectivity using your TLS settings and modern auth plugins.
29+
30+
## See also
31+
32+
* [Pre-upgrade checks for {{vers}}](./upgrade-prechecks-8.4.md)
33+
* [{{vers}} breaking changes](./8.4-breaking-changes.md)
34+
* [Post-upgrade validation for {{vers}}](./upgrade-validation-8.4.md)
35+

‎docs/upgrade-components.md‎

Lines changed: 16 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22

33
[Need help navigating plugin to component transitions? Percona Support can assist].(https://www.percona.com/services/support)
44

5+
Percona Server for MySQL {{vers}} shifts several features from plugins to components. When both forms exist in 8.0, transition to the component in 8.0 first where possible; otherwise, plan a controlled change during the {{vers}} upgrade.
6+
57
The following plugins have changed:
68

79
| Plugin | 8.0 information | {{vers}} changes | Notes |
@@ -27,11 +29,13 @@ The operation to transition from a plugin to a component can be complicated. Alw
2729

2830
Before you start, review the differences between the plugin and the component. A plugin configuration has plugin-specific system variables and uses the `--early-plugin-load` option. A component has a configuration file and loads using a manifest.
2931

32+
General procedure:
33+
3034
1. Setup the component's configuration file.
3135

32-
2. Load the component using the manifest.
36+
2. Load the component using the manifest (`INSTALL COMPONENT` or manifest file, as applicable).
3337

34-
3. Confirm that the component works. Run queries or other operations and test the component thoroughtly in your test environment.
38+
3. Confirm that the component works. Run queries or other operations and test the component thoroughly in your staging environment.
3539

3640
4. After confirmation, remove the original plugin.
3741

@@ -47,4 +51,13 @@ Some plugins may require more configuration and setup during the transition to a
4751

4852
5. Start the new {{vers}}
4953

50-
6. Confirm the component in {{vers}}
54+
6. Confirm the component in {{vers}}
55+
56+
## See also
57+
58+
* [Install a component](./install-component.md)
59+
* [Uninstall a component](./uninstall-component.md)
60+
* [Use Keyring Vault component](./use-keyring-vault-component.md)
61+
* [Install Data Masking component](./install-data-masking-component.md)
62+
* [Audit Log Filter component overview](./audit-log-filter-overview.md)
63+
* [Manage Audit Log Filter](./manage-audit-log-filter.md)

0 commit comments

Comments
 (0)