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

Use the keyring file component

The keyring_file component is part of the component-based MySQL infrastructure which extends the server capabilities.

Important

Percona Server for MySQL 8.4 does not support the keyring_file plugin.

See the MySQL documentation on the component installation and on the keyring_file component usage for more information.

Install a keyring component through a manifest file. During startup, the server reads the manifest. Each component reads a corresponding configuration file during initialization.

Do not load keyring components with either of the following methods:

Method Why it fails
--early-plugin-load option Loads plugins only, not components
INSTALL COMPONENT statement Registers components in the mysql.component table, which the server loads after InnoDB initialization

Components that InnoDB requires at startup must load earlier.

Create a global manifest file named mysqld.my in the installation directory. Optionally, create a local manifest file with the same name in a data directory.

To install a keyring component, complete the following steps:

  1. Write a manifest in valid JSON format

  2. Write a configuration file

A manifest file declares which component to load. The server skips any component whose manifest file does not exist. During startup, the server reads the global manifest file from the installation directory. The global manifest file either contains the required information or references a local manifest file in the data directory.

Use a local manifest file in each data directory when you run multiple server instances with different keyring components. Each instance then loads the correct keyring component.

Warning

Enable only one keyring plugin or keyring component per server instance. Percona Server does not support multiple or mixed keyring implementations. Unsupported configurations can cause data loss.

An example of a manifest and a configuration file is the following:

An example of ./bin/mysqld.my:

{
    "components": "file://component_keyring_file"
}

An example of /lib/plugin/component_keyring_file.cnf:

{
    "path": "/var/lib/mysql-keyring/keyring_file", "read_only": false
}

Verify the keyring component

After you start Percona Server for MySQL, confirm that the keyring component loaded and initialized. Query the performance_schema.keyring_component_status table:

SELECT * FROM performance_schema.keyring_component_status;

The query returns one row for each status key that the loaded component reports. The Component_status row indicates the result of initialization:

Component_status value Meaning Recovery
Active The component loaded and initialized successfully None
Disabled The component loaded but failed to initialize, typically due to a configuration error Review the server error log, correct the configuration file, then run ALTER INSTANCE RELOAD KEYRING

If a keyring component fails to load entirely, the server does not start. Check the server error log for diagnostic messages.

For the complete list of status keys that each component reports, see keyring_component_status Table in the MySQL Reference Manual.