Skip to content
Percona Software for MySQL Documentation

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].(https://www.percona.com/services/support)

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 removed This plugin has been removed entirely in 8.4. 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.

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.

  2. Stop the service

  3. Upgrade to 8.4

  4. Review and adjust the configurations, as needed

  5. Start the new 8.4

  6. Confirm the component in 8.4

Further reading

Component-specific documentation