diff --git a/_resourcepdf/overrides/main.html b/_resourcepdf/overrides/main.html index 7d667d54484..c8a27d1ea40 100644 --- a/_resourcepdf/overrides/main.html +++ b/_resourcepdf/overrides/main.html @@ -50,11 +50,14 @@ {% endif %} diff --git a/_resourcepdf/overrides/partials/edit.html b/_resourcepdf/overrides/partials/edit.html new file mode 100644 index 00000000000..43b0d87b1c1 --- /dev/null +++ b/_resourcepdf/overrides/partials/edit.html @@ -0,0 +1,11 @@ +
+
+ + + {% set icon = config.theme.icon.edit or "material/file-edit-outline" %} + {% include ".icons/" ~ icon ~ ".svg" %} + + Edit this page on GitHub + +
+
\ No newline at end of file diff --git a/docs/8.4-breaking-changes.md b/docs/8.4-breaking-changes.md new file mode 100644 index 00000000000..209aa5b4fd9 --- /dev/null +++ b/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) + + diff --git a/docs/8.4-compatibility-and-removed-items.md b/docs/8.4-compatibility-and-removed-items.md new file mode 100644 index 00000000000..7eb71f013bb --- /dev/null +++ b/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) diff --git a/docs/8.4-defaults-and-tuning.md b/docs/8.4-defaults-and-tuning.md new file mode 100644 index 00000000000..38f426e5290 --- /dev/null +++ b/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) + + diff --git a/docs/adaptive-network-buffers.md b/docs/adaptive-network-buffers.md index 67c65d68b9c..59c7299ced6 100644 --- a/docs/adaptive-network-buffers.md +++ b/docs/adaptive-network-buffers.md @@ -2,7 +2,7 @@ To find the buffer size of the current connection, use the `network_buffer_length` status variable. Add `SHOW GLOBAL` to review the cumulative buffer sizes for all connections. This variable can help to estimate the maximum size of the network buffer’s overhead. -Network buffers grow towards the [max_allowed_packet] size and do not shrink until the connection is terminated. For example, if the connections are selected at random from the pool, an occasional big query eventually increases the buffers of all connections. The combination of max_allowed packet set to a value between 64MB to 128MB and the connection number between 256 to 1024 can create a large memory overhead. +Network buffers grow towards the [max_allowed_packet] size and do not shrink until the connection is terminated. For example, if the connections are selected at random from the pool, an occasional big query eventually increases the buffers of all connections. The combination of max_allowed packet set to a value between 64MB and 128MB and the connection number between 256 and 1024 can create a large memory overhead. Percona Server for MySQL implemented the [net_buffer_shrink_interval](#net_buffer_shrink_interval) variable to solve this issue. The default value is 0 (zero). If you set the value higher than 0, Percona Server records the network buffer’s maximum use size for the number of seconds set by net_buffer_shrink_interval. When the next interval starts, the network buffer is set to the recorded size. This action removes spikes in the buffer size. @@ -20,4 +20,4 @@ You can achieve similar results by disconnecting and reconnecting the TCP connec The interval is measured in seconds. The default value is 0, which disables the functionality. The minimum value is 0, and the maximum value is 31536000. -[max_allowed_packet]: https://dev.mysql.com/doc/refman/{{vers}}/en/server-system-variables.html#sysvar_max_allowed_packet \ No newline at end of file +[max_allowed_packet]: https://dev.mysql.com/doc/refman/{{vers}}/en/server-system-variables.html#sysvar_max_allowed_packet diff --git a/docs/audit-log-filter-new.md b/docs/audit-log-filter-new.md index 243fdcb8b20..1c172e04a31 100644 --- a/docs/audit-log-filter-new.md +++ b/docs/audit-log-filter-new.md @@ -4,7 +4,7 @@ The filter writes the audit log filter file in XML. The XML file uses UTF-8. The is the root element and this element contains - elements. Each element contains specific +<AUDIT_RECORD> elements. Each <AUDIT_RECORD> element contains specific information about an event that is audited. For each new file, the Audit Log Filter component writes the XML @@ -76,7 +76,7 @@ closing element is not available. ``` -The order of the attributes within an can vary. Certain attributes are in every element. Other attributes are optional and depend on the type of audit record. +The order of the attributes within an <AUDIT_RECORD> can vary. Certain attributes are in every element. Other attributes are optional and depend on the type of audit record. The attributes in every element are the following: diff --git a/docs/audit-log-filter-old.md b/docs/audit-log-filter-old.md index f71941aade1..19e4f018bf4 100644 --- a/docs/audit-log-filter-old.md +++ b/docs/audit-log-filter-old.md @@ -1,8 +1,8 @@ # Audit Log Filter format - XML (old style) -The old style XML format uses `` tag as the root element and adds the `` tag when the file closes. Each audited event is contained in an element. +The old style XML format uses `` tag as the root element and adds the `` tag when the file closes. Each audited event is contained in an <AUDIT_RECORD> element. -The order of the attributes within an can vary. Certain attributes are in every element. Other attributes are optional and depend on the type of audit record. +The order of the attributes within an <AUDIT_RECORD> can vary. Certain attributes are in every element. Other attributes are optional and depend on the type of audit record. ```xml diff --git a/docs/audit-log-filter-variables.md b/docs/audit-log-filter-variables.md index 01284b3b19a..5f4226cad90 100644 --- a/docs/audit-log-filter-variables.md +++ b/docs/audit-log-filter-variables.md @@ -374,7 +374,7 @@ mysql> SELECT audit_log_filter_set_user('user-name@localhost', 'filter-name'); | Units | byes | | Block size | 4096 | -This variable defines the buffer size in multiples of 4096 when logging is asynchronous. The contents for events are stored in a buffer. The contents are stored until the contents are written. +This read-only variable defines the buffer size in multiples of `4096` when logging is asynchronous. Events are temporarily stored in this buffer before being written to the log file. This variable requires a server restart to change. The component initializes a single buffer and removes the buffer when the component terminates. @@ -383,13 +383,13 @@ The component initializes a single buffer and removes the buffer when the compon | Option name | Description | | --- | --- | | Command-line | --audit-log-filter.compression | -| Dynamic | Yes | +| Dynamic | No | | Scope | Global | | Data type | Enumeration | | Default | NONE | | Valid values | NONE or GZIP | -This variable defines the compression type for the audit log filter file. The values can be either `NONE`, the default value and file has no compression, or `GZIP`. +This read-only variable defines the compression type for the audit log filter file. This variable requires a server restart to change. The values can be either `NONE`, the default value and file has no compression, or `GZIP`. ### `audit_log_filter.database` @@ -402,9 +402,11 @@ This variable defines the compression type for the audit log filter file. The va | Data type | String | | Default | mysql | -This variable defines the audit_log_filter database. This read-only variable stores the necessary tables. Set this option at system startup. The database name cannot exceed 64 characters or be `NULL`. +This read-only variable defines the audit_log_filter database, which stores the necessary tables. -An invalid database name prevents the use of the audit log filter component. +The database name cannot exceed 64 characters or be `NULL`. An invalid database name prevents the use of the audit log filter component. + +This variable requires a server restart to change. ### `audit_log_filter.disable` @@ -431,9 +433,10 @@ This variable requires the user account to have `SYSTEM_VARIABLES_ADMIN` and `AU | Default | NONE | | Valid values | NONE or AES | -This variable defines the encryption type for the audit log filter file. The values can be either of the following: +This read-only variable defines the encryption type for the audit log filter file. This variable requires a server restart to change. The values can be either of the following: * `NONE` - the default value, no encryption + * `AES` ### `audit_log_filter.file` @@ -446,11 +449,12 @@ This variable defines the encryption type for the audit log filter file. The val | Data type | String | | Default | audit_filter.log | -This variable defines the name and suffix of the audit log filter file. The component writes events to this file. +This read-only variable defines the filename of the audit log filter file. The component writes events to this file. This variable requires a server restart to change. -The file name and suffix can be either of the following: +The filename can be either of the following: * a relative path name - the component looks for this file in the data directory + * a full path name - the component uses the given value If you use a full path name, ensure the directory is accessible only to users who need to view the log and the server. @@ -468,12 +472,14 @@ For more information, see [Naming conventions](audit-log-filter-naming.md) | Default | NEW | | Available values | OLD, NEW, JSON | -This variable defines the audit log filter file format. +This read-only variable defines the audit log filter file format. This variable requires a server restart to change. The available values are the following: * [OLD (old-style XML)](audit-log-filter-old.md) -* [NEW (new-style XML)](audit-log-filter-new.md) and + +* [NEW (new-style XML)](audit-log-filter-new.md) + * [JSON](audit-log-filter-json.md). ### `audit_log_filter.format_unix_timestamp` @@ -502,11 +508,11 @@ This option does nothing when used with other format types. | Data type | String | | Default | FILE | -Defines where the component writes the audit log filter file. The following values are available: +This read-only variable defines where the component writes the audit log filter file. This variable requires a server restart to change. The following values are available: * `FILE` - component writes the log to a location specified in [`audit_log_filter.file`](#audit_log_filterfile) -* `SYSLOG` - component writes to the syslog +* `SYSLOG` - component writes to the syslog ### `audit_log_filter.key_derivation_iterations_count_mean` @@ -536,25 +542,22 @@ Defines the mean value of iterations used by the password-based derivation routi | Unit | bytes | | Block size | 4096 | -Defines pruning based on the combined size of the files: - -The default value is 1GB. - -A value of 0 (zero) disables pruning based on size. - -A value greater than 0 (zero) enables pruning based on size and defines the combined size limit. When the files exceed this limit, they can be pruned. +This variable defines the maximum combined size of all audit log files before pruning occurs. -The value is based on 4096 (block size). A value is truncated to the nearest multiple of the block size. If the value is less than 4096, the value is treated as 0 (zero). +**Default value:** 1GB -If the values for [`audit_log_filter.rotate_on_size`](#audit_log_filterrotate_on_size) and [`audit_log_filter.max_size`](#audit_log_filtermax_size) are greater than 0, we recommend that `audit_log_filter.max_size` value should be at least seven times the `audit_log_filter.rotate_on_size` value. +**Behavior:** +* A value of 0 (zero) disables size-based pruning +* A value greater than 0 enables pruning when the combined size of all audit log files exceeds this limit +* Values are rounded down to the nearest multiple of 4096 bytes (block size) +* Values less than 4096 are treated as 0 (disabled) -Pruning requires the following options: +**Recommendation:** When both `audit_log_filter.rotate_on_size` and `audit_log_filter.max_size` are greater than 0, set `audit_log_filter.max_size` to at least seven times the `audit_log_filter.rotate_on_size` value. -* [`audit_log_filter.rotate_on_size`](#audit_log_filterrotate_on_size) - -* [`audit_log_filter.max_size`](#audit_log_filtermax_size) - -* [`audit_log_filter.prune_seconds`](#audit_log_filterprune_seconds) +**Pruning requirements:** To enable pruning, you must configure at least one of the following: +* [`audit_log_filter.rotate_on_size`](#audit_log_filterrotate_on_size) - enables rotation +* [`audit_log_filter.max_size`](#audit_log_filtermax_size) - enables size-based pruning +* [`audit_log_filter.prune_seconds`](#audit_log_filterprune_seconds) - enables time-based pruning ### `audit_log_filter.password_history_keep_days` @@ -642,7 +645,7 @@ If you set the value to less than 4096, the component does not automatically rot | Data type | Enumeration | | Default | ASYNCHRONOUS | -Defines the Audit Log filter component's logging method. The valid values are the following: +This read-only variable defines the Audit Log filter component's logging method. This variable requires a server restart to change. The valid values are the following: | Values | Description | | --- | --- | @@ -661,6 +664,8 @@ Defines the Audit Log filter component's logging method. The valid values are th | Data type | String | | Default | audit-filter | +This read-only variable specifies the syslog tag value. This variable requires a server restart to change. + ### `audit_log_filter.syslog_facility` | Option name | Description | @@ -671,7 +676,7 @@ Defines the Audit Log filter component's logging method. The valid values are th | Data type | String | | Default | LOG_USER | -Specifies the syslog `facility` value. The option has the same meaning as the appropriate parameter described in the [syslog(3) manual](https://man7.org/linux/man-pages/man3/syslog.3.html). +This read-only variable specifies the syslog `facility` value. This variable requires a server restart to change. The option has the same meaning as the appropriate parameter described in the [syslog(3) manual](https://man7.org/linux/man-pages/man3/syslog.3.html). ### `audit_log_filter.syslog_priority` @@ -684,7 +689,7 @@ Specifies the syslog `facility` value. The option has the same meaning as the ap | Data type | String | | Default | LOG_INFO | -Defines the `priority` value for the syslog. The option has the same meaning as the appropriate parameter described in the [syslog(3) manual](https://man7.org/linux/man-pages/man3/syslog.3.html). +This read-only variable defines the `priority` value for the syslog. This variable requires a server restart to change. The option has the same meaning as the appropriate parameter described in the [syslog(3) manual](https://man7.org/linux/man-pages/man3/syslog.3.html). ## Audit log filter status variables diff --git a/docs/css/extra.css b/docs/css/extra.css index 50180c1cc4d..d7fd5898249 100644 --- a/docs/css/extra.css +++ b/docs/css/extra.css @@ -4,11 +4,27 @@ top: 0.6rem; left: 0.6rem; } - -} + } .md-sidebar__inner { font-size: 0.65rem; /* Font size */ line-height: 1.6; } +.edit-page-link { + white-space: nowrap; + display: inline-flex; + align-items: center; + gap: 0.5em; + font-size: 1.2rem; + font-weight: normal; + color: var(--md-typeset-a-color); + text-decoration: underline; +} + +.edit-page-icon svg { + width: 1.40em; + height: 1.40em; + fill: currentColor; + vertical-align: middle; +} diff --git a/docs/downgrade.md b/docs/downgrade.md index 28e8ca377bf..546730b2565 100644 --- a/docs/downgrade.md +++ b/docs/downgrade.md @@ -45,3 +45,17 @@ Downgrading has the following risks: | 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. | + +## 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) +* [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) diff --git a/docs/glossary.md b/docs/glossary.md index 0f8f0656e8c..61d630bae4b 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -8,6 +8,12 @@ Set of properties that guarantee database transactions are processed reliably. S Atomicity means that database operations are applied following a “all or nothing” rule. A transaction is either fully applied or not at all. +## Atomic DDL (Data Definition Language) + +Atomic DDL (Data Definition Language) refers to the concept where DDL operations such as `CREATE`, `ALTER`, `DROP`, or `RENAME` statements are executed in a way that ensures atomicity, meaning they either fully succeed or have no effect at all. + +This means that if a DDL statement fails, the database automatically rolls back any partial changes, leaving the schema in a consistent state. + ## Consistency Consistency means that each transaction that modifies the database takes it from one consistent state to another. diff --git a/docs/index-contents.md b/docs/index-contents.md index ce0e25e7732..17456f1d755 100644 --- a/docs/index-contents.md +++ b/docs/index-contents.md @@ -183,8 +183,7 @@ - [Upgrade from 8.0 to {{vers}} overview](upgrade.md) - [Upgrade strategies](upgrade-strategies.md) - [Upgrade to Percona Server for MySQL Pro](upgrade-pro.md) -- [Upgrade using standalone packages](upgrade-standalone-packages.md) -- [Upgrade using the Percona repositories](upgrade-percona-repos.md) +- [Upgrade procedures for {{vers}}](upgrade-procedures.md) - [Upgrading from plugins to components](upgrade-components.md) - [Use an APT repository to install Percona Server for MySQL {{vers}}](apt-repo.md) - [Use Docker Compose and named volumes](docker-compose.md) diff --git a/docs/index-keywords.md b/docs/index-keywords.md index 30005aaff5f..69520c02ed9 100644 --- a/docs/index-keywords.md +++ b/docs/index-keywords.md @@ -380,8 +380,7 @@ * [Upgrade from 8.0 to {{vers}} overview](upgrade.md) * [Upgrade strategies](upgrade-strategies.md) * [Upgrade to Percona Server for MySQL Pro](upgrade-pro.md) -* [Upgrade using standalone packages](upgrade-standalone-packages.md) -* [Upgrade using the Percona repositories](upgrade-percona-repos.md) +* [Upgrade procedures for {{vers}}](upgrade-procedures.md) * [Upgrading from plugins to components](upgrade-components.md) * [Use an APT repository to install Percona Server for MySQL {{vers}}](apt-repo.md) * [Use Docker Compose and named volumes](docker-compose.md) diff --git a/docs/install-audit-log-filter.md b/docs/install-audit-log-filter.md index 6ff134071d6..fdd03da293f 100644 --- a/docs/install-audit-log-filter.md +++ b/docs/install-audit-log-filter.md @@ -1,24 +1,129 @@ -# Install the Audit Log Filter +# Install the audit log filter -The `plugin_dir` system variable defines the component library location. If needed, at server startup, set the `plugin_dir` variable. +## Installation script -In the `share` directory, locate the `audit_log_filter_linux_install.sql ` script. +The recommended way to install the component is to use the `audit_log_filter_linux_install.sql` script, located in the `share` directory, which creates the required tables before installing the component. -At the time you run the script, you can select the database used to store the JSON filter tables. +### Prerequisites -* If the component is loaded, the installation script takes the database name from the `audit_log_filter.database` variable -* If the component is not loaded, but passes the `-D db_name` to the mysql client when the installation script runs, uses the `db_name`. -* If the component is not loaded and the `-D` option is not provided, the installation script creates the required tables in the default database name `mysql`. +The `plugin_dir` system variable defines the component library location. If needed, set the `plugin_dir` variable at server startup. + +### Database selection + +The script determines the target database using the following priority: + +* If the component is already loaded, the script uses the database name from the `audit_log_filter.database` variable + +* If the component is not loaded, but you pass the `-D db_name` option to the mysql client when running the script, it uses the specified `db_name` + +* If the component is not loaded and no `-D` option is provided, you must specify the `mysql` database when running the script You can also designate a different database with the `audit_log_filter.database` system variable. The database name cannot be NULL or exceed 64 characters. If the database name is invalid, the audit log filter tables are not found. -To install the component, run the following command: +### Install the component + +To install the component using the script, you must specify the `mysql` database. You can do this in two ways: + +* Option 1: Run the script from the command line with the `-D mysql` option: + + ```{.bash data-prompt="$"} + mysql -u root -p -D mysql < /path/to/mysql/share/audit_log_filter_linux_install.sql + ``` + +* Option 2: Connect to `mysql` database and run the script interactively: + + ```{.bash data-prompt="mysql>"} + mysql> use mysql; + mysql> source /path/to/mysql/share/audit_log_filter_linux_install.sql; + ``` + + Replace `/path/to/mysql/share/` with the actual path to your MySQL installation's share directory. + +### Verify installation + +After running the script, verify that the required tables are created: + +```{.bash data-prompt="mysql>"} +mysql> show tables in mysql like 'aud%'; +``` + +??? example "Expected output" + + ```{.text .no-copy} + +------------------------+ + | Tables_in_mysql (aud%) | + +------------------------+ + | audit_log_filter | + | audit_log_user | + +------------------------+ + 2 rows in set (0.00 sec) + ``` + +## Alternative: INSTALL COMPONENT method + +You can also install the component using the `INSTALL COMPONENT` command, but this method does not create the required tables and will cause filter operations to fail. + +### Verify component installation + +Check that the component is properly installed: ```{.bash data-prompt="mysql>"} -mysql> INSTALL COMPONENT 'file://component_audit_log_filter'; +mysql> select * from mysql.component; ``` -Find more information in the [INSTALL COMPONENT](install-component.md) document. +??? example "Expected output" + + ```{.text .no-copy} + +--------------+--------------------+------------------------------------+ + | component_id | component_group_id | component_urn | + +--------------+--------------------+------------------------------------+ + | 1 | 1 | file://component_percona_telemetry | + | 2 | 2 | file://component_audit_log_filter | + +--------------+--------------------+------------------------------------+ + 2 rows in set (0.00 sec) + ``` + +### Test filter functionality + +Test that the audit log filter is working correctly: + +```{.bash data-prompt="mysql>"} +mysql> SELECT audit_log_filter_set_filter('log_all', '{"filter": {"log": true}}'); +``` + +??? example "Expected output" + + ```{.text .no-copy} + +---------------------------------------------------------------------+ + | audit_log_filter_set_filter('log_all', '{"filter": {"log": true}}') | + +---------------------------------------------------------------------+ + | ERROR: Failed to check filtering rule name existence | + +---------------------------------------------------------------------+ + 1 row in set (0.00 sec) + ``` + +!!! note + + This error occurs when the component is installed without the required tables. Using the SQL script prevents this issue. + +### Fix missing tables + +If you have already installed the audit log component but are missing the required tables, you can run the `audit_log_filter_linux_install.sql` script to create the audit tables in the `mysql` database: + +```{.bash data-prompt="$"} +mysql -u root -p -D mysql < /path/to/mysql/share/audit_log_filter_linux_install.sql +``` + +Or interactively: + +```{.bash data-prompt="mysql>"} +mysql> use mysql; +mysql> source /path/to/mysql/share/audit_log_filter_linux_install.sql; +``` + +This operation creates the missing tables without reinstalling the component. + +## Additional information To upgrade from `audit_log_filter` plugin in Percona Server 8.4 to `component_audit_log_filter` component in Percona Server {{vers}}, do the [manual upgrade](upgrade-components.md). diff --git a/docs/jemalloc-profiling.md b/docs/jemalloc-profiling.md index c736d372b6d..4aca189cef8 100644 --- a/docs/jemalloc-profiling.md +++ b/docs/jemalloc-profiling.md @@ -118,7 +118,7 @@ Run the following command: ```shell jeprof --dot /usr/sbin/mysqld /tmp/jeprof_mysqld.1.0.170013202213 > /tmp/jeprof1.dot -dot --Tpng /tmp/jeprof1.dot > /tmp/jeprof1.png +dot -Tpng /tmp/jeprof1.dot > /tmp/jeprof1.png ``` !!! note diff --git a/docs/mysql-upgrade-paths.md b/docs/mysql-upgrade-paths.md new file mode 100644 index 00000000000..5499f6f4805 --- /dev/null +++ b/docs/mysql-upgrade-paths.md @@ -0,0 +1,41 @@ +# MySQL upgrade paths and supported methods + +MySQL supports different upgrade paths depending on the source and target versions. Choose the appropriate method based on your current version and target. + +## Upgrade path matrix + +| Upgrade Path | Path Examples | Supported Upgrade Methods | +| --- | --- | --- | +| 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 | +| 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 | +| 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 | +| 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 | +| 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 | + +## Key considerations + +* **LTS to LTS**: Direct upgrade from 8.0 LTS to 8.4 LTS is supported with multiple methods. +* **Innovation to Innovation**: Cannot skip LTS releases; must upgrade through the LTS series first. +* **MySQL Clone**: Only available for upgrades within the same major version series. +* **Replication**: Available for most upgrade paths but requires careful planning for cross-version replication. + +## Choosing your upgrade method + +* **In-place upgrade**: Fastest but highest risk; requires downtime. +* **Logical dump and load**: Cleanest but slowest for large datasets; requires downtime. +* **Replication**: Minimal downtime but requires additional infrastructure; good for high-availability setups. +* **MySQL Clone**: Fastest for same-series upgrades; requires compatible versions. + +## 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) +* [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) +* [Defaults and tuning guidance for {{vers}}](./8.4-defaults-and-tuning.md) +* [Percona Toolkit updates for {{vers}}](./percona-toolkit-8.4-updates.md) diff --git a/docs/percona-toolkit-8.4-updates.md b/docs/percona-toolkit-8.4-updates.md new file mode 100644 index 00000000000..408e7d0de36 --- /dev/null +++ b/docs/percona-toolkit-8.4-updates.md @@ -0,0 +1,43 @@ +# Percona Toolkit updates for {{vers}} + +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. + +## Terminology alignment + +* Toolkit commands and output now use SOURCE/REPLICA terminology consistent with MySQL {{vers}}. + +## Renamed tools + +* `pt-slave-find` → `pt-replica-find` +* `pt-slave-restart` → `pt-replica-restart` + +Aliases with the old names remain for a transition period; update scripts and runbooks to the new names. + +## Deprecated tool + +* `pt-slave-delay` is deprecated. MySQL {{vers}} support was not added. Use built-in delayed replication features instead. + +## Authentication and SSL + +* Improved SSL handling and consistent support for `caching_sha2_password` and `sha256_password` authentication plugins. + +## What to change in your environment + +* Search automation and scripts for `pt-slave-*` and replace with `pt-replica-*`. +* Remove dependencies on `pt-slave-delay`; use native delayed replication. +* Validate Toolkit connectivity using your TLS settings and modern auth plugins. + +## 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) +* [Defaults and tuning guidance for {{vers}}](./8.4-defaults-and-tuning.md) + diff --git a/docs/upgrade-checklist-8.4.md b/docs/upgrade-checklist-8.4.md new file mode 100644 index 00000000000..2e3fa5ed86c --- /dev/null +++ b/docs/upgrade-checklist-8.4.md @@ -0,0 +1,159 @@ +# Upgrade checklist for {{vers}} + +Thorough preparation and validation reduce risk more than any cutover tactic. Use this checklist to guide your upgrade from 8.0 to {{vers}}, validating each item in staging before upgrading production. + +## Pre-upgrade checks + +Complete these checks before starting the upgrade process. + +### Authentication and connectivity + +**Impact**: `mysql_native_password` is disabled by default in {{vers}}; `default_authentication_plugin` is removed. New accounts default to `caching_sha2_password`. The `mysql_native_password` plugin can still be loaded using `--mysql-native-password=ON` if needed, but it will be completely removed in the MySQL 9.x series. + +**Action**: + +- [ ] Inventory accounts and applications that still use `mysql_native_password`. +- [ ] Verify drivers/clients support `caching_sha2_password` and TLS as configured. +- [ ] Plan account migration to `caching_sha2_password`. If temporary compatibility is needed, `--mysql-native-password=ON` can be used, but plan migration as this plugin will be removed in future versions. +- [ ] See: [authentication methods](./authentication-methods.md) + +### Replication and operational scripts + +**Impact**: MASTER/SLAVE syntax is removed; use SOURCE/REPLICA commands. + +**Action**: + +- [ ] Search and update scripts: `START REPLICA`, `SHOW REPLICA STATUS`, `CHANGE REPLICATION SOURCE TO`. +- [ ] Validate Orchestrator/HA tooling versions for {{vers}} syntax. +- [ ] Update Percona Toolkit calls: replace `pt-slave-find` with `pt-replica-find`, and `pt-slave-restart` with `pt-replica-restart`; remove `pt-slave-delay` usage. +- [ ] See: [Percona Toolkit updates for {{vers}}](./percona-toolkit-8.4-updates.md) + +### Removed features and variables + +**Impact**: Several legacy statements, status counters, variables, and functions are removed in {{vers}}. + +**Action**: + +- [ ] Replace MASTER/SLAVE statements and counters with SOURCE/REPLICA equivalents. +- [ ] Migrate from `expire_logs_days` to `binlog_expire_logs_seconds`. +- [ ] Replace `WAIT_UNTIL_SQL_THREAD_AFTER_GTIDS()` with `WAIT_FOR_EXECUTED_GTID_SET()`. +- [ ] Remove dependencies on built-in memcached variables/APIs. +- [ ] See: [Breaking and incompatible changes in {{vers}}](./8.4-breaking-changes.md) + +### Reserved keywords in identifiers + +**Impact**: New reserved words (for example, `MANUAL`, `PARALLEL`, `QUALIFY`, `TABLESAMPLE`) can break schemas and queries. + +**Action**: + +- [ ] Scan object names and queries for unquoted usage; quote or rename as needed. +- [ ] 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. + + +### Schema constraints + +**Impact**: `AUTO_INCREMENT` is not allowed on `FLOAT`/`DOUBLE`. + +**Action**: + +- [ ] Identify and convert any `FLOAT`/`DOUBLE` `AUTO_INCREMENT` columns to integer types prior to upgrade. + +### Configuration defaults review + +**Impact**: {{vers}} changes several InnoDB defaults for modern hardware; old 8.0 configs may not be optimal and can cause behavior changes. + +**Action**: + +- [ ] Compare your overrides to {{vers}} defaults; remove obsolete settings and re-evaluate IO/log parameters. +- [ ] See: [Defaults and tuning guidance for {{vers}}](./8.4-defaults-and-tuning.md) + +### Spatial indexes + +**Impact**: A known issue may corrupt a spatial index after certain update/delete sequences across upgrade. + +**Action**: + +- [ ] Drop spatial indexes before upgrade (document which ones for post-upgrade re-creation). +- [ ] Plan to re-create spatial indexes after upgrade completion. + +### Backup and recovery rehearsal + +**Action**: + +- [ ] Take a hot backup with Percona XtraBackup; document restore steps and timings. +- [ ] Restore into a clean {{vers}} environment; validate startup and metadata upgrade. +- [ ] See: [Backup and restore overview](./backup-restore-overview.md) + +### Behavior comparison and testing + +**Action**: + +- [ ] Use `pt-upgrade` to compare query plans/behavior between 8.0 and {{vers}}. +- [ ] Run application smoke and load tests against a restored {{vers}} copy. + +### Plugins to components transitions + +**Impact**: Some 8.0 plugins are removed or replaced by components in {{vers}}. + +**Action**: + +- [ ] If a component exists in 8.0 (for example, data masking), transition in 8.0 before upgrading. +- [ ] Plan configuration changes from plugin variables/`--early-plugin-load` to component manifests/config files. +- [ ] See: [Upgrade from plugins to components](./upgrade-components.md) + +### Rollback feasibility + +**Action**: + +- [ ] Define a rollback path (for example, keep 8.0 environment on standby or validate point-in-time recovery to 8.0-compatible readers if applicable). +- [ ] Confirm cutover/rollback runbooks with approvers. + +## Post-upgrade validation + +Run these checks immediately after upgrading from 8.0 to {{vers}} and before widening traffic. + +### Connectivity and authentication + +- [ ] Verify application logins for every service account. +- [ ] Confirm new account creations default to `caching_sha2_password` as expected. + +### Replication health (if applicable) + +- [ ] Confirm `SHOW REPLICA STATUS` reports healthy IO/SQL threads. +- [ ] Exercise planned failover and change-source procedures. + +### Spatial indexes + +- [ ] Re-create any spatial indexes dropped pre-upgrade. +- [ ] Run integrity checks and representative spatial queries. + +### Workload and performance baselines + +- [ ] Re-run baseline queries and workload tests; compare latency and throughput. +- [ ] Review changes in 8.4 defaults that can affect performance (optimizer/costing, redo/undo, IO settings) and tune as needed. +- [ ] See: [Defaults and tuning guidance for {{vers}}](./8.4-defaults-and-tuning.md) + +### Logs and observability + +- [ ] Review error logs and warnings post-startup and during smoke tests. +- [ ] Inspect Performance Schema metrics and application SLOs for regressions. + +### Backup and recovery + +- [ ] Take a fresh full backup with Percona XtraBackup. +- [ ] Optionally perform a spot restore test to validate recovery on {{vers}}. + +## Further reading + +* [Upgrade overview](./upgrade.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) +* [Defaults and tuning guidance for {{vers}}](./8.4-defaults-and-tuning.md) +* [Percona Toolkit updates for {{vers}}](./percona-toolkit-8.4-updates.md) + diff --git a/docs/upgrade-components.md b/docs/upgrade-components.md index cc1bd209227..ad62be1f909 100644 --- a/docs/upgrade-components.md +++ b/docs/upgrade-components.md @@ -1,19 +1,19 @@ -# Upgrading from plugins to components +# Upgrade from plugins to components [Need help navigating plugin to component transitions? Percona Support can assist].(https://www.percona.com/services/support) +Percona Server for MySQL {{vers}} introduces a shift from plugins to components for several key features, a change that requires a manual transition during the upgrade process. It is generally recommended to transition to the component version of a feature in the 8.0 series before performing the upgrade to {{vers}} if both a plugin and a component are available for that feature. + The following plugins have changed: | Plugin | 8.0 information | {{vers}} changes | Notes | |---|---|---|---| -| `keyring_vault` | Only available as a plugin | `component_keyring_vault` | A manual upgrade path is required. For example, the plugin configuration file, specified by the `keyring_vault_config` system variable, must be transformed to a JSON format for the `component_keyring_vault.cnf`. | -| `audit_log` | Only available as a plugin | removed | Recommended that you use the `component_audit_log_filter`. | -| `audit_log_filter` | Only available as a plugin | `component_audit_log_filter` | Transition the plugin to the component after the upgrade to {{vers}}. | -| `data_masking` | Available as a plugin and component | `component_masking_functions` | Transition the plugin to the component in 8.0 before the upgrade to {{vers}} | -| `binlog_utils_udf` user defined functions | Only available as plugin. Users must install the plugin and then run `CREATE FUNCTION ... SONAME...` | `component_binlog_utils_udf` | Run `INSTALL COMPONENT` and all functions are registered automatically. | -| `percona-udf` user defined functions | Must create individual functions with `CREATE FUNCTION ... SONAME ...`. | `component_percona_udf` | Run `INSTALL COMPONENT` and all functions are registered automatically. Can still use `CREATE FUNCTION ... SONAME ...` if needed. | +| `keyring_vault` | Only available as a plugin | `component_keyring_vault` | This plugin has been replaced by the `component_keyring_vault` component. The upgrade requires a manual conversion of the plugin's configuration file from the `keyring_vault_config` system variable format to a JSON format. | +| `audit_log` | Only available as a plugin | removed | This plugin has been removed entirely in {{vers}}. The recommended replacement is `component_audit_log_filter`. | +| `audit_log_filter` | Only available as a plugin | `component_audit_log_filter` | This plugin has a corresponding component. The transition to the component should be performed after the upgrade to {{vers}}. | +| `data_masking` | Available as a plugin and component | `component_masking_functions` | For this feature, it is specifically advised to transition to the `component_masking_functions` in the 8.0 series before upgrading to {{vers}}. | +| `binlog_utils_udf` and `percona-udf` user defined functions | Previously installed via a plugin. Users must install the plugin and then run `CREATE FUNCTION ... SONAME ...` for each function. | `component_binlog_utils_udf` and `component_percona_udf` | These user-defined functions, previously installed via plugins, are now available as components. After running `INSTALL COMPONENT`, all functions are automatically registered, which simplifies the process. | -We recommend if you use a plugin and the feature also available a component, switch to the component in 8.0 series before upgrading to {{vers}}. ## Transition a plugin to a component @@ -25,16 +25,22 @@ The operation to transition from a plugin to a component can be complicated. Alw * Verify that the existing functionality transfers correctly -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. +Before you start, review the differences between the plugin and the component. The configuration of these features changes: plugins use system variables and the `--early-plugin-load` option, while components rely on a separate configuration file and are loaded using a manifest. + +General procedure: + +The general procedure for transitioning from a plugin to a component involves: 1. Setup the component's configuration file. -2. Load the component using the manifest. +2. Load the component using the manifest (`INSTALL COMPONENT` or manifest file, as applicable). -3. Confirm that the component works. Run queries or other operations and test the component thoroughtly in your test environment. +3. Confirm that the component works. Thoroughly test the component's functionality in your staging environment. Run queries or other operations to verify all existing functionality is correctly transferred. 4. After confirmation, remove the original plugin. +This process should be carefully planned to minimize downtime and ensure that all existing functionality is correctly transferred. + Some plugins may require more configuration and setup during the transition to a component. For those plugins, you may have the following scenario: 1. Test the plugin in 8.0. @@ -47,4 +53,27 @@ Some plugins may require more configuration and setup during the transition to a 5. Start the new {{vers}} -6. Confirm the component in {{vers}} \ No newline at end of file +6. Confirm the component in {{vers}} + +## 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 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) +* [Defaults and tuning guidance for {{vers}}](./8.4-defaults-and-tuning.md) +* [Percona Toolkit updates for {{vers}}](./percona-toolkit-8.4-updates.md) + +### Component-specific documentation + +* [Install a component](./install-component.md) +* [Uninstall a component](./uninstall-component.md) +* [Use Keyring Vault component](./use-keyring-vault-component.md) +* [Install Data Masking component](./install-data-masking-component.md) +* [Audit Log Filter component overview](./audit-log-filter-overview.md) +* [Manage Audit Log Filter](./manage-audit-log-filter.md) \ No newline at end of file diff --git a/docs/upgrade-percona-repos.md b/docs/upgrade-percona-repos.md deleted file mode 100644 index 1e45191dc92..00000000000 --- a/docs/upgrade-percona-repos.md +++ /dev/null @@ -1,113 +0,0 @@ -# Upgrade using the Percona repositories - -[Need expert guidance for your Percona Server upgrade? Percona Support is here to help.](https://www.percona.com/services/support) - -We recommend using the Percona repositories to upgrade your server. - -Find the instructions on how to enable the repositories in the following documents: - -* [Percona APT Repository](apt-repo.md) - -* [Percona RPM Repository](yum-repo.md) - - -=== "DEB-based distributions" - - Run the following commands as root or use the `sudo` command. - - - 1. Make a full backup (or dump if possible) of your database. Move the database configuration file, `my.cnf`, to another directory to save it. If the configuration file is not moved, it can be overwritten. - - - 2. Stop the server with the appropriate command for your system: - - ```{.bash data-prompt="$"} - systemctl stop mysql` - ``` - - 3. Modify the database configuration file, `my.cnf`, as needed. - - 4. Install Percona Server for MySQL: - - ```{.bash data-prompt="$"} - $ sudo apt update - $ sudo apt install curl - $ curl -O https://repo.percona.com/apt/percona-release_latest.generic_all.deb - $ sudo apt install gnupg2 lsb-release ./percona-release_latest.generic_all.deb - $ sudo apt update - $ sudo percona-release setup {{pkg}} - $ sudo apt install percona-server-server - ``` - - 5. Install the storage engine packages. - - If you used the MyRocks storage engine in Percona Server for MySQL {{vers}}, install the `percona-server-rocksdb` package: - - ```{.bash data-prompt="$"} - $ sudo apt install percona-server-rocksdb - ``` - - 6. Running the upgrade: - - The mysqld binary automatically runs the upgrade process if needed. To find more information, see [MySQL Upgrade Process Upgrades](https://dev.mysql.com/doc/refman/{{vers}}/en/upgrading-what-is-upgraded.html) - - 7. Restart the service - - ```{.bash data-prompt="$"} - $ sudo systemctl restart mysqld - ``` - After the service has been successfully restarted you can use the new Percona Server for MySQL {{vers}}. - -=== "RPM-based distributions" - - Run the following commands as root or use the sudo command. - - - 1. Make a full backup (or dump if possible) of your database. Copy the database configuration file, for example, `my.cnf`, to another directory to save it. - - - 2. Stop the server with the appropriate command for your system: - - ```{.bash data-prompt="$"} - $ systemctl stop mysql` - ``` - - 3. Check your installed packages with `rpm -qa | grep Percona-Server`. - - 4. Remove only the packages without dependencies and leave dependent packages. The command does not prompt for confirmation: - - ```{.bash data-prompt="$"} - $ rpm -qa | grep Percona-Server | xargs rpm -e --nodeps - ``` - - 5. Remove the mysql-related packages, run: - - ```{.bash data-prompt="$"} - $ rpm -qa | grep '^mysql-' | xargs rpm -e --nodeps - ``` - - - 6. Install the `percona-server-server` package: - - ```{.bash data-prompt="$"} - $ sudo yum install https://repo.percona.com/yum/percona-release-latest.noarch.rpm - $ sudo percona-release setup {{pkg}} - $ sudo yum install percona-server-server - ``` - - 7. Install the storage engine packages. - - If you used the MyRocks storage engine in the previous version, install the `percona-server-rocksdb` package: - - ```{.bash data-prompt="$"} - $ yum install percona-server-rocksdb - ``` - - 8. Modify your configuration file, `my.cnf`, and reinstall the plugins if necessary. - - - 2. Running the upgrade - - The mysqld binary automatically runs the upgrade process if needed. To find more information, see [MySQL Upgrade Process Upgrades](https://dev.mysql.com/doc/refman/{{vers}}/en/upgrading-what-is-upgraded.html) - - Restart the server and you can use the Percona Server for MySQL {{vers}}. diff --git a/docs/upgrade-procedures.md b/docs/upgrade-procedures.md new file mode 100644 index 00000000000..02fb2631af0 --- /dev/null +++ b/docs/upgrade-procedures.md @@ -0,0 +1,329 @@ +# Upgrade procedures for {{vers}} + +[Need expert guidance for your Percona Server upgrade? Percona Support is here to help.](https://www.percona.com/services/support) + +This document provides step-by-step procedures for upgrading Percona Server for MySQL using either Percona repositories (recommended) or standalone packages. + +Before beginning the upgrade process: + +1. Complete the [upgrade checklist](./upgrade-checklist-8.4.md) pre-upgrade checks. +2. Create a full backup (or dump if possible) of your database. +3. Move your database configuration file (`my.cnf`) to a safe location (repository method) or modify it as needed before stopping the server. +4. Stop the server using the appropriate command for your system: + + ```{.bash} + sudo systemctl stop mysql + ``` + +!!! warning "Critical" + + Always test the upgrade process in a non-production environment first. For detailed upgrade procedures or if you encounter any issues during this process, our [Percona Support team](https://www.percona.com/services/support) is available to assist you. + +## Using Percona repositories (recommended) + +We recommend using the Percona repositories to upgrade your server. This method automatically handles dependencies and simplifies the upgrade process. + +Find the instructions on how to enable the repositories in the following documents: + +* [Percona APT Repository](./apt-repo.md) +* [Percona RPM Repository](./yum-repo.md) + +=== "DEB-based distributions" + + Run the following commands as root or use the `sudo` command. + + 1. Make a full backup (or dump if possible) of your database. Move the database configuration file, `my.cnf`, to another directory to save it. If the configuration file is not moved, it can be overwritten. + + 2. Stop the server with the appropriate command for your system: + + ```{.bash} + sudo systemctl stop mysql + ``` + + 3. Modify the database configuration file, `my.cnf`, as needed. + + 4. Install Percona Server for MySQL: + + ```{.bash} + sudo apt update + sudo apt install curl + curl -O https://repo.percona.com/apt/percona-release_latest.generic_all.deb + sudo apt install gnupg2 lsb-release ./percona-release_latest.generic_all.deb + sudo apt update + sudo percona-release setup {{pkg}} + sudo apt install percona-server-server + ``` + + 5. Install the storage engine packages. + + If you used the MyRocks storage engine in Percona Server for MySQL {{vers}}, install the `percona-server-rocksdb` package: + + ```{.bash} + sudo apt install percona-server-rocksdb + ``` + + 6. The mysqld binary automatically runs the upgrade process if needed. To find more information, see [MySQL Upgrade Process](https://dev.mysql.com/doc/refman/{{vers}}/en/upgrading-what-is-upgraded.html). + + 7. Restart the service: + + ```{.bash} + sudo systemctl restart mysql + ``` + + After the service has been successfully restarted, you can use the new Percona Server for MySQL {{vers}}. + +=== "RPM-based distributions" + + Run the following commands as root or use the `sudo` command. + + 1. Make a full backup (or dump if possible) of your database. Copy the database configuration file, for example, `my.cnf`, to another directory to save it. + + 2. Stop the server with the appropriate command for your system: + + ```{.bash} + sudo systemctl stop mysql + ``` + + 3. Check your installed packages: + + ```{.bash} + rpm -qa | grep Percona-Server + ``` + + 4. Remove only the packages without dependencies and leave dependent packages. The command does not prompt for confirmation: + + ```{.bash} + rpm -qa | grep Percona-Server | xargs rpm -e --nodeps + ``` + + 5. Remove the mysql-related packages: + + ```{.bash} + rpm -qa | grep '^mysql-' | xargs rpm -e --nodeps + ``` + + 6. Install the `percona-server-server` package: + + ```{.bash} + sudo yum install https://repo.percona.com/yum/percona-release-latest.noarch.rpm + sudo percona-release setup {{pkg}} + sudo yum install percona-server-server + ``` + + 7. Install the storage engine packages. + + If you used the MyRocks storage engine in the previous version, install the `percona-server-rocksdb` package: + + ```{.bash} + sudo yum install percona-server-rocksdb + ``` + + 8. Modify your configuration file, `my.cnf`, and reinstall the plugins if necessary. + + 9. The mysqld binary automatically runs the upgrade process if needed. To find more information, see [MySQL Upgrade Process](https://dev.mysql.com/doc/refman/{{vers}}/en/upgrading-what-is-upgraded.html). + + 10. Restart the server: + + ```{.bash} + sudo systemctl restart mysql + ``` + + After the service has been successfully restarted, you can use the Percona Server for MySQL {{vers}}. + +## Using standalone packages + +Use this method when you cannot use repositories or need to install from manually downloaded packages. This method requires you to manually resolve dependencies. + +=== "Debian-derived distributions" + + 1. Remove the installed packages with their dependencies: + + ```{.bash} + sudo apt autoremove percona-server percona-client + ``` + + 2. Do the required modifications in the database configuration file `my.cnf`. + + 3. Download the following packages for your architecture: + + * `percona-server-server` + * `percona-server-client` + * `percona-server-common` + * `libperconaserverclient21` + + The following example downloads Percona Server for MySQL {{release}} packages for Debian 11.0: + + ```{.bash} + wget https://downloads.percona.com/downloads/Percona-Server-innovative-release/Percona-Server-{{release}}/binary/debian/bullseye/x86_64/Percona-Server-{{release}}-r582ebeef-bullseye-x86_64-bundle.tar + ``` + + 4. Unpack the bundle to get the packages: + + ```{.bash} + tar xvf Percona-Server-{{release}}-r582ebeef-bullseye-x86_64-bundle.tar + ``` + + After you unpack the bundle, you should see the following packages: + + ```{.bash} + ls *.deb + ``` + + ??? example "Expected output" + + ```{.text .no-copy} + libperconaserverclient21-dev_{{release}}.bullseye_amd64.deb + percona-server-dbg_{{release}}.bullseye_amd64.deb + libperconaserverclient21_{{release}}.bullseye_amd64.deb + percona-server-rocksdb_{{release}}.bullseye_amd64.deb + percona-mysql-router_{{release}}.bullseye_amd64.deb + percona-server-server_{{release}}.bullseye_amd64.deb + percona-server-client_{{release}}.bullseye_amd64.deb + percona-server-source_{{release}}.bullseye_amd64.deb + percona-server-common_{{release}}.bullseye_amd64.deb + percona-server-test_{{release}}.bullseye_amd64.deb + ``` + + 5. Install Percona Server for MySQL: + + ```{.bash} + sudo dpkg -i *.deb + ``` + + This command installs the packages from the bundle. Another option is to download or specify only the packages you need for running Percona Server for MySQL installation (`libperconaserverclient21_{{release}}.bullseye_amd64.deb`, `percona-server-client-{{release}}.bullseye_amd64.deb`, `percona-server-common-{{release}}.bullseye_amd64.deb`, and `percona-server-server-{{release}}.bullseye_amd64.deb`). + + !!! warning + + When installing packages manually, you must resolve all the dependencies and install missing packages yourself. At least the following packages should be installed before installing Percona Server for MySQL {{release}}: + * `libmecab2` + * `libjemalloc1` + * `zlib1g-dev` + * `libaio1` + + 6. The mysqld binary automatically runs the upgrade process. To find more information, see [MySQL Upgrade Process](https://dev.mysql.com/doc/refman/{{release}}/en/upgrading-what-is-upgraded.html). + + 7. Restart the service: + + ```{.bash} + sudo service mysql restart + ``` + + After the service has been successfully restarted, use the new Percona Server for MySQL {{release}}. + +=== "Red Hat-derived distributions" + + 1. Check the installed packages: + + ```{.bash} + rpm -qa | grep percona-server + ``` + + ??? example "Expected output" + + ```{.text .no-copy} + percona-server-shared-{{release}}.el9.x86_64 + percona-server-shared-compat-{{release}}.el9.x86_64 + percona-server-client-{{release}}.el9.x86_64 + percona-server-server-{{release}}.el9.x86_64 + ``` + + You may have the `shared-compat` package, which is required for compatibility. + + 2. Remove the packages without dependencies: + + ```{.bash} + rpm -qa | grep percona-server | xargs rpm -e --nodeps + ``` + + It is important that you remove the packages without dependencies as many packages may depend on these (as they replace `mysql`) and will be removed if omitted. + + To remove the listed packages, run: + + ```{.bash} + rpm -qa | grep '^mysql-' | xargs rpm -e --nodeps + ``` + + 3. Download the packages of the desired series for your architecture from the [download page](https://www.percona.com/downloads). The easiest way is to download the bundle which contains all the packages. The following example downloads Percona Server for MySQL {{release}} packages for CentOS 9: + + ```{.bash} + wget https://downloads.percona.com/downloads/Percona-Server-innovative-release/Percona-Server-{{release}}/binary/redhat/9/x86_64/Percona-Server-{{release}}-r582ebeef-el9-x86_64-bundle.tar + ``` + + 4. Unpack the bundle to get the packages: + + ```{.bash} + tar xvf Percona-Server-{{release}}-r582ebeef-el9-x86_64-bundle.tar + ``` + + After you unpack the bundle, you should see the following packages: + + ```{.bash} + ls *.rpm + ``` + + 5. Install Percona Server for MySQL: + + ```{.bash} + sudo rpm -ivh percona-server-server-{{release}}.el9.x86_64.rpm \ + percona-server-client-{{release}}.el9.x86_64.rpm \ + percona-server-shared-{{release}}.el9.x86_64.rpm \ + percona-server-shared-compat-{{release}}.el9.x86_64.rpm + ``` + + This command installs only packages required to run the Percona Server for MySQL {{release}}. + + You can install all the packages (for debugging, testing, etc.) with: + + ```{.bash} + sudo rpm -ivh *.rpm + ``` + + !!! note + + When manually installing packages, you must resolve all the dependencies and install missing ones. + + 6. Modify your configuration file, `my.cnf`, and install the plugins if necessary. + + RHEL/CentOS automatically backs up the previous configuration file to `/etc/my.cnf.rpmsave` and installs the default `my.cnf`. After the upgrade/install process completes, you can move the old configuration file back (after you remove all the unsupported system variables). + + 7. The schema of the grant table has changed, the server must be started without reading the grants. Add a line to `my.cnf` in the `[mysqld]` section: + + ```{.text .no-copy} + [mysqld] + skip-grant-tables + ``` + + Restart the mysql server: + + ```{.bash} + sudo service mysql start + ``` + + 8. The mysqld binary automatically runs the upgrade process. To find more information, see [MySQL Upgrade Process](https://dev.mysql.com/doc/refman/{{vers}}/en/upgrading-what-is-upgraded.html). + + 9. Remove the `skip-grant-tables` line from `my.cnf` and restart the server: + + ```{.bash} + sudo service mysql restart + ``` + + After the service has been successfully restarted, you can use the new Percona Server for MySQL {{release}}. + +## Post-upgrade validation + +After completing the upgrade, follow the post-upgrade validation steps in the [upgrade checklist](./upgrade-checklist-8.4.md#post-upgrade-validation). + +## Further reading + +* [Upgrade overview](./upgrade.md) +* [Upgrade checklist for {{vers}}](./upgrade-checklist-8.4.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) +* [Defaults and tuning guidance for {{vers}}](./8.4-defaults-and-tuning.md) +* [Percona Toolkit updates for {{vers}}](./percona-toolkit-8.4-updates.md) + diff --git a/docs/upgrade-standalone-packages.md b/docs/upgrade-standalone-packages.md deleted file mode 100644 index c8998635d2c..00000000000 --- a/docs/upgrade-standalone-packages.md +++ /dev/null @@ -1,165 +0,0 @@ -# Upgrade using standalone packages - - -Before beginning the upgrade process: - -1. Create a full backup (or dump if possible) of your database - -2. Move your database configuration file (`my.cnf`) to a safe location - -3. Stop the server using `/etc/init.d/mysql stop` - -For detailed upgrade procedures or if you encounter any issues during this process, our [Percona support team](https://www.percona.com/services/support) is available to assist you. - -=== "Debian-derived distribution" - - 1. Remove the installed packages with their dependencies: `sudo apt autoremove percona-server percona-client` - - 2. Do the required modifications in the database configuration file `my.cnf`. - - 3. Download the following packages for your architecture: - - * `percona-server-server` - - * `percona-server-client` - - * `percona-server-common` - - * `libperconaserverclient21` - - The following example downloads Percona Server for MySQL {{release}} packages for Debian 11.0: - - ```{.bash data-prompt="$"} - $ wget https://downloads.percona.com/downloads/Percona-Server-innovative-release/Percona-Server-{{release}}/binary/debian/bullseye/x86_64/Percona-Server-{{release}}-r582ebeef-bullseye-x86_64-bundle.tar - ``` - - 4. Unpack the bundle to get the packages: `tar xvf Percona-Server-{{release}}-x86_64-bundle.tar`. - - After you unpack the bundle, you should see the following packages: - - ```{.bash data-prompt="$"} - $ ls *.deb - ``` - - ??? example "Expected output" - - ```{.text .no-copy} - llibperconaserverclient21-dev_{{release}}.bullseye_amd64.deb - percona-server-dbg_{{release}}.bullseye_amd64.deb - libperconaserverclient21_{{release}}.bullseye_amd64.deb - percona-server-rocksdb_{{release}}.bullseye_amd64.deb - percona-mysql-router_{{release}}.bullseye_amd64.deb - percona-server-server_{{release}}.bullseye_amd64.deb - percona-server-client_{{release}}.bullseye_amd64.deb - percona-server-source_{{release}}.bullseye_amd64.deb - percona-server-common_{{release}}.bullseye_amd64.deb - percona-server-test_{{release}}.bullseye_amd64.deb - ``` - - 5. Install Percona Server for MySQL: - - ```{.bash data-prompt="$"} - $ sudo dpkg -i *.deb - ``` - - This command installs the packages from the bundle. Another option is to - download or specify only the packages you need for running Percona Server for MySQL - installation (`libperconaserverclient21-dev_{{release}}.bullseye_amd64.deb`, - `percona-server-client-{{release}}.bullseye_amd64.deb`, - `percona-server-common-{{release}}.bullseye_amd64.deb`, and - `percona-server-server-{{release}}.bullseye_amd64.deb`. - - !!! warning - - When installing packages manually, you must resolve all the dependencies and install missing packages yourself. At least - the following packages should be installed before installing Percona Server for MySQL {{release}}: - \* `libmecab2`, - \* `libjemalloc1`, - \* `zlib1g-dev`, - \* `libaio1`. - - 6. Running the upgrade: - - The mysqld binary automatically runs the upgrade process. To find more information, see [MySQL Upgrade Process Upgrades](https://dev.mysql.com/doc/refman/{{release}}/en/upgrading-what-is-upgraded.html) - - 7. Restart the service with `service mysql restart`. After the service has been successfully restarted use the new Percona Server for MySQL {{release}}. - -=== "Red Hat-derived distributions" - - 1. Check the installed packages: - - ```{.bash data-prompt="$"} - $ rpm -qa | grep percona-server - ``` - - ??? example "Expected output" - - ```{.text .no-copy} - percona-server-shared-{{release}}.el9.x86_64 - percona-server-shared-compat-{{release}}.el9.x86_64 - percona-server-client-{{release}}.el9.x86_64 - percona-server-server-{{release}}.el9.x86_64 - ``` - - You may have the `shared-compat` package, which is required for compatibility. - - 2. Remove the packages without dependencies with `rpm -qa | grep percona-server | xargs rpm -e --nodeps`. - - It is important that you remove the packages without dependencies as many packages may depend on these (as they replace `mysql`) and will be removed if omitted. - - To remove the listed packages, run: - - ```{.bash data-prompt="$"} - $ rpm -qa | grep '^mysql-'| xargs rpm -e --nodeps` - ``` - - 3. Download the packages of the desired series for your architecture from the [download page](https://www.percona.com/downloads). The easiest way is to download the bundle which contains all the packages. The following example downloads Percona Server for MySQL {{release}} packages for CentOS 9: - - ```{.bash data-prompt="$"} - $ wget https://downloads.percona.com/downloads/Percona-Server-innovative-release/Percona-Server-{{release}}/binary/redhat/9/x86_64/Percona-Server-{{release}}-r582ebeef-el9-x86_64-bundle.tar - ``` - - 4. Unpack the bundle to get the packages - - ```{.bash data-prompt="$"} - $ tar xvf Percona-Server-{{release}}-r582ebeef-el9-x86_64-bundle.tar - ``` - - After you unpack the bundle, you should see the following packages: `ls \*.rpm` - - 5. Install Percona Server for MySQL: - - ```{.bash data-prompt="$"} - $ sudo rpm -ivh percona-server-server-{{release}}.el9.x86_64.rpm \ - > percona-server-client-{{release}}.el9.x86_64.rpm \ - > percona-server-shared-{{release}}.el9.x86_64.rpm \ - > percona-server-shared-compat-{{release}}.el9.x86_64.rpm - ``` - - This command installs only packages required to run the Percona Server for MySQL - {{release}}. - - 6. You can install all the packages (for debugging, testing, etc.) with `sudo rpm -ivh \*.rpm`. - - !!! note - - When manually installing packages, you must resolve all the dependencies and install missing ones. - - 7. Modify your configuration file, `my.cnf`, and install the plugins if necessary. - - RHEL/CentOS automatically backs up the previous configuration file to `/etc/my.cnf.rpmsave` and installs the default `my.cnf`. After the upgrade/install process completes you can move the old configuration file back (after you remove all the unsupported system variables). - - 8. The schema of the grant table has changed, the server must be started without reading the grants. Add a line to my.cnf in the [mysqld] section, - - ```{.text .no-copy} - [mysqld] - skip-grant-tables - ``` - - Restart the mysql server with `service mysql start`. - - 9. Running the upgrade: - - The mysqld binary automatically runs the upgrade process. To find more information, see [MySQL Upgrade Process Upgrades](https://dev.mysql.com/doc/refman/{{vers}}/en/upgrading-what-is-upgraded.html) - - 10. Restart the server with `service mysql restart`. After the service has been successfully restarted you can use the new Percona Server for MySQL {{release}}. diff --git a/docs/upgrade-strategies.md b/docs/upgrade-strategies.md index bdfdd405cfa..23eb52a58b3 100644 --- a/docs/upgrade-strategies.md +++ b/docs/upgrade-strategies.md @@ -38,3 +38,71 @@ The new environment strategy has the following pros and cons: * Allows upgrade of hardware easily. * Requires only a single cutover window. + +## 8.0 → {{vers}} migration methods + +Choose the approach that matches your downtime budget, risk tolerance, and rollback needs. Always rehearse in a non-production environment first. + +> **Note**: For a complete overview of supported upgrade paths and methods, see [MySQL upgrade paths and supported methods](./mysql-upgrade-paths.md). + +### 1) In-place upgrade (stop/replace/start) + +Downtime: short to moderate + +Risk: higher (shared data directory; fewer rollback options) + +Use when: the environment is simple, downtime is acceptable, and you have strong backups and validation. + +Prerequisites: + +* Complete [Upgrade checklist](./upgrade-checklist-8.4.md) pre-upgrade checks +* Set `innodb_fast_shutdown=0` for a clean shutdown +* Verified backup and restore + +Rollback: restore backup and revert binaries. + +### 2) Logical dump and restore (clean rebuild) + +Downtime: moderate to high (data size dependent) + +Risk: moderate (clean metadata; slower for large datasets) + +Use when: you want a pristine {{vers}} instance and can accept longer downtime. + +Prerequisites: + +* Sufficient capacity for parallel dump/restore +* Application maintenance window sized to data volume + +Rollback: keep 8.0 online until validation completes; redirect traffic back if needed. + +### 3) Side-by-side with replication and controlled cutover + +Downtime: minimal (cutover only) + +Risk: lower (new environment; defined fallback until fail-forward) + +Use when: you need the smallest outage and can provision a parallel environment. + +Prerequisites: + +* Build a new {{vers}} environment; establish replication from 8.0 +* Validate workload on the replica(s) and rehearse failover + +Cutover: stop writes on 8.0, allow replica to catch up, redirect traffic (VIP/DNS), then promote {{vers}}. + +Rollback: if issues arise before fail-forward, redirect traffic back to 8.0 and resume writes. + +## Further reading + +* [Upgrade overview](./upgrade.md) +* [Upgrade checklist for {{vers}}](./upgrade-checklist-8.4.md) +* [Upgrade procedures for {{vers}}](./upgrade-procedures.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) +* [Defaults and tuning guidance for {{vers}}](./8.4-defaults-and-tuning.md) +* [Percona Toolkit updates for {{vers}}](./percona-toolkit-8.4-updates.md) diff --git a/docs/upgrade.md b/docs/upgrade.md index 74abadaa106..c73292f681e 100644 --- a/docs/upgrade.md +++ b/docs/upgrade.md @@ -2,41 +2,149 @@ --8<--- "get-help-snip.md" -[Need expert guidance for your upgrade? Percona Support is here to help.](https://www.percona.com/services/support). +[Need expert guidance for your upgrade? Percona Support is ready to assist you every step of the way.](https://www.percona.com/services/support). -Upgrading your server to {{vers}} has the following benefits: +## Why upgrade to Percona Server for MySQL {{vers}} LTS -| Benefits | Description | -| --- | --- | -| Security fixes | These patches and updates protect your data from cyberattacks and address vulnerabilities or bugs in the database software.| -| New or improved features | You have access to new or improved features that enhance the functionality, performance, and availability of the database. | -| Reduced labor | You can automate some routine tasks. | -| Relevance | Your customers and stakeholders have changing needs and expectations. Using the latest version can help to deliver solutions faster. | -| Reduced operational costs | An upgraded database server can help reduce your operational costs because the server has improved efficiency and scalability. | +Long‑Term Support (LTS) releases focus on stability, predictable security patches, and a clearly defined maintenance horizon—essential qualities for production databases. Moving from 8.0 to 8.4 isn’t just a simple version bump: new defaults, deprecated options, and behavior changes can affect performance and break existing scripts. Treat the upgrade as a small project: plan the steps, pick the method that matches your downtime window, and verify the result. -Not upgrading your database can have the following risks: +## Benefits of upgrading to Percona Server for MySQL 8.4 -| Risks | Description | -| --- | --- | -| Security risks | Your database server is vulnerable to cyberattacks because you do not receive security fixes. These attacks can result in data breaches, data loss, and data corruption. These actions can harm the organization's reputation and lose money. | -| Service risks | You do not benefit from new or improved features. This risk may cause poor user experience, reduced productivity, and increased downtime. | -| Support risks | You are limited in support access. This risk can result in longer resolution times, unresolved issues, and higher support costs. | -| Compatibility risks | You can experience compatibility issues with hardware, operating systems, or applications since the older version is not supported on newer platforms. At some point, the database server is no longer supportable. | -| Failure risk | A failure in either hardware, operating system, or application may force an upgrade at the wrong time. | +| Benefit | What it means for you | +|-----------------------|----------------------------------------------------------------------------------------| +| Security fixes | Patches close known vulnerabilities, keeping your data safe from attacks. | +| New or enhanced features | Access to functionality that improves performance, reliability, and overall capability. | +| Less manual effort | Automation tools let you handle routine tasks without hands-on intervention. | +| Stay relevant | The latest version helps you meet evolving customer expectations and deliver solutions more quickly. | +| Lower operational cost | Improved efficiency, and scalability translate into cheaper day-to-day operations. | -[Concerned about upgrade risks? Percona Support can help mitigate potential issues.](https://www.percona.com/services/support) +## Risks of staying on an older version -Create a test environment to verify the upgrade before you upgrade the production servers. The test environment is crucial to the success of the upgrade. There is no supported [downgrade procedure](./downgrade.md). You can try to replicate from an {{vers}} version to an 8.0 version or restore a backup. -Tools, such as the [`pt-upgrade` tool](https://docs.percona.com/percona-toolkit/pt-upgrade.html) in the [Percona Toolkit](https://docs.percona.com/percona-toolkit/), can help with the upgrade process. +| Risk | Potential impact | +|--------------------------|----------------------------------------------------------------------------------------------------------------------------------| +| Security exposure | Without the latest patches, attackers can breach, corrupt, or destroy data, harming reputation and causing financial loss. | +| Feature stagnation | Missing new capabilities can lead to slower performance, lower productivity, and more frequent outages. | +| Reduced support | Older versions receive less vendor assistance, resulting in longer troubleshooting times and higher support expenses. | +| Compatibility problems | New hardware, operating system releases, or third-party applications may not work with an outdated Percona Server version, eventually leaving the server unsupported. | +| Unplanned upgrade pressure | Unexpected hardware or OS failures can force a rushed upgrade, increasing the chance of errors. | -We recommend upgrading to the latest version. +[Concerned about these risks? +Percona Support can help assess and mitigate them.](https://www.percona.com/services/support) -[Need personalized support during your upgrade? Contact Percona Support.](https://www.percona.com/services/support) -Review the documentation for other changes between 8.0 to {{vers}}. +## Upgrade workflow -Review [Upgrade Strategies](./upgrade-strategies.md) for an overview of the major strategies. +Follow this step-by-step workflow to plan and execute your upgrade from 8.0 to {{vers}}: + +### Step 1: Understand what's changing + +Review these documents to understand breaking changes, removed features, and compatibility issues: + +* [Breaking and incompatible changes in {{vers}}](./8.4-breaking-changes.md) - Review behavioral changes, removed features, and removed variables that may affect your applications + +* [Compatibility and removed items in {{vers}}](./8.4-compatibility-and-removed-items.md) - Verify third-party tool compatibility + +* [Defaults and tuning guidance for {{vers}}](./8.4-defaults-and-tuning.md) - Understand configuration changes that may impact performance + +* [Percona Toolkit updates for {{vers}}](./percona-toolkit-8.4-updates.md) - Review toolkit changes if you use Percona Toolkit + +### Step 2: Complete pre-upgrade preparation + +Work through the pre-upgrade checks in the [upgrade checklist](./upgrade-checklist-8.4.md). This includes: + +* Verifying authentication methods and client compatibility + +* Updating replication scripts (MASTER/SLAVE → SOURCE/REPLICA syntax) + +* Identifying and addressing removed features or variables + +* Reviewing configuration defaults + +* Testing backups and restore procedures + +* Planning plugin-to-component transitions (if applicable) + +### Step 3: Choose your upgrade strategy + +Select the upgrade method that best fits your environment: + +* [Upgrade strategies](./upgrade-strategies.md) - Overview of in-place, logical dump/restore, and side-by-side methods + +* [MySQL upgrade paths and supported methods](./mysql-upgrade-paths.md) - Verify your upgrade path is supported + +### Step 4: Execute the upgrade + +Follow the step-by-step procedures for your chosen method: + +* [Upgrade procedures for {{vers}}](./upgrade-procedures.md) - Detailed procedures for repository-based or standalone package upgrades + +### Step 5: Validate the upgrade + +After completing the upgrade, complete the post-upgrade validation steps in the [upgrade checklist](./upgrade-checklist-8.4.md#post-upgrade-validation). These steps include: + +* Verifying connectivity and authentication + +* Checking replication health (if applicable) + +* Re-creating spatial indexes + +* Validating performance baselines + +* Reviewing logs and metrics + +* Testing backup and recovery + +### Additional reference materials + +* [Upgrade from plugins to components](./upgrade-components.md) - Guide for migrating from plugins to components + +* [Downgrade options](./downgrade.md) - Information about downgrading if needed + +### Tooling to de-risk your upgrade + +* [`pt-upgrade`](https://docs.percona.com/percona-toolkit/pt-upgrade.html) – compares query plans and execution behavior between Percona Server 8.0 and {{vers}} + +* [Percona XtraBackup](https://www.percona.com/software/mysql-database/percona-xtrabackup) – creates hot backups and lets you test restores without downtime. + +* A full dry-run workflow - backup → restore on 8.4 → run smoke/load tests → validate → practice rollback. + +These purpose‑built tools let you spot regressions early and ensure a reliable fallback plan. + +## Test environment is mandatory + +Set up a sandbox and run the upgrade there first. This isolated environment is essential for a successful migration. If you ever need to revert to the previous version, note that there is no fully supported in-place [downgrade procedure](./downgrade.md) from Percona Server for MySQL 8.4 to an earlier major version. The most reliable rollback method is to restore a backup taken before the upgrade, or to use a logical dump/load or replication into the older version. Because binary compatibility may not be preserved when new features or data-format changes have been applied, the safest approach is to provision a fresh instance of the older version and reload your data, rather than expecting a simple “undo” of the upgrade. + +We strongly advise upgrading to the latest LTS release (Percona Server for MySQL {{vers}}) to stay secure, performant, and fully supported. + + +[Need personalized support during your upgrade? Contact Percona Support for a detailed migration plan.](https://www.percona.com/services/support) + +## Further reading + +Review these upgrade-related documents: + +* [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) + +* [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) + +* [Defaults and tuning guidance for {{vers}}](./8.4-defaults-and-tuning.md) + +* [Percona Toolkit updates for {{vers}}](./percona-toolkit-8.4-updates.md) + +### Additional MySQL documentation The following list summarizes a number of the changes in the 8.0 series and has useful guides that can help you perform a smooth upgrade. We strongly recommend reading this information: diff --git a/docs/write-filter-definitions.md b/docs/write-filter-definitions.md index b11280c99cb..e2a916deecc 100644 --- a/docs/write-filter-definitions.md +++ b/docs/write-filter-definitions.md @@ -24,10 +24,10 @@ When you’re setting up audit log filters in Percona Server for MySQL, you use | Benefit | Description | |---|---| | Reduced Log Volume and Storage | By defining specific rules for what events to log (inclusive filters), you significantly reduce the amount of data written to the audit log. This minimizes log file size, reduces storage requirements, and lowers maintenance overhead. | -| Improved Performance | Smaller log files lead to faster log rotations and less disk I/O, which can improve overall server performance. Reduced log volume also decreases the impact of auditing on the database server itself. | -| Enhanced Security Focus | Instead of logging every single event (which can be overwhelming), you can focus on the most critical events. For example, you can prioritize logging events related to:
- Sensitive data access: Log queries that access or modify critical tables.
- User account activity: Monitor user logins, password changes, and privilege grants.
- DML operations: Log INSERT, UPDATE, and DELETE statements on specific tables.
- DDL operations: Log schema changes like CREATE TABLE, ALTER TABLE, and DROP TABLE. | +| Improved Performance | Smaller log files lead to faster log rotations and less disk I/O, which can improve overall server performance. Reducing log volume also decreases the impact of auditing on the database server itself. | +| Enhanced Security Focus | Instead of logging every single event (which can be overwhelming), you can focus on the most critical events. For example, you can prioritize logging events related to:
* Sensitive data access: Log queries that access or modify critical tables.
* User account activity: Monitor user logins, password changes, and privilege grants.
* DML operations: Log INSERT, UPDATE, and DELETE statements on specific tables.
* DDL operations: Log schema changes like CREATE TABLE, ALTER TABLE, and DROP TABLE. | | Simplified Log Analysis | By filtering out irrelevant events, you make it easier to analyze and investigate security incidents or performance issues. You can quickly identify and focus on the most important events in the audit log. | -| Compliance | Many compliance regulations (e.g., PCI DSS, HIPAA) require organizations to audit database activity. Well-defined audit log filters help you meet these compliance requirements by ensuring that the necessary events are being logged. | +| Compliance | Many compliance regulations (for example, PCI DSS, HIPAA) require organizations to audit database activity. Well-defined audit log filters help you meet these compliance requirements by ensuring that the necessary events are being logged. | | Resource Optimization | By minimizing log volume and optimizing the auditing process, you can conserve valuable system resources, such as CPU, memory, and disk space. | ## Basic structure @@ -259,7 +259,7 @@ It’s important to consider the performance impact of logging and how it might #### Inclusive filter example -This filter is useful for monitoring and auditing changes to the database performed by administrative users, particularly to ensure that updates and deletions are tracked. +This filter is useful for monitoring and auditing database changes made by administrative users, particularly to ensure that updates and deletions are tracked. ```json { @@ -267,8 +267,10 @@ This filter is useful for monitoring and auditing changes to the database perfor "class": [ { "name": "table_access", - "user": ["admin"], - "operation": ["update", "delete"] + "event": [ + { "name": "update"}, + { "name": "delete"} + ] } ] } @@ -279,11 +281,11 @@ This filter does one thing: log all update and delete operations performed by ad * "class": The top-level key specifies that the filter applies to the `table_access` class. This class monitors events related to database table interactions. -* "name": "table_access": This defines the event class you want to track. This class captures interactions with database tables such as read, insert, update, and delete operations. Specifies the specific class of events +* "name": "table_access": This defines the event class you want to track. This class captures interactions with database tables, such as read, insert, update, and delete modifications. Specifies the specific class of events -* user: ["admin"]: This specifies that the filter applies only to events performed by the admin user. It restricts the filter to only log actions executed by this user. +* user: ["admin"]: This specifies that the filter applies only to events performed by the admin user and restricts the filter to only log actions executed by this user. -* operation: ["update", "delete"]: This narrows down the filter to track only specific operations. In this case, it captures update and delete operations. Any SELECT (read) or INSERT operations on tables will not be logged, as they are excluded by this filter. +* event: ["update", "delete"]: This narrows down the filter to track only specific actions. In this case, the filter captures update and delete modifications. Any SELECT (read) or INSERT modifications on tables will not be logged, as they are excluded by this filter. Inclusive filters give you granular control over your MySQL audit logging, allowing you to capture exactly the information you need without overwhelming your logging system. @@ -291,7 +293,7 @@ Inclusive filters give you granular control over your MySQL audit logging, allow Exclusive filters in the audit_log_filter for Percona Server for MySQL let you exclude certain activities from being logged, helping you reduce log size and focus on what matters most. For example, you can filter out routine operations like health checks or background processes to avoid unnecessary clutter in your logs. -This example defines a filter that `excludes` (negate: true) all table access events ("table_access") by the user "readonly_user". Events for other users or other classes of activity are still be logged unless additional filters are defined. +This example defines a filter that `excludes` (negate: true) all table access events ("table_access") by the user "readonly_user". Events for other users or other classes of activity are still being logged unless additional filters are defined. ```json { @@ -317,54 +319,62 @@ This example defines a filter that `excludes` (negate: true) all table access ev "name": "table_access", "user": ["admin", "developer"], "database": ["financial"], - "operation": ["update", "delete"], - "status": [1] // Failed operations only + "event": [ + {"name":"update"}, + {"name":"delete"} + ], + "status": [1] }, { "name": "connection", "user": ["external_service"], - "status": [0] // Successful connections + "status": [0] } ] } } ``` -This filter captures failed update/delete operations by admin and developer users in the financial database and successful connections for the `external_service` user +This filter captures failed update/delete modifications by admin and developer users in the financial database and successful connections for the `external_service` user ## Best practices -Following a systematic approach helps ensure successful deployment and maintenance when implementing audit log filters. Start by creating broad, inclusive filters that capture a wide range of events, giving you a comprehensive view of your database activity. For example, you might begin by logging all actions from administrative users or all operations on critical databases. As you analyze the captured data, you can refine these filters to focus on specific events, users, or operations that matter most to your organization. +Following a systematic approach helps ensure successful deployment and maintenance when implementing audit log filters. Start by creating broad, inclusive filters that capture a wide range of events, giving you a comprehensive view of your database activity. For example, you might begin by logging all actions from administrative users or all changes on critical databases. As you analyze the captured data, you can refine these filters to focus on specific events, users, or changes that matter most to your organization. Testing is crucial before deploying filters in production. Set up a non-production environment that mirrors your production setup as closely as possible. This non-production environment allows you to verify that your filters capture the intended events without missing critical information. During testing, pay particular attention to how different filter combinations interact and ensure they don't create any unexpected gaps in your audit coverage. Log file management requires careful attention. Audit logs can grow rapidly, especially with detailed filtering configurations. Monitor your log file sizes regularly and implement appropriate rotation policies. Consider storage capacity, retention requirements, and system performance when determining how much detail to include in your logs. It's often helpful to calculate expected log growth based on your typical database activity and adjust your rotation policies accordingly. -Performance impact is a critical consideration when implementing detailed logging. More granular filters typically require more system resources to process and store the audit data. Monitor your system's performance metrics while testing different filter configurations. Look for significant changes in query response times, CPU usage, or I/O operations. If you notice performance degradation, consider adjusting your filters to balance capturing necessary audit data and maintaining acceptable system performance. Remember that starting with less detailed logging is often better and gradually increasing it as needed rather than implementing overly aggressive logging that impacts system performance. +Performance impact is a critical consideration when implementing detailed logging. More granular filters typically require more system resources to process and store the audit data. Monitor your system's performance metrics while testing different filter configurations. Look for significant changes in query response times, CPU usage, or I/O operations. If you notice performance degradation, consider adjusting your filters to balance capturing necessary audit data and maintaining acceptable system performance. Remember that starting with less detailed logging is often better and gradually increasing it as needed, rather than implementing overly aggressive logging that impacts system performance. ## Implement the filter -Here's how to define and implement an audit log filter: +Here's how to define and implement an audit log filter in Percona Server for MySQL 8.4.6: -### Add filter identifier +### Create a filter -An audit log filter identifier is your filter's unique name within the `audit_log_filter` system. You create this name to label and track your specific filter setup. The `audit_log_filter_id` system variable stores this name, and you should choose descriptive identifiers like 'finance_audit' or 'security_tracking'. +To create an audit log filter, use the `audit_log_filter_set_filter()` function. This function takes two parameters: the filter name and the filter definition as a JSON string. -After you name your filter with an identifier, you attach your rules. The identifier makes it easy to manage multiple filter setups and update them as needed. When you want to change your logging rules, you first reference your chosen identifier and then add your new filter settings. - -Remember that when you apply new filter settings to an existing identifier, the system replaces the old settings. It doesn't add the new rules to what's already there. +```sql +SELECT audit_log_filter_set_filter('log_all', '{ "filter": { "log": true } }'); +``` +### Assign filter to users +To assign a filter to specific users, use the `audit_log_filter_set_user()` function. This function takes three parameters: username, userhost, and filtername. ```sql -SET GLOBAL audit_log_filter_id = 'financial_tracking'; +SELECT audit_log_filter_set_user('%', '%', 'log_all'); ``` -### Add filter definition +### Example: Financial tracking filter + +Here's a complete example of creating and assigning a comprehensive financial tracking filter: ```sql -SET GLOBAL audit_log_filter = '{ +-- Create the filter +SELECT audit_log_filter_set_filter('financial_tracking', '{ "filter": { "class": [ { @@ -372,40 +382,55 @@ SET GLOBAL audit_log_filter = '{ "user": ["admin", "finance_team"], "database": ["financial_db"], "table": ["accounts", "transactions"], - "operation": ["insert", "update", "delete"], + "event": [ + {"name":"insert"}, + {"name":"update"}, + {"name":"delete"], + ], "status": [0, 1] }, { "name": "connection", "user": ["admin", "finance_team"], - "operation": ["connect", "disconnect"], + "event": [ + {"name":"connect"}, + {"name":"disconnect"} + ], "status": [0, 1] } ] } -}'; +}'); + +-- Assign the filter to all users +SELECT audit_log_filter_set_user('%', '%', 'financial_tracking'); ``` The filter monitors two main types of activities. First, it watches all changes to your accounts and transactions tables. This monitoring means that the filter logs when someone adds new data, changes existing information, or removes records. You get a complete picture of who's touching your financial data and what they do with it. -The filter doesn't just track successful operations—it monitors both successes and failures. This tracking gives you valuable information about attempted changes that didn't work out, which is helpful for troubleshooting and security monitoring. +The filter tracks both successes and failures. This tracking gives you valuable information about attempted changes that didn't work out, which is helpful for troubleshooting and security monitoring. Here's what gets logged: -* Every insert, update, and delete operation on your financial tables +* Every insert, update, and delete action on your financial tables * All connection attempts from your admin and finance teams, including when they log in and out -* Whether each operation succeeded (status 0) or failed (status 1) +* Whether each action has succeeded (status 0) or failed (status 1) The filter focuses only on activity in your `financial_db` database. This targeted approach makes it easier to find the information you need when you need it. Tracking all these elements gives you a comprehensive view of who's accessing your financial data, what changes they're making, and whether those changes are successful. This ability is beneficial for security monitoring and compliance requirements. -To verify your filter: +To verify your filter, you can check the audit tables: + ```sql -SHOW GLOBAL VARIABLES LIKE 'audit_log_filter'; +-- Check created filters +SELECT * FROM mysql.audit_log_filter; + +-- Check user assignments +SELECT * FROM mysql.audit_log_user; ``` -To check if events are being logged, you can examine your audit log file (default location is the data directory). +You can examine your audit log file (the default location is the data directory) to check if events are being logged. diff --git a/mkdocs-base.yml b/mkdocs-base.yml index 10a924abe4e..2836e9ed14c 100644 --- a/mkdocs-base.yml +++ b/mkdocs-base.yml @@ -56,7 +56,7 @@ theme: - navigation.indexes - content.tooltips - content.tabs.link - - content.action.edit +# - content.action.edit - content.action.view - content.code.copy - content.code.annotate @@ -81,7 +81,7 @@ markdown_extensions: toc: permalink: true title: On this page - toc_depth: 3 + toc_depth: 2 md_in_html: {} admonition: {} footnotes: {} @@ -274,10 +274,16 @@ nav: - docker-compose.md - Upgrade: - upgrade.md + - Understand what's changing: + - 8.4-breaking-changes.md + - 8.4-compatibility-and-removed-items.md + - 8.4-defaults-and-tuning.md + - percona-toolkit-8.4-updates.md + - upgrade-checklist-8.4.md - upgrade-strategies.md + - mysql-upgrade-paths.md + - upgrade-procedures.md - upgrade-components.md - - upgrade-percona-repos.md - - upgrade-standalone-packages.md - downgrade.md - Post-Installation: - binlogging-replication-improvements.md diff --git a/mkdocs.yml b/mkdocs.yml index 8e507af8945..d720b51c442 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -27,6 +27,4 @@ extra: name: This page could be improved data: 0 note: >- - Thank you for your feedback! Help us improve by using our - - feedback form. + Thanks for your feedback! Want to improve this page? Click Edit this page on GitHub above to submit a pull request.