Skip to content
Percona Software for MySQL Documentation

Rate this page
☆ ☆ ☆ ☆ ☆
Thanks for your feedback
Thank you! The feedback has been submitted.

For help, click the link below to get free database assistance or contact our experts for personalized support.

Get help from Percona

Upgrade from plugins to components

Need help navigating plugin to component transitions? Percona Support can assist.

Percona Server for MySQL 8.4 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 8.4 if both a plugin and a component are available for that feature.

The following plugins have changed:

Plugin 8.0 information 8.4 changes Notes
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 a deprecated plugin added in 8.4.7-7 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 8.4.
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 8.4.
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.

Transition a plugin to a component

The operation to transition from a plugin to a component can be complicated. Always test the migration in a staging environment before applying the changes to the production servers. To ensure there is minimal interruption, the key preparation steps are the following:

  • Plan for downtime

  • Create a comprehensive testing strategy

  • Verify that the existing functionality transfers correctly

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 (INSTALL COMPONENT or manifest file, as applicable).

  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.

Transition timing

The timing of the transition depends on the specific plugin:

  • Transition before upgrade: For plugins that have both plugin and component versions available in 8.0 (for example, data_masking), transition to the component in 8.0 before upgrading to 8.4.

  • Transition after upgrade: For plugins that only exist as plugins in 8.0 but have component equivalents in 8.4 (for example, audit_log_filter, keyring_vault), you must upgrade to 8.4 first, then transition to the component. The general procedure for these cases is:

  • Test the plugin functionality in 8.0 to establish a baseline.

  • Stop the service and upgrade to 8.4.

  • Review and adjust configurations as needed (for example, convert keyring_vault_config system variable to JSON format for the component).

  • Start the new 8.4 server.

  • Transition to the component following the general procedure above.

  • Verify the component works correctly in 8.4.

Further reading

Component-specific documentation