Skip to content

Commit 77dcef7

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 77dcef7

8 files changed

Lines changed: 743 additions & 0 deletions

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

Lines changed: 290 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,290 @@
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+
## GTID and enforce_gtid_consistency defaults (9.0)
42+
43+
Impact:
44+
45+
* As of MySQL 9.0, `gtid_mode` defaults to ON. Upgrading from a non-GTID 8.4 (or earlier) setup can break replication if the replica expects file-based or position-based replication.
46+
* `enforce_gtid_consistency` also defaults to ON. It prevents non-deterministic statements (e.g. certain UUID(), user variable, or limit-inconsistent constructs) inside transactions; applications that rely on such statements can fail or behave differently.
47+
48+
Replacement:
49+
50+
* To keep pre-9.0 replication behavior, set `gtid_mode=OFF` and `enforce_gtid_consistency=OFF` in `my.cnf` before starting the upgraded server, or migrate to GTID before upgrading.
51+
52+
Action:
53+
54+
* If you use replication without GTID today, either set `gtid_mode=OFF` and `enforce_gtid_consistency=OFF` in configuration before upgrade or plan a GTID migration first.
55+
* Audit application SQL for non-deterministic statements in transactions; ensure compatibility or leave `enforce_gtid_consistency=OFF` only if necessary and understood.
56+
57+
## --early-plugin-load removed (9.1)
58+
59+
Impact:
60+
61+
* The server option `--early-plugin-load` is removed in MySQL 9.1. If this option is present in `my.cnf`, the server can fail to start.
62+
63+
Replacement:
64+
65+
* Use the component manifest (e.g. `mysqld.my`) or the supported component-loading mechanism for functionality that previously relied on early-loaded plugins.
66+
67+
Action:
68+
69+
* Remove `--early-plugin-load` and any associated plugin references from `my.cnf` before upgrading to 9.x; migrate to components where applicable.
70+
71+
## mysql client parsing of \G and \C (9.1)
72+
73+
Impact:
74+
75+
* The mysql client parses `\G` (vertical output) and `\C` (clear) more strictly; they are only recognized at the end of a statement. Scripts that embed these in the middle of a statement (e.g. `mysql -e "SELECT 1 \G SELECT 2"`) can break or produce unexpected output.
76+
77+
Replacement:
78+
79+
* Use `\G` or `\C` only at statement end, or split commands into separate invocations or statements.
80+
81+
Action:
82+
83+
* Audit shell scripts and automation that use `mysql -e "..."` or batch input for broken or ambiguous use of `\G` and `\C`; fix syntax before upgrading.
84+
85+
## CREATE DATABASE / DROP DATABASE atomic (9.1)
86+
87+
Impact:
88+
89+
* `CREATE DATABASE` and `DROP DATABASE` are now atomic and crash-safe. This is a behavior improvement; no compatibility break for correct usage.
90+
91+
Action:
92+
93+
* No change required; optional cleanup of any workarounds that assumed non-atomic behavior.
94+
95+
## keyring_file plugin removed (9.2)
96+
97+
Impact:
98+
99+
* The `keyring_file` plugin binary is removed in MySQL 9.2. Servers or configurations that load this plugin will fail to start or will error when the plugin is requested.
100+
101+
Replacement:
102+
103+
* Use the `component_keyring_file` component for file-based keyring storage. Migrate keyring data and configuration to the component before upgrade.
104+
105+
Action:
106+
107+
* Migrate to `component_keyring_file` (or another keyring component) before upgrading to 9.x; remove plugin load options and update configuration.
108+
109+
## FLUSH PRIVILEGES and related (9.2)
110+
111+
Impact:
112+
113+
* The `FLUSH PRIVILEGES` statement is deprecated and produces a warning when used; it is expected to be removed in a future release.
114+
* 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).
115+
116+
Replacement:
117+
118+
* 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.
119+
120+
Action:
121+
122+
* Update scripts, automation, and runbooks to remove or replace `FLUSH PRIVILEGES` and the deprecated mysqladmin commands before upgrading to 9.7.
123+
124+
## Version Tokens plugin (9.2 deprecated, 9.3 removed)
125+
126+
Impact:
127+
128+
* 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.
129+
130+
Replacement:
131+
132+
* No direct replacement; implement equivalent logic in application or middleware if needed.
133+
134+
Action:
135+
136+
* Remove use of Version Tokens plugin, related functions, privilege, and variables from configuration and code before upgrading to 9.x.
137+
138+
## Connection Control plugins (9.2)
139+
140+
Impact:
141+
142+
* 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.
143+
144+
Replacement:
145+
146+
* 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).
147+
148+
Action:
149+
150+
* 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.
151+
152+
## Replica parallel workers minimum (9.3)
153+
154+
Impact:
155+
156+
* As of 9.3, `replica_parallel_workers` can no longer be set to `0`; the minimum permitted value is `1`.
157+
158+
Replacement:
159+
160+
* Use `replica_parallel_workers = 1` if you previously relied on `0` for single-threaded applier behavior.
161+
162+
Action:
163+
164+
* Remove or change any configuration that sets `replica_parallel_workers = 0` before upgrading.
165+
166+
## InnoDB and Version Tokens variables removed (9.3)
167+
168+
Impact:
169+
170+
* InnoDB: `innodb_log_file_size`, `innodb_log_files_in_group`, and `innodb_undo_tablespaces` are removed; redo/undo configuration is handled differently.
171+
* Version Tokens: `version_tokens_session` and `version_tokens_session_number` are removed with the plugin.
172+
173+
Replacement:
174+
175+
* See the MySQL Reference Manual for current redo/undo and log configuration options.
176+
177+
Action:
178+
179+
* Remove these variables from configuration; adopt the current InnoDB and logging configuration model before upgrading.
180+
181+
## IGNORE and scalar subqueries (9.0)
182+
183+
Impact:
184+
185+
* `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.
186+
187+
Replacement:
188+
189+
* Ensure scalar subqueries return at most one row, or avoid relying on `IGNORE` to suppress this error.
190+
191+
Action:
192+
193+
* Audit procedures, scripts, and application SQL for `IGNORE` with scalar subqueries; fix logic or remove `IGNORE` where appropriate.
194+
195+
## Inline foreign keys enforced (9.0)
196+
197+
Impact:
198+
199+
* Inline foreign key specifications and implicit references to parent primary keys are now enforced; previously some forms were parsed but ignored.
200+
201+
Replacement:
202+
203+
* Use the standard syntax that MySQL now enforces.
204+
205+
Action:
206+
207+
* Confirm schema definitions and any generated DDL match the intended constraints; fix any statements that relied on previously ignored syntax.
208+
209+
## MD5() and SHA1() deprecated in SQL (9.4)
210+
211+
Impact:
212+
213+
* The `MD5()` and `SHA1()` SQL functions are formally deprecated in MySQL 9.4. They continue to work but may be removed in a future release. Applications or stored code that depend on them for security-sensitive or compatibility-sensitive behavior should plan to migrate.
214+
215+
Replacement:
216+
217+
* Use `SHA2()` or other non-deprecated hashing functions where possible. For compatibility with existing hashes, plan a migration path (e.g. dual-write, then cutover).
218+
219+
Action:
220+
221+
* Audit application code, stored procedures, and triggers for use of `MD5()` and `SHA1()`; migrate to `SHA2()` or another supported mechanism where appropriate.
222+
223+
## Foreign key logic moved to SQL layer (9.6)
224+
225+
Impact:
226+
227+
* Foreign key handling has been moved from the InnoDB storage engine to the SQL layer. Cascade and constraint behavior may produce additional or differently ordered events in the binary log and in CDC (change data capture) streams. Replication and downstream consumers that parse or rely on a specific event order may see new or changed events.
228+
229+
Replacement:
230+
231+
* Use the current MySQL 9.6 behavior; adjust replication or CDC consumers if they assume the previous InnoDB-only behavior or event ordering.
232+
233+
Action:
234+
235+
* Test replication and any CDC or binlog-based pipelines after upgrading to 9.6; expect new cascade-related events and update parsing or logic if needed.
236+
237+
## YEAR and date-time: negative years rejected (9.6)
238+
239+
Impact:
240+
241+
* Negative year values in date and time types are now strictly rejected. Data ingestion or ETL that previously allowed or relied on negative years (e.g. for historical or sentinel values) can fail with errors after upgrading to 9.6.
242+
243+
Replacement:
244+
245+
* Use valid year ranges (e.g. 1–9999 for `YEAR` and date types) or store out-of-range or sentinel values in a different representation.
246+
247+
Action:
248+
249+
* Audit data ingestion pipelines and any use of historical or sentinel dates (including negative years); clean or transform data before upgrade or adjust application logic to use supported ranges.
250+
251+
## Group Replication and replica variables removed (9.5)
252+
253+
Impact:
254+
255+
* `group_replication_allow_local_lower_version_join` is removed.
256+
* `replica_parallel_type` and `slave_parallel_type` are removed; replica parallelization is controlled differently.
257+
* 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.
258+
259+
Replacement:
260+
261+
* Use current Group Replication and replication configuration options; externalize semisync behavior if required.
262+
263+
Action:
264+
265+
* Remove removed variables from configuration and monitoring; update automation and runbooks to use current replication and Group Replication options.
266+
267+
## MySQL 9.0.0 availability
268+
269+
Impact:
270+
271+
* 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.
272+
273+
Replacement:
274+
275+
* Use MySQL 9.0.1 or later for the 9.0 series.
276+
277+
Action:
278+
279+
* 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).
280+
281+
## Further reading
282+
283+
* [Compatibility and removed items in the MySQL 9.x series](./9x-compatibility-and-removed-items.md)
284+
* [Defaults and tuning guidance for the MySQL 9.x series](./9x-defaults-and-tuning.md)
285+
* [What's New in the MySQL 9.x series (APT/DNF/YUM)](./whats-new-mysql-9x-apt-dnf-yum.md)
286+
* [Upgrade overview](./upgrade.md)
287+
* [Upgrade strategies](./upgrade-strategies.md)
288+
* [MySQL upgrade paths and supported methods](./mysql-upgrade-paths.md)
289+
* [Upgrade from plugins to components](./upgrade-components.md)
290+
* [Downgrade options](./downgrade.md)

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

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
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+
| `--early-plugin-load` | Server option | 9.1 | Component manifest (e.g. `mysqld.my`) or supported component loading |
36+
| keyring_file plugin (binary) | Plugin | 9.2 | `component_keyring_file` component |
37+
| All `Rpl_semi_sync_master_*` status variables | Status variable | 9.5 | No replacement |
38+
| All `Rpl_semi_sync_slave_*` status variables | Status variable | 9.5 | No replacement |
39+
40+
## Deprecated items (plan to replace before or during upgrade)
41+
42+
| Item | Deprecated in | Replacement or note |
43+
| --- | --- | --- |
44+
| `FLUSH PRIVILEGES` statement | 9.2 | Use recommended privilege-load behavior; see FLUSH docs |
45+
| `FLUSH_PRIVILEGES` privilege | 9.2 | Same as above |
46+
| mysqladmin flush-privileges, mysqladmin reload | 9.2 | Same as above |
47+
| Version Tokens plugin and related | 9.2 (removed 9.3) | No replacement |
48+
| Connection Control plugins | 9.2 | Connection Control component (`component_connection_control`) |
49+
| MySQL Enterprise Firewall plugin | 9.4 | MySQL Enterprise Firewall component |
50+
| Keyring plugin API, `--early-plugin-load` | 9.4 | Keyring components (see also `--early-plugin-load` removed 9.1) |
51+
| `MD5()`, `SHA1()` SQL functions | 9.4 | `SHA2()` or other non-deprecated hashing |
52+
| SCRAM-SHA-1 for SASL LDAP | 9.5 | `SCRAM-SHA-256`; `authentication_ldap_sasl_auth_method_name` now defaults to it |
53+
| HashiCorp Vault keyring plugin variables | 9.3 | HashiCorp Vault keyring component |
54+
55+
## Server and status variables reference (MySQL)
56+
57+
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:
58+
59+
* [MySQL 9.3](https://dev.mysql.com/doc/refman/9.3/en/added-deprecated-removed.html)
60+
* [MySQL 9.4](https://dev.mysql.com/doc/refman/9.4/en/added-deprecated-removed.html)
61+
* [MySQL 9.5](https://dev.mysql.com/doc/refman/9.5/en/added-deprecated-removed.html)
62+
* [MySQL 9.6](https://dev.mysql.com/doc/refman/9.6/en/added-deprecated-removed.html)
63+
64+
## APT/DNF/YUM packaging (9.x)
65+
66+
* 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.
67+
* 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).
68+
* 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.
69+
* For full steps, see [What's New in the MySQL 9.x series (APT/DNF/YUM)](./whats-new-mysql-9x-apt-dnf-yum.md).
70+
71+
## Pre-upgrade validation
72+
73+
Use these methods to identify compatibility issues:
74+
75+
* Cross-reference configuration files and application code against the removed and deprecated items in the tables above.
76+
* 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).
77+
* 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.
78+
* Test replication across source and replica versions before upgrading production replicas; deprecated or removed features can cause replication failures or different behavior.
79+
80+
## Further reading
81+
82+
* [Breaking and incompatible changes in the MySQL 9.x series](./9x-breaking-changes.md)
83+
* [Defaults and tuning guidance for the MySQL 9.x series](./9x-defaults-and-tuning.md)
84+
* [What's New in the MySQL 9.x series (APT/DNF/YUM)](./whats-new-mysql-9x-apt-dnf-yum.md)
85+
* [Upgrade overview](./upgrade.md)
86+
* [Upgrade strategies](./upgrade-strategies.md)
87+
* [MySQL upgrade paths and supported methods](./mysql-upgrade-paths.md)
88+
* [Upgrade from plugins to components](./upgrade-components.md)
89+
* [Downgrade options](./downgrade.md)

0 commit comments

Comments
 (0)