Skip to content

Commit 9a9cc5c

Browse files
patrickbirchpatrickbirch
committed
PS-10482 [DOCS] - Create a What's Changed in the MySQL 9.x series document 8.4
 new file: docs/9x-breaking-changes.md new file: docs/9x-compatibility-and-removed-items.md new file: docs/9x-defaults-and-tuning.md modified: docs/index.md modified: docs/installation.md modified: docs/upgrade.md new file: docs/whats-new-mysql-9x-apt-dnf-yum.md new file: docs/whats-changed-mysql-9x.md modified: mkdocs-base.yml
1 parent 655ef1e commit 9a9cc5c

8 files changed

Lines changed: 598 additions & 0 deletions

‎docs/9x-breaking-changes.md‎

Lines changed: 180 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,180 @@
1+
# Breaking and incompatible changes in the MySQL 9.x series
2+
3+
Review these items before upgrading from 8.x or an earlier 9.x release to 9.7 (or later 9.x). This document covers the most significant breaking behavioral changes, removed features, and removed variables that may affect your upgrade. Each entry includes the impact, replacement (if available), and recommended action.
4+
5+
Content is drawn from the MySQL 9.0, 9.2, 9.3, 9.4, and 9.5 release notes and the MySQL Reference Manual “What Is New” (nutshell) sections. For Percona Server for MySQL, check Percona release notes; timing and implementation may differ from community MySQL.
6+
7+
Review the [MySQL 9.x Reference Manual :octicons-link-external-16:](https://dev.mysql.com/doc/refman/9.6/en/) for more information.
8+
9+
## Authentication and user management (9.0)
10+
11+
Impact:
12+
13+
* The `mysql_native_password` authentication plugin is removed in MySQL 9.0.0 (it was deprecated in 8.0). The server rejects `mysql_native` authentication from older clients that do not support `CLIENT_PLUGIN_AUTH`.
14+
* The server options `--mysql-native-password`, `--mysql-native-password-proxy-users`, and the `default_authentication_plugin` system variable are removed.
15+
16+
Replacement:
17+
18+
* Use `caching_sha2_password` or another supported authentication plugin. New users default to `caching_sha2_password` in 8.4 and later.
19+
20+
Action:
21+
22+
* Identify accounts and applications using `mysql_native_password` and migrate them to `caching_sha2_password` (or another supported plugin) before upgrading to 9.x.
23+
* Remove `--mysql-native-password`, `--mysql-native-password-proxy-users`, and `default_authentication_plugin` from configuration and scripts.
24+
* When upgrading from MySQL 5.7 to a later release, the system accounts `mysql.sys` and `mysql.session` are updated to use `caching_sha2_password` (as of 9.2).
25+
26+
## Replication and mixed storage engines (9.0)
27+
28+
Impact:
29+
30+
* Transactions that update both transactional and nontransactional (or noncomposable) tables now produce a deprecation warning to the client and to the error log. Only InnoDB and BLACKHOLE are transactional and composable; NDB is transactional but not composable.
31+
32+
Replacement:
33+
34+
* Restrict such transactions or use only composable engine combinations (e.g. InnoDB+BLACKHOLE, MyISAM+MERGE) where the warning is not raised.
35+
36+
Action:
37+
38+
* Review workloads and replication streams for mixed-engine transactions; see [Replication and Transactions](https://dev.mysql.com/doc/refman/9.0/en/replication-features-transactions.html) in the MySQL manual.
39+
* Plan to eliminate or isolate mixed-engine usage before or after upgrading replicas.
40+
41+
## FLUSH PRIVILEGES and related (9.2)
42+
43+
Impact:
44+
45+
* The `FLUSH PRIVILEGES` statement is deprecated and produces a warning when used; it is expected to be removed in a future release.
46+
* The `FLUSH_PRIVILEGES` privilege and its grant are deprecated, as are `mysqladmin flush-privileges` and `mysqladmin reload`. Flushing privileges via SIGHUP and `mysqladmin refresh` are also considered deprecated (no warning).
47+
48+
Replacement:
49+
50+
* Use the recommended privilege-load behavior; see the [FLUSH statement](https://dev.mysql.com/doc/refman/9.2/en/flush.html) and [mysqladmin](https://dev.mysql.com/doc/refman/9.2/en/mysqladmin.html) documentation.
51+
52+
Action:
53+
54+
* Update scripts, automation, and runbooks to remove or replace `FLUSH PRIVILEGES` and the deprecated mysqladmin commands before upgrading to 9.7.
55+
56+
## Version Tokens plugin (9.2 deprecated, 9.3 removed)
57+
58+
Impact:
59+
60+
* The Version Tokens plugin was deprecated in 9.2 and removed in 9.3. The Version Tokens functions, `VERSION_TOKEN_ADMIN` privilege, and the `version_tokens_session` and `version_tokens_session_number` system variables are removed with the plugin.
61+
62+
Replacement:
63+
64+
* No direct replacement; implement equivalent logic in application or middleware if needed.
65+
66+
Action:
67+
68+
* Remove use of Version Tokens plugin, related functions, privilege, and variables from configuration and code before upgrading to 9.x.
69+
70+
## Connection Control plugins (9.2)
71+
72+
Impact:
73+
74+
* Both Connection Control plugins are deprecated and subject to removal in a future release. The plugin system and status variables and the Information Schema table used by the plugins are deprecated.
75+
76+
Replacement:
77+
78+
* The Connection Control component (`component_connection_control`) replaces both plugins with a single `INSTALL COMPONENT`; the component uses its own variables and a Performance Schema table. See [Connection Control Component](https://dev.mysql.com/doc/refman/9.2/en/connection-control-component.html).
79+
80+
Action:
81+
82+
* Migrate from the Connection Control plugins to the Connection Control component before the plugins are removed; update configuration and any scripts that query the deprecated I_S table.
83+
84+
## Replica parallel workers minimum (9.3)
85+
86+
Impact:
87+
88+
* As of 9.3, `replica_parallel_workers` can no longer be set to `0`; the minimum permitted value is `1`.
89+
90+
Replacement:
91+
92+
* Use `replica_parallel_workers = 1` if you previously relied on `0` for single-threaded applier behavior.
93+
94+
Action:
95+
96+
* Remove or change any configuration that sets `replica_parallel_workers = 0` before upgrading.
97+
98+
## InnoDB and Version Tokens variables removed (9.3)
99+
100+
Impact:
101+
102+
* InnoDB: `innodb_log_file_size`, `innodb_log_files_in_group`, and `innodb_undo_tablespaces` are removed; redo/undo configuration is handled differently.
103+
* Version Tokens: `version_tokens_session` and `version_tokens_session_number` are removed with the plugin.
104+
105+
Replacement:
106+
107+
* See the MySQL Reference Manual for current redo/undo and log configuration options.
108+
109+
Action:
110+
111+
* Remove these variables from configuration; adopt the current InnoDB and logging configuration model before upgrading.
112+
113+
## IGNORE and scalar subqueries (9.0)
114+
115+
Impact:
116+
117+
* `ER_SUBQUERY_NO_1_ROW` is no longer ignored by statements that use the `IGNORE` keyword. An UPDATE, DELETE, or INSERT that includes `IGNORE` and a scalar subquery returning more than one row can raise an error after upgrading to 9.0.
118+
119+
Replacement:
120+
121+
* Ensure scalar subqueries return at most one row, or avoid relying on `IGNORE` to suppress this error.
122+
123+
Action:
124+
125+
* Audit procedures, scripts, and application SQL for `IGNORE` with scalar subqueries; fix logic or remove `IGNORE` where appropriate.
126+
127+
## Inline foreign keys enforced (9.0)
128+
129+
Impact:
130+
131+
* Inline foreign key specifications and implicit references to parent primary keys are now enforced; previously some forms were parsed but ignored.
132+
133+
Replacement:
134+
135+
* Use the standard syntax that MySQL now enforces.
136+
137+
Action:
138+
139+
* Confirm schema definitions and any generated DDL match the intended constraints; fix any statements that relied on previously ignored syntax.
140+
141+
## Group Replication and replica variables removed (9.5)
142+
143+
Impact:
144+
145+
* `group_replication_allow_local_lower_version_join` is removed.
146+
* `replica_parallel_type` and `slave_parallel_type` are removed; replica parallelization is controlled differently.
147+
* All semisynchronous replication system and status variables (`rpl_semi_sync_master_*`, `rpl_semi_sync_slave_*`, `Rpl_semi_sync_master_*`, `Rpl_semi_sync_slave_*`) are removed in MySQL 9.5.
148+
149+
Replacement:
150+
151+
* Use current Group Replication and replication configuration options; externalize semisync behavior if required.
152+
153+
Action:
154+
155+
* Remove removed variables from configuration and monitoring; update automation and runbooks to use current replication and Group Replication options.
156+
157+
## MySQL 9.0.0 availability
158+
159+
Impact:
160+
161+
* MySQL 9.0.0 was withdrawn from download due to a critical bug: after creating a very large number of tables (8001 or more), the server could fail to restart.
162+
163+
Replacement:
164+
165+
* Use MySQL 9.0.1 or later for the 9.0 series.
166+
167+
Action:
168+
169+
* If you are on or evaluating 9.0, use 9.0.1 or later; see [Changes in MySQL 9.0.1](https://dev.mysql.com/doc/relnotes/mysql/9.0/en/news-9-0-1.html).
170+
171+
## Further reading
172+
173+
* [Compatibility and removed items in the MySQL 9.x series](./9x-compatibility-and-removed-items.md)
174+
* [Defaults and tuning guidance for the MySQL 9.x series](./9x-defaults-and-tuning.md)
175+
* [What's New in the MySQL 9.x series (APT/DNF/YUM)](./whats-new-mysql-9x-apt-dnf-yum.md)
176+
* [Upgrade overview](./upgrade.md)
177+
* [Upgrade strategies](./upgrade-strategies.md)
178+
* [MySQL upgrade paths and supported methods](./mysql-upgrade-paths.md)
179+
* [Upgrade from plugins to components](./upgrade-components.md)
180+
* [Downgrade options](./downgrade.md)

‎docs/9x-compatibility-and-removed-items.md‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
# Compatibility and removed items in the MySQL 9.x series
2+
3+
A successful migration to 9.7 (or later 9.x) requires identifying and addressing removed parameters, variables, and features. Using removed items in configuration files or application code will cause errors and can prevent the server from starting or applications from running. The following tables summarize removals across 9.0, 9.2, 9.3, 9.4, and 9.5; the 9.6 series documents the same removals as 9.5.
4+
5+
## Removed server and replication system variables
6+
7+
| Variable name | Removed in | Replacement |
8+
| --- | --- | --- |
9+
| `default_authentication_plugin` | 9.0 | `authentication_policy` (and migrate to supported plugins) |
10+
| `version_tokens_session` | 9.3 | No replacement (Version Tokens plugin removed) |
11+
| `version_tokens_session_number` | 9.3 | No replacement |
12+
| `innodb_log_file_size` | 9.3 | See MySQL Reference Manual for current redo configuration |
13+
| `innodb_log_files_in_group` | 9.3 | See MySQL Reference Manual |
14+
| `innodb_undo_tablespaces` | 9.3 | See MySQL Reference Manual |
15+
| `temptable_use_mmap` | 9.4 | No replacement |
16+
| `group_replication_allow_local_lower_version_join` | 9.5 | No replacement |
17+
| `replica_parallel_type` | 9.5 | Replica parallelization is now controlled differently |
18+
| `slave_parallel_type` | 9.5 | Same as above |
19+
| `rpl_semi_sync_master_enabled` | 9.5 | No replacement (semisync variables removed) |
20+
| `rpl_semi_sync_master_timeout` | 9.5 | No replacement |
21+
| `rpl_semi_sync_master_trace_level` | 9.5 | No replacement |
22+
| `rpl_semi_sync_master_wait_for_slave_count` | 9.5 | No replacement |
23+
| `rpl_semi_sync_master_wait_point` | 9.5 | No replacement |
24+
| `rpl_semi_sync_slave_enabled` | 9.5 | No replacement |
25+
| `rpl_semi_sync_slave_trace_level` | 9.5 | No replacement |
26+
27+
Note: `replica_parallel_workers = 0` is no longer allowed as of 9.3; minimum value is `1`.
28+
29+
## Removed server options and status variables
30+
31+
| Item name | Type | Removed in | Replacement |
32+
| --- | --- | --- | --- |
33+
| `--mysql-native-password` | Server option | 9.0 | Use supported authentication plugins |
34+
| `--mysql-native-password-proxy-users` | Server option | 9.0 | No replacement |
35+
| All `Rpl_semi_sync_master_*` status variables | Status variable | 9.5 | No replacement |
36+
| All `Rpl_semi_sync_slave_*` status variables | Status variable | 9.5 | No replacement |
37+
38+
## Deprecated items (plan to replace before or during upgrade)
39+
40+
| Item | Deprecated in | Replacement or note |
41+
| --- | --- | --- |
42+
| `FLUSH PRIVILEGES` statement | 9.2 | Use recommended privilege-load behavior; see FLUSH docs |
43+
| `FLUSH_PRIVILEGES` privilege | 9.2 | Same as above |
44+
| mysqladmin flush-privileges, mysqladmin reload | 9.2 | Same as above |
45+
| Version Tokens plugin and related | 9.2 (removed 9.3) | No replacement |
46+
| Connection Control plugins | 9.2 | Connection Control component (`component_connection_control`) |
47+
| MySQL Enterprise Firewall plugin | 9.4 | MySQL Enterprise Firewall component |
48+
| Keyring plugin API, `--early-plugin-load` | 9.4 | Keyring components |
49+
| SCRAM-SHA-1 for SASL LDAP | 9.5 | `SCRAM-SHA-256`; `authentication_ldap_sasl_auth_method_name` now defaults to it |
50+
| HashiCorp Vault keyring plugin variables | 9.3 | HashiCorp Vault keyring component |
51+
52+
## Server and status variables reference (MySQL)
53+
54+
Each MySQL 9.x Reference Manual includes a section that lists server options, system variables, and status variables added, deprecated, or removed in that release. Use it to audit configuration and monitoring:
55+
56+
* [MySQL 9.3](https://dev.mysql.com/doc/refman/9.3/en/added-deprecated-removed.html)
57+
* [MySQL 9.4](https://dev.mysql.com/doc/refman/9.4/en/added-deprecated-removed.html)
58+
* [MySQL 9.5](https://dev.mysql.com/doc/refman/9.5/en/added-deprecated-removed.html)
59+
* [MySQL 9.6](https://dev.mysql.com/doc/refman/9.6/en/added-deprecated-removed.html)
60+
61+
## APT/DNF/YUM packaging (9.x)
62+
63+
* Repository setup RPM names use the `mysql84` prefix (e.g. `mysql84-community-release-{platform}-{version-number}.noarch.rpm`); that prefix denotes the default series (MySQL 8.4 LTS), not whether 9.x is available.
64+
* The same repository provides MySQL 8.4 LTS (enabled by default), MySQL 8.0 (disabled by default), and the MySQL Innovation Series (disabled by default), which includes 9.x releases. To install or upgrade to 9.x, disable the 8.4 LTS subrepository and enable the Innovation subrepository (or select the Innovation track for APT).
65+
* Only one release series (8.4 LTS, 8.0, or Innovation) should be enabled at a time. On EL8, disable the platform MySQL module (`yum module disable mysql` or `dnf module disable mysql`) so MySQL repository packages are visible.
66+
* For full steps, see [What's New in the MySQL 9.x series (APT/DNF/YUM)](./whats-new-mysql-9x-apt-dnf-yum.md).
67+
68+
## Pre-upgrade validation
69+
70+
Use these methods to identify compatibility issues:
71+
72+
* Cross-reference configuration files and application code against the removed and deprecated items in the tables above.
73+
* Review the MySQL “Server and Status Variables and Options Added, Deprecated, or Removed” pages for each 9.x version you are stepping through (9.3, 9.4, 9.5, 9.6).
74+
* If available, use upgrade checkers (e.g. mysqlsh upgrade checker) and verify third-party backup, proxy, and monitoring tools are compatible with the target 9.x release.
75+
* Test replication across source and replica versions before upgrading production replicas; deprecated or removed features can cause replication failures or different behavior.
76+
77+
## Further reading
78+
79+
* [Breaking and incompatible changes in the MySQL 9.x series](./9x-breaking-changes.md)
80+
* [Defaults and tuning guidance for the MySQL 9.x series](./9x-defaults-and-tuning.md)
81+
* [What's New in the MySQL 9.x series (APT/DNF/YUM)](./whats-new-mysql-9x-apt-dnf-yum.md)
82+
* [Upgrade overview](./upgrade.md)
83+
* [Upgrade strategies](./upgrade-strategies.md)
84+
* [MySQL upgrade paths and supported methods](./mysql-upgrade-paths.md)
85+
* [Upgrade from plugins to components](./upgrade-components.md)
86+
* [Downgrade options](./downgrade.md)

‎docs/9x-defaults-and-tuning.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
# Defaults and tuning guidance for the MySQL 9.x series
2+
3+
MySQL 9.x introduces default and limit changes that can affect behavior and performance when upgrading from 8.x or an earlier 9.x release. Reusing an older `my.cnf` without review may miss improvements or cause unexpected behavior. Review and re-evaluate your configuration for the target 9.x release (e.g. 9.7), or generate a new config, rather than carrying old settings forward.
4+
5+
## Notable default and limit changes (9.5 and later)
6+
7+
| System variable or behavior | New default or limit (9.5+) | Previous (9.4 and earlier) |
8+
| --- | --- | --- |
9+
| `innodb_log_writer_threads` | Default depends on `log_bin` and number of logical CPUs (see below) | Default OFF when logical CPUs < 32; ON when ≥ 32 (unchanged when `log_bin` = ON) |
10+
| `binlog_transaction_dependency_history_size` | Default 1,000,000; maximum 10,000,000 | Default 25,000; maximum 1,000,000 |
11+
12+
### innodb_log_writer_threads default (9.5.0+)
13+
14+
As of MySQL 9.5.0, the default value of `innodb_log_writer_threads` is determined as follows:
15+
16+
* If `log_bin` = OFF: default OFF when number of logical CPUs ≤ 4; default ON when > 4.
17+
* If `log_bin` = ON: same as 9.4 and earlier — default OFF when logical CPUs < 32; default ON when ≥ 32.
18+
19+
Any value you set explicitly for `innodb_log_writer_threads` is unchanged. For details, see the variable description and [Optimizing InnoDB Redo Logging](https://dev.mysql.com/doc/refman/9.5/en/optimizing-innodb-logging.html) in the MySQL Reference Manual.
20+
21+
### binlog_transaction_dependency_history_size (9.5.0+)
22+
23+
The default was increased from 25,000 to 1,000,000 and the maximum from 1,000,000 to 10,000,000. Existing configured values are left as-is; this change does not affect already-set values.
24+
25+
Why these changes matter:
26+
27+
* The `innodb_log_writer_threads` default now allows log writer threads to be enabled on smaller systems when binary logging is off (e.g. standalone or read-scale nodes), which can improve redo write throughput.
28+
* A larger default and maximum for `binlog_transaction_dependency_history_size` supports better transaction dependency tracking for multithreaded replicas when the binary log is used; review if you had previously set this variable near the old maximum.
29+
30+
## Configuration review checklist
31+
32+
Use this when adapting an 8.x or earlier 9.x configuration to 9.7 (or later 9.x):
33+
34+
* Remove overrides that merely reassert old defaults unless they are proven necessary.
35+
* Re-evaluate InnoDB and redo/undo settings; several InnoDB variables were removed in 9.3 (e.g. `innodb_log_file_size`, `innodb_log_files_in_group`, `innodb_undo_tablespaces`) — ensure configuration matches the current model.
36+
* Confirm replication-related settings: `replica_parallel_workers` (minimum 1), and remove any use of `replica_parallel_type`, `slave_parallel_type`, or semisync variables removed in 9.5.
37+
* If you use binary logging, consider the new default and maximum for `binlog_transaction_dependency_history_size` and adjust only if needed.
38+
* Validate authentication and plugin/component usage: no `mysql_native_password` or removed plugin options; migrate to components where plugins are deprecated (keyring, firewall, Connection Control).
39+
* Generate a fresh config for the target 9.x release when possible; only reapply carefully justified overrides.
40+
41+
## Practical evaluation steps
42+
43+
* Benchmark with your workload: establish a baseline on the current version, then run the same tests on the target 9.x release.
44+
* Compare Performance Schema metrics and wait events for regressions or new hotspots.
45+
* Adjust one variable or setting at a time; document changes and their impacts.
46+
* Test replication and failover procedures on the new defaults before upgrading production.
47+
48+
## Further reading
49+
50+
* [Breaking and incompatible changes in the MySQL 9.x series](./9x-breaking-changes.md)
51+
* [Compatibility and removed items in the MySQL 9.x series](./9x-compatibility-and-removed-items.md)
52+
* [What's New in the MySQL 9.x series (APT/DNF/YUM)](./whats-new-mysql-9x-apt-dnf-yum.md)
53+
* [Upgrade overview](./upgrade.md)
54+
* [Upgrade strategies](./upgrade-strategies.md)
55+
* [MySQL upgrade paths and supported methods](./mysql-upgrade-paths.md)
56+
* [Upgrade from plugins to components](./upgrade-components.md)
57+
* [Downgrade options](./downgrade.md)
58+
* [Optimizing InnoDB Redo Logging](https://dev.mysql.com/doc/refman/9.5/en/optimizing-innodb-logging.html) (MySQL 9.5 Reference Manual)

‎docs/index.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,12 @@ Upgrade your Percona Server for MySQL installation with our comprehensive upgrad
6262

6363
</div><div data-banner markdown>
6464

65+
### :material-information-outline: Planning for the MySQL 9.x series? { .title }
66+
67+
If you are evaluating or planning a move to the MySQL 9.x series (for example, MySQL 9.7), see [What's New in the MySQL 9.x series (APT/DNF/YUM)](whats-new-mysql-9x-apt-dnf-yum.md) for an overview, plus the related guides on [breaking changes](9x-breaking-changes.md), [compatibility and removed items](9x-compatibility-and-removed-items.md), and [defaults and tuning](9x-defaults-and-tuning.md).
68+
69+
</div><div data-banner markdown>
70+
6571
## :fontawesome-solid-gears: Audit Log Filter plugin { .title }
6672

6773
Learn about the Audit Log Filter plugin that allows you to monitor, log, and block a connection or query actively executed on the selected server.

0 commit comments

Comments
 (0)