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.

Percona Server relies on a keyring to safeguard the master keys that encrypt data at rest. A manifest file loads the keyring component, which reads a separate configuration file during initialization. Avoid --early-plugin-load and INSTALL COMPONENT: neither mechanism can load a keyring early enough in startup.

Why the manifest is the only supported load path

The keyring must be live before InnoDB opens an encrypted page, which rules out any mechanism that depends on a running SQL layer. A typical startup proceeds in this order:

1. mysqld parses startup configuration and reads the manifest file next to the binary.

2. The server loads components named in the manifest.

3. InnoDB initializes, replays the redo log, and opens tablespaces.

4. The SQL layer accepts connections.

The keyring must be ready between steps 1 and 3. Both alternative mechanisms miss that window:

• INSTALL COMPONENT runs as SQL, so the statement cannot execute until step 4. The registration lives in mysql.component, an InnoDB table the server reads only after InnoDB initializes — a circular dependency when the system tablespace is encrypted. Crash recovery also runs before SQL, so an encrypted redo log must be readable without any SQL layer.

• --early-plugin-load applies to legacy keyring plugins, not components. Plugins and components load through separate subsystems; the flag cannot locate component entry points. The manifest is the only early-load channel for components.

One practical consequence: a component registered through INSTALL COMPONENT on a running server disappears on the next restart, so InnoDB fails to unwrap tablespace keys without a manifest file on disk. A missing or malformed mysqld.my is therefore a startup failure for any instance with encrypted tablespaces.

Place a global manifest named mysqld.my in the server installation directory. For per-instance overrides, add a local manifest — also named mysqld.my — in the data directory.

To install a keyring component:

1. Write the manifest file in valid JSON.

2. Write the component’s configuration file in valid JSON.

The manifest names the component to load. Without a matching manifest file, the server quietly skips the component. On startup, the server reads the global manifest from the installation directory; the global manifest either holds the component entries directly or delegates to a local manifest in the data directory. When instances on the same host require different keyring components, place a local manifest in each data directory so every instance loads the correct component.

Warning

Run exactly one keyring per server instance. Percona Server does not support multiple keyring plugins, multiple keyring components, or any mix of plugin and component — such configurations risk 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
}