PS-10273 [DOCS] - Update 8.0 to 8.4 migration documents

docs/8.4-breaking-changes.md

@@ -0,0 +1,150 @@
+# Breaking and incompatible changes in {{vers}}
+
+Review these items before upgrading from 8.0 to {{vers}}. This document covers breaking behavioral changes, removed features, and removed variables that may affect your upgrade. Each entry includes the impact, replacement (if available), and recommended action.
+
+## Authentication and user management
+
+Impact:
+
+* `mysql_native_password` is disabled by default in {{vers}}; new users default to `caching_sha2_password`.
+
+* The `mysql_native_password` plugin can still be loaded using `--mysql-native-password=ON` if needed for backward compatibility.
+
+* In the 9.x series, `mysql_native_password` will be completely removed.
+
+* `default_authentication_plugin` variable is removed.
+
+Replacement:
+
+* New users default to `caching_sha2_password`; configure authentication via supported mechanisms without this variable.
+
+Action:
+
+* Identify accounts and applications using `mysql_native_password` and plan migration to `caching_sha2_password`.
+* If necessary for temporary compatibility, you can enable `mysql_native_password` with `--mysql-native-password=ON`, but plan to migrate accounts as this plugin will be removed in future versions.
+* Validate driver/client support for `caching_sha2_password` and TLS.
+* Ensure drivers and clients support `caching_sha2_password`.
+
+## Replication terminology and commands
+
+Impact:
+
+* MASTER/SLAVE terms and statements are removed in {{vers}} and will cause syntax errors if used.
+
+* Statements such as `CHANGE MASTER TO`, `START SLAVE`, `STOP SLAVE`, and `SHOW SLAVE STATUS` are no longer supported.
+
+* Related status variables and counters (for example, `Com_show_slave_status`) are also removed.
+
+Replacement:
+
+* Use SOURCE/REPLICA equivalents: `START REPLICA`, `SHOW REPLICA STATUS`, `CHANGE REPLICATION SOURCE TO` and updated status fields.
+
+Action:
+
+* Update operational scripts, automation, and runbooks to new commands before upgrading.
+
+* Search for and replace all MASTER/SLAVE statements in your codebase with their SOURCE/REPLICA equivalents.
+
+* Update scripts, automation, and monitoring that reference removed statements or counters.
+
+* Re-test replication lifecycle: provisioning, change-source, failover.
+
+## Spatial indexes
+
+Impact:
+
+* A known issue can corrupt a spatial index (R-Tree index) in MySQL 8.4.0 through 8.4.4. The corruption is triggered when an `UPDATE` that slightly changes a geometry's MBR (Minimum Bounding Rectangle) is immediately followed by a `DELETE` of the same row. The R-Tree index can retain a dangling leaf, leading to "Incorrect key file" errors.
+
+Action:
+
+* Upgrade to 8.4.5 or later, which fixes this issue.
+
+* If you must remain on 8.4.0-8.4.4, apply one of these workarounds:
+  * Serialize UPDATE and DELETE statements (ensure they don't execute in immediate succession)
+  * Rebuild the spatial index after operations that might trigger the bug
+  * Set `innodb_rtree_index_update_interval=0` to disable deferred updates
+
+* If you're planning an upgrade from 8.0 or an earlier 8.4 point release, schedule a pre-upgrade test that exercises an update-then-delete pattern on a table with a spatial index. Verify the index remains healthy with `CHECK TABLE ... EXTENDED`. This will surface the bug before you move production data.
+
+* As a precautionary measure, you can drop spatial indexes before upgrade and re-create them after upgrade, then verify integrity.
+
+## New reserved keywords
+
+Impact:
+
+* New reserved words (for example, `MANUAL`, `PARALLEL`, `QUALIFY`, `TABLESAMPLE`) may conflict with unquoted identifiers and break queries.
+
+Action:
+
+* Scan schemas and queries for unquoted usage; quote or rename objects.
+
+* See: [Keywords and Reserved Words in MySQL {{vers}}](https://dev.mysql.com/doc/refman/{{vers}}/en/keywords.html) for the complete list of reserved keywords.
+
+
+## Data type restrictions
+
+Impact:
+
+* `AUTO_INCREMENT` is not permitted on `FLOAT` or `DOUBLE`.
+
+Action:
+
+* Convert these columns to `INTEGER` before upgrading.
+
+## Removed SQL function
+
+Impact:
+
+* `WAIT_UNTIL_SQL_THREAD_AFTER_GTIDS()` function is removed (deprecated in 8.0).
+
+Replacement:
+
+* `WAIT_FOR_EXECUTED_GTID_SET()`.
+
+Action:
+
+* Replace function usage in procedures, scripts, and runbooks.
+
+## Binary log retention variable
+
+Impact:
+
+* `expire_logs_days` variable is removed.
+
+Replacement:
+
+* `binlog_expire_logs_seconds`.
+
+Action:
+
+* Adjust configuration and automation to use seconds-based retention.
+
+## Memcached-related variables and APIs
+
+Impact:
+
+* Built-in memcached integration variables (for example, `daemon_memcached`, `innodb_api`, and related settings) are removed.
+
+Replacement:
+
+* Externalize caching at the application tier or separate cache services.
+
+Action:
+
+* Remove dependencies on the built-in memcached functionality.
+
+## Further reading
+
+* [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)
+* [Upgrade to Percona Server for MySQL Pro](./upgrade-pro.md)
+* [Downgrade options](./downgrade.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)
+
+

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

@@ -0,0 +1,82 @@
+# Compatibility and removed items in {{vers}}
+
+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.
+
+## Removed server and replication system variables
+
+| Variable Name | Description | Replacement |
+| --- | --- | --- |
+| `avoid_temporal_upgrade` | Whether ALTER TABLE should upgrade pre-5.6.4 temporal columns | No replacement |
+| `binlog_transaction_dependency_tracking` | Source of dependency information for multithreaded applier | Functionality is now internal; WRITESET is the default and the only available mode |
+| `character-set-client-handshake` | Do not ignore client-side character set value sent during handshake | No replacement |
+| `default_authentication_plugin` | Default authentication plugin | `authentication_policy` |
+| `expire_logs_days` | Purge binary logs after a number of days | `binlog_expire_logs_seconds` |
+| `group_replication_ip_whitelist` | List of hosts permitted to connect to the group | No replacement |
+| `group_replication_primary_member` | Primary member UUID when in single-primary mode | No replacement |
+| `group_replication_recovery_complete_at` | Recovery policies when handling cached transactions | No replacement |
+| `have_openssl` | Whether the server supports SSL connections | No replacement |
+| `have_ssl` | Whether the server supports SSL connections | No replacement |
+| `innodb_api_...` variables | All innodb_api variables related to built-in memcached functionality | No replacement |
+
+## Removed server options, SQL statements, and status variables
+
+| Item Name | Type | Replacement |
+| --- | --- | --- |
+| `admin-ssl` | Server Option | `--tls-version` and `--admin-tls-version` |
+| `authentication_fido_rp_id` | Server Option | No replacement |
+| `--language` | Server Option | No replacement |
+| `--old` and `--new` | Server Option | No replacement |
+| `Com_change_master` | Status Variable | `Com_change_replication_source` |
+| `Com_show_master_status` | Status Variable | `Com_show_binary_log_status` |
+| `Com_show_slave_status` | Status Variable | `Com_show_replica_status` |
+| `Com_slave_start` | Status Variable | `Com_replica_start` |
+| `Com_slave_stop` | Status Variable | `Com_replica_stop` |
+| `CHANGE MASTER TO` | SQL Statement | `CHANGE REPLICATION SOURCE TO` |
+| `SHOW SLAVE STATUS` | SQL Statement | `SHOW REPLICA STATUS` |
+| `START SLAVE` | SQL Statement | `START REPLICA` |
+| `STOP SLAVE` | SQL Statement | `STOP REPLICA` |
+| `SHOW MASTER STATUS` | SQL Statement | `SHOW BINARY LOG STATUS` |
+| `RESET MASTER` | SQL Statement | `RESET BINARY LOGS AND GTIDS` |
+| `WAIT_UNTIL_SQL_THREAD_AFTER_GTIDS()` | SQL Function | `WAIT_FOR_EXECUTED_GTID_SET()` |
+
+## Third-party tool compatibility
+
+### Percona XtraBackup (PXB)
+
+* **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.
+* **Compatibility**: Does not support backing up databases from MySQL 8.0 or 9.x servers.
+* **Action**: Upgrade XtraBackup to version 8.4 before or during the database upgrade.
+
+### Percona Operator for MySQL
+
+* **Upgrade method**: Create a new PXC 8.4 installation using the Percona Operator for PXC 8.4.
+* **Data migration**: Recover data from an 8.0 backup, then establish asynchronous replication between clusters.
+* **In-place upgrade**: Not recommended; may work but is not guaranteed.
+
+### ProxySQL
+
+* **MySQL 8.4 support**: Recent versions support MySQL 8.4 and include Group Replication support for 8.4 and 9.x.
+* **Authentication**: ProxySQL 2.6+ supports `caching_sha2_password` (default in 8.4).
+* **Replication terminology**: Compatible with SOURCE/REPLICA syntax; can monitor replica lag and manage traffic accordingly.
+
+## Pre-upgrade validation
+
+Use these tools to identify compatibility issues:
+
+* **mysqlsh upgrade checker**: Identifies many removed parameters and compatibility issues.
+* **Manual review**: Cross-reference your configuration files and application code against the removed items tables above.
+* **Third-party tooling**: Verify versions of backup utilities, proxies, and monitoring solutions.
+
+## Further reading
+
+* [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)
+* [Upgrade to Percona Server for MySQL Pro](./upgrade-pro.md)
+* [Downgrade options](./downgrade.md)
+* [Breaking and incompatible changes in {{vers}}](./8.4-breaking-changes.md)
+* [Defaults and tuning guidance for {{vers}}](./8.4-defaults-and-tuning.md)
+* [Percona Toolkit updates for {{vers}}](./percona-toolkit-8.4-updates.md)

docs/8.4-defaults-and-tuning.md

@@ -0,0 +1,57 @@
+# Defaults and tuning guidance for {{vers}}
+
+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.
+
+## Notable InnoDB default changes
+
+| InnoDB System Variable Name | New Default ({{vers}}) | Previous Default (8.0) |
+| --- | --- | --- |
+| `innodb_adaptive_hash_index` | OFF | ON |
+| `innodb_change_buffering` | none | all |
+| `innodb_doublewrite_files` | 2 | `innodb_buffer_pool_instances * 2` |
+| `innodb_doublewrite_pages` | 128 | 4 |
+| `innodb_flush_method` on Linux | O_DIRECT if supported, otherwise fsync | fsync |
+| `innodb_io_capacity` | 10000 | 200 |
+| `innodb_log_buffer_size` | 67108864 (64 MiB) | 16777216 (16 MiB) |
+| `innodb_numa_interleave` | ON | OFF |
+| `temptable_max_ram` | 3% of total memory (1–4 GiB range) | 1073741824 (1 GiB) |
+| `innodb_parallel_read_threads` | available logical processors / 8 (min 4) | 4 |
+
+Why it matters:
+
+* Higher `innodb_io_capacity` leverages SSD/NVMe for IO-bound workloads; legacy spinning disks may need a lower value.
+* Larger `innodb_log_buffer_size` reduces redo flush frequency—helpful for write-heavy workloads.
+* `innodb_adaptive_hash_index` default OFF favors predictability; AHI can become a contention source under concurrency.
+* NUMA interleaving defaults ON to reduce imbalance on multi-socket systems.
+
+## Configuration review checklist
+
+Use this to adapt an 8.0 configuration to {{vers}}:
+
+* Remove overrides that merely reassert old 8.0 defaults unless they are proven necessary.
+* Re-evaluate IO settings (`innodb_io_capacity`, flush method) based on storage type and observed latency.
+* Confirm redo/undo settings and log buffer meet current write patterns.
+* Validate parallel read threads relative to CPU topology and workload.
+* Generate a fresh config for {{vers}} when possible; only reapply carefully justified overrides.
+
+## Practical evaluation steps
+
+* Benchmark with your workload: baseline on 8.0 → restore to {{vers}} → run the same tests.
+* Compare Performance Schema and wait events for regressions or new hotspots.
+* Adjust a single variable at a time; document changes and impacts.
+
+## Further reading
+
+* [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)
+* [Upgrade to Percona Server for MySQL Pro](./upgrade-pro.md)
+* [Downgrade options](./downgrade.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)
+* [Percona Toolkit updates for {{vers}}](./percona-toolkit-8.4-updates.md)
+
+