MySQL 9.1.0
Source Code Documentation
Persisted_variables_cache Class Referencefinal

#include <persisted_variable.h>

Classes

struct  Key_info
 

Public Member Functions

 Persisted_variables_cache ()
 
int init (int *argc, char ***argv)
 Initialize class members. More...
 
bool set_variable (THD *thd, set_var *system_var)
 Update in-memory copy for every SET PERSIST statement. More...
 
bool flush_to_file ()
 Driver: Flush in-memory copy to persistent file. More...
 
bool write_persist_file_v2 (String &dest, bool &do_cleanup)
 Write v2 persistent file. More...
 
int read_persist_file ()
 Driver function: Read options from persistent file. More...
 
int read_persist_file_v1 (const Json_object *json_object)
 Read v1 persistent file. More...
 
int read_persist_file_v2 (const Json_object *json_object)
 Read v2 persistent file. More...
 
bool load_persist_file ()
 Search for persisted config file and if found read persistent options. More...
 
bool set_persisted_options (bool plugin_options, const char *target_var_name=nullptr, int target_var_name_length=0)
 set_persisted_options() will set the options read from persisted config file More...
 
bool reset_persisted_variables (THD *thd, const char *name, bool if_exists)
 Reset persisted options. More...
 
Persisted_variables_usetget_persisted_dynamic_variables ()
 Get persisted variables. More...
 
Persisted_variables_usetget_persisted_dynamic_parse_early_variables ()
 Get persisted parse-early variables. More...
 
Persisted_variables_usetget_persisted_dynamic_sensitive_variables (THD *thd)
 Get SENSITIVE persisted variables. More...
 
Persisted_variables_umapget_persisted_static_variables ()
 Get persisted static variables. More...
 
Persisted_variables_umapget_persisted_static_parse_early_variables ()
 Get persisted parse-early static variables. More...
 
Persisted_variables_umapget_persisted_static_sensitive_variables (THD *thd)
 Get SENSITIVE persisted static variables. More...
 
bool append_read_only_variables (int *argc, char ***argv, bool arg_separator_added=false, bool plugin_options=false, MEM_ROOT *root_to_use=nullptr)
 append read only persisted variables to command line options with a separator. More...
 
bool append_parse_early_variables (int *argc, char ***argv, bool &arg_separator_added)
 append PARSE EARLY read only persisted variables to command line options with a separator. More...
 
void cleanup ()
 
void lock ()
 Acquire lock on m_persisted_dynamic_variables/m_persisted_static_variables. More...
 
void unlock ()
 Release lock on m_persisted_dynamic_variables/m_persisted_static_variables. More...
 
void assert_lock_owner ()
 Assert caller that owns lock on m_persisted_dynamic_variables/m_persisted_static_variables. More...
 
void keyring_support_available ()
 Set internal state to reflect keyring support status. More...
 
std::string to_hex (const std::string &value)
 
std::string from_hex (const std::string &value)
 

Static Public Member Functions

static Persisted_variables_cacheget_instance ()
 Return a singleton object. More...
 

Protected Types

enum class  File_version { VERSION_V1 = 1 , VERSION_V2 }
 

Private Types

enum class  return_status { NOT_REQUIRED , SUCCESS , ERROR }
 

Private Member Functions

bool extract_variables_from_json (const Json_dom *dom, bool is_read_only=false)
 extract_variables_from_json() is used to extract all the variable information which is in the form of Json_object. More...
 
void load_aliases ()
 After extracting the variables from the JSON, we duplicate any variable definition that relates to an alias. More...
 
bool get_file_encryption_key (std::unique_ptr< unsigned char[]> &file_key, size_t &file_key_length, bool generate=false)
 Get file encryption key. More...
 
return_status encrypt_sensitive_variables ()
 Encrypt sensitive variables values. More...
 
return_status decrypt_sensitive_variables ()
 Decrypt sensitive variables values. More...
 
void set_parse_early_sources ()
 Helper to set source information for PARSE_EARLY variables. More...
 
void handle_option_type_change ()
 Helper function to handle changes in option type. More...
 
void clear_sensitive_blob_and_iv ()
 
bool open_persist_file (int flag)
 Open persisted config file. More...
 
bool open_persist_backup_file (int flag)
 Open persisted backup config file. More...
 
void close_persist_file ()
 Close persisted config file. More...
 

Static Private Member Functions

static Stringget_variable_value (THD *thd, sys_var *system_var, String *str, bool *is_null)
 Retrieve variables value from sys_var. More...
 
static const char * get_variable_alias (const sys_var *system_var)
 If the variable has an alias, return the name for the alias. More...
 
static std::string get_variable_alias (const char *name)
 

Private Attributes

Persisted_variables_umap m_persisted_static_sensitive_variables
 
Persisted_variables_umap m_persisted_static_parse_early_variables
 
Persisted_variables_umap m_persisted_static_variables
 
Persisted_variables_uset m_persisted_dynamic_parse_early_variables
 
Persisted_variables_uset m_persisted_dynamic_sensitive_variables
 
Persisted_variables_uset m_persisted_dynamic_variables
 
Persisted_variables_uset m_persisted_dynamic_sensitive_plugin_variables
 
Persisted_variables_uset m_persisted_dynamic_plugin_variables
 
Key_info m_key_info
 
bool m_keyring_support_available {false}
 
std::string m_sensitive_variables_blob {}
 
std::string m_iv {}
 
mysql_mutex_t m_LOCK_persist_variables
 
MYSQL_FILEm_fd
 
std::string m_persist_filename
 
std::string m_persist_backup_filename
 
mysql_mutex_t m_LOCK_persist_file
 
MEM_ROOT parse_early_persisted_argv_alloc
 
MEM_ROOT ro_persisted_argv_alloc {key_memory_persisted_variables_memroot, 512}
 
MEM_ROOT ro_persisted_plugin_argv_alloc
 
File_version m_default_version = File_version::VERSION_V2
 

Static Private Attributes

static Persisted_variables_cachem_instance = nullptr
 

Member Enumeration Documentation

◆ File_version

enum class Persisted_variables_cache::File_version
strongprotected
Enumerator
VERSION_V1 
VERSION_V2 

◆ return_status

enum class Persisted_variables_cache::return_status
strongprivate
Enumerator
NOT_REQUIRED 
SUCCESS 
ERROR 

Constructor & Destructor Documentation

◆ Persisted_variables_cache()

Persisted_variables_cache::Persisted_variables_cache ( )
explicit

Member Function Documentation

◆ append_parse_early_variables()

bool Persisted_variables_cache::append_parse_early_variables ( int *  argc,
char ***  argv,
bool &  arg_separator_added 
)

append PARSE EARLY read only persisted variables to command line options with a separator.

append_parse_early_variables() does a lookup into persist_variables for parse early variables and place them after the command line options with a separator "----persist-args-separator----"

This function does nothing when –no-defaults is set or if persisted_globals_load is disabled.

Parameters
[in]argcPointer to argc of original program
[in]argvPointer to argv of original program
[out]arg_separator_addedWhether the separator is added or not
Returns
0 Success
1 Failure

◆ append_read_only_variables()

bool Persisted_variables_cache::append_read_only_variables ( int *  argc,
char ***  argv,
bool  arg_separator_added = false,
bool  plugin_options = false,
MEM_ROOT root = nullptr 
)

append read only persisted variables to command line options with a separator.

append_read_only_variables() does a lookup into persist_variables for read only variables and place them after the command line options with a separator "----persist-args-separator----"

This function does nothing when –no-defaults is set or if persisted_globals_load is disabled.

Parameters
[in]argcPointer to argc of original program
[in]argvPointer to argv of original program
[in]arg_separator_addedThis flag tells whether arg separator has already been added or not
[in]plugin_optionsThis flag tells whether options are handled during plugin install. If set to true options are handled as part of
[in]rootThe memory root to use for the allocations. Null if you want to use the PV cache root(s). install plugin.
Returns
0 Success
1 Failure

◆ assert_lock_owner()

void Persisted_variables_cache::assert_lock_owner ( )
inline

Assert caller that owns lock on m_persisted_dynamic_variables/m_persisted_static_variables.

◆ cleanup()

void Persisted_variables_cache::cleanup ( )

◆ clear_sensitive_blob_and_iv()

void Persisted_variables_cache::clear_sensitive_blob_and_iv ( )
private

◆ close_persist_file()

void Persisted_variables_cache::close_persist_file ( )
private

Close persisted config file.

◆ decrypt_sensitive_variables()

Persisted_variables_cache::return_status Persisted_variables_cache::decrypt_sensitive_variables ( )
private

Decrypt sensitive variables values.

Returns
Status of the operation
Return values
falseSuccess
trueError

◆ encrypt_sensitive_variables()

Persisted_variables_cache::return_status Persisted_variables_cache::encrypt_sensitive_variables ( )
private

Encrypt sensitive variables values.

Returns
Status of the operation

◆ extract_variables_from_json()

bool Persisted_variables_cache::extract_variables_from_json ( const Json_dom dom,
bool  is_read_only = false 
)
private

extract_variables_from_json() is used to extract all the variable information which is in the form of Json_object.

New format for mysqld-auto.cnf is as below: { "mysql_static_parse_early_variables": { "variable_name_1" : { "Value" : "variable_value", "Metadata" : { "Timestamp" : timestamp_value, "User" : "user_name", "Host" : "host_name" } }, "variable_name_2" : { "Value" : "variable_value", "Metadata" : { "Timestamp" : timestamp_value, "User" : "user_name", "Host" : "host_name" } }, ... ... "variable_name_n" : { "Value" : "variable_value", "Metadata" : { "Timestamp" : timestamp_value, "User" : "user_name", "Host" : "host_name" } } }, "mysql_dynamic_parse_early_variables": { "variable_name_1" : { "Value" : "variable_value", "Metadata" : { "Timestamp" : timestamp_value, "User" : "user_name", "Host" : "host_name" } }, "variable_name_2" : { "Value" : "variable_value", "Metadata" : { "Timestamp" : timestamp_value, "User" : "user_name", "Host" : "host_name" } }, ... ... "variable_name_n" : { "Value" : "variable_value", "Metadata" : { "Timestamp" : timestamp_value, "User" : "user_name", "Host" : "host_name" } } }, "mysql_static_variables": { "variable_name_1" : { "Value" : "variable_value", "Metadata" : { "Timestamp" : timestamp_value, "User" : "user_name", "Host" : "host_name" } }, "variable_name_2" : { "Value" : "variable_value", "Metadata" : { "Timestamp" : timestamp_value, "User" : "user_name", "Host" : "host_name" } }, ... ... "variable_name_n" : { "Value" : "variable_value", "Metadata" : { "Timestamp" : timestamp_value, "User" : "user_name", "Host" : "host_name" } } }, "mysql_dynamic_variables": { "variable_name_1" : { "Value" : "variable_value", "Metadata" : { "Timestamp" : timestamp_value, "User" : "user_name", "Host" : "host_name" } }, "variable_name_2" : { "Value" : "variable_value", "Metadata" : { "Timestamp" : timestamp_value, "User" : "user_name", "Host" : "host_name" } }, ... ... "variable_name_n" : { "Value" : "variable_value", "Metadata" : { "Timestamp" : timestamp_value, "User" : "user_name", "Host" : "host_name" } } }, "mysql_sensitive_variables" : { "master_key": "<master_key_name>", "mysql_file_key": "<ENCRYPTED_FILE_KEY_IN_HEX>", "mysql_file_key_iv": "<IV_IN_HEX>", "key_encryption_algorithm": "AES_256_CBC", "mysql_sensitive_variables_blob": "<SENSITIVE_VARIABLES_INFO_IN_ENCRYPTED_FORM_IN_HEX>", "mysql_sensitive_variables_iv": "<IV_IN_HEX>", "data_encryption_algorithm": "AES_256_CBC" } }

Parameters
[in]domPointer to the Json_dom object which is an internal representation of parsed json string
[in]is_read_onlyBool value when set to TRUE extracts read only variables and dynamic variables when set to FALSE.
Returns
0 Success
1 Failure

Static variables by themselves is represented as a json object with key "mysql_server_static_options" as parent element.

Every Json object which represents Variable information must have only 2 elements which is { "Value" : "variable_value", – 1st element "Metadata" : { – 2nd element "Timestamp" : timestamp_value, "User" : "user_name", "Host" : "host_name" } }

If we are reading from a v1 persisted file, all static options including PARSE_EARLY options are stored in array "mysql_server_static_options". Since there is no way to identify PARSE_EARLY static variables, we push all these variables to m_persisted_static_parse_early_variables.

◆ flush_to_file()

bool Persisted_variables_cache::flush_to_file ( )

Driver: Flush in-memory copy to persistent file.

Convert in-memory copy into a stream of characters and write this stream to persisted config file.

Returns
Error state
Return values
trueAn error occurred
falseSuccess

◆ from_hex()

std::string Persisted_variables_cache::from_hex ( const std::string &  value)

◆ get_file_encryption_key()

bool Persisted_variables_cache::get_file_encryption_key ( std::unique_ptr< unsigned char[]> &  file_key,
size_t &  file_key_length,
bool  generate = false 
)
private

Get file encryption key.

Use master key from keyring to decrypt it

Parameters
[out]file_keyDecrypted Key
[out]file_key_lengthDecrypted key length
[in]generateGenerate key if missing
Returns
status of key extraction operation
Return values
trueError
falseSuccess

◆ get_instance()

Persisted_variables_cache * Persisted_variables_cache::get_instance ( )
static

Return a singleton object.

◆ get_persisted_dynamic_parse_early_variables()

Persisted_variables_uset * Persisted_variables_cache::get_persisted_dynamic_parse_early_variables ( )

Get persisted parse-early variables.

Get PARSE_EARLY persisted variables.

◆ get_persisted_dynamic_sensitive_variables()

Persisted_variables_uset * Persisted_variables_cache::get_persisted_dynamic_sensitive_variables ( THD thd)

Get SENSITIVE persisted variables.

◆ get_persisted_dynamic_variables()

Persisted_variables_uset * Persisted_variables_cache::get_persisted_dynamic_variables ( )

Get persisted variables.

Return in-memory copy persist_variables_.

◆ get_persisted_static_parse_early_variables()

Persisted_variables_umap * Persisted_variables_cache::get_persisted_static_parse_early_variables ( )

Get persisted parse-early static variables.

◆ get_persisted_static_sensitive_variables()

Persisted_variables_umap * Persisted_variables_cache::get_persisted_static_sensitive_variables ( THD thd)

Get SENSITIVE persisted static variables.

◆ get_persisted_static_variables()

Persisted_variables_umap * Persisted_variables_cache::get_persisted_static_variables ( )

Get persisted static variables.

Return in-memory copy for static persisted variables.

◆ get_variable_alias() [1/2]

std::string Persisted_variables_cache::get_variable_alias ( const char *  name)
staticprivate

◆ get_variable_alias() [2/2]

const char * Persisted_variables_cache::get_variable_alias ( const sys_var system_var)
staticprivate

If the variable has an alias, return the name for the alias.

◆ get_variable_value()

String * Persisted_variables_cache::get_variable_value ( THD thd,
sys_var system_var,
String str,
bool *  is_null 
)
staticprivate

Retrieve variables value from sys_var.

Parameters
[in]thdPointer to connection handler
[in]system_varPointer to sys_var which is being SET
[in]strPointer to String instance into which value is copied
[out]is_nullIs value NULL or not.
Returns
Pointer to String instance holding the value

◆ handle_option_type_change()

void Persisted_variables_cache::handle_option_type_change ( )
private

Helper function to handle changes in option type.

Function to recategorize variables based on changes in their properties.

It is possible that during the course of development, we reclassify certain variables. Such an action may have an impact on when and how the persisted values of such variables are used/applied.

If such variables are persisted using previous versions of the server binary, it is important that we move them to correct in-memory containers so that,

  1. Variables will be handled as required during bootstrap
  2. Upon next change to persisted option file, variables will be placed into appropriate JSON arrays.

◆ init()

int Persisted_variables_cache::init ( int *  argc,
char ***  argv 
)

Initialize class members.

This function reads datadir if present in config file or set at command line, in order to know from where to load this config file. If datadir is not set then read from MYSQL_DATADIR.

Parameters
[in]argcPointer to argc of original program
[in]argvPointer to argv of original program
Returns
0 Success
1 Failure

◆ keyring_support_available()

void Persisted_variables_cache::keyring_support_available ( )

Set internal state to reflect keyring support status.

We cache keyring support status just after reading manifest file.

This is required because in the absence of a keyring component, keyring plugin may provide some of the services through daemon proxy keyring.

However, we CANNOT use keyring plugin to encrypt SENSITIVE variables because upon server restart, keyring plugins will be loaded quite late.

Later on, before each encryption operation, we refer to this cached value to decide whether to proceed with encryption or not.

◆ load_aliases()

void Persisted_variables_cache::load_aliases ( )
private

After extracting the variables from the JSON, we duplicate any variable definition that relates to an alias.

◆ load_persist_file()

bool Persisted_variables_cache::load_persist_file ( )

Search for persisted config file and if found read persistent options.

load_persist_file() read persisted config file

Returns
Error state
Return values
trueAn error occurred
falseSuccess

◆ lock()

void Persisted_variables_cache::lock ( )
inline

Acquire lock on m_persisted_dynamic_variables/m_persisted_static_variables.

◆ open_persist_backup_file()

bool Persisted_variables_cache::open_persist_backup_file ( int  flag)
private

Open persisted backup config file.

Parameters
[in]flagfile open mode
Returns
Error state
Return values
trueAn error occurred
falseSuccess

◆ open_persist_file()

bool Persisted_variables_cache::open_persist_file ( int  flag)
private

Open persisted config file.

Parameters
[in]flagFile open mode
Returns
Error state
Return values
trueAn error occurred
falseSuccess

◆ read_persist_file()

int Persisted_variables_cache::read_persist_file ( )

Driver function: Read options from persistent file.

read_persist_file() reads the persisted config file

This function does following:

  1. Read the persisted config file into a string buffer
  2. This string buffer is parsed with JSON parser to check if the format is correct or not.
  3. Check for correct group name.
  4. Extract key/value pair and populate in m_persisted_dynamic_variables, m_persisted_static_variables. mysqld-auto.cnf file will have variable properties like when a variable is set, by wholm and on what host this variable was set.
Returns
Error state
Return values
-1or 1 Failure
0Success

◆ read_persist_file_v1()

int Persisted_variables_cache::read_persist_file_v1 ( const Json_object json_object)

Read v1 persistent file.

◆ read_persist_file_v2()

int Persisted_variables_cache::read_persist_file_v2 ( const Json_object json_object)

Read v2 persistent file.

◆ reset_persisted_variables()

bool Persisted_variables_cache::reset_persisted_variables ( THD thd,
const char *  name,
bool  if_exists 
)

Reset persisted options.

reset_persisted_variables() does a lookup into persist_variables and remove the variable from the hash if present and flush the hash to file.

Parameters
[in]thdPointer to connection handle.
[in]nameName of variable to remove, if NULL all variables are removed from config file.
[in]if_existsBool value when set to true reports warning else error if variable is not present in the config file.
Returns
0 Success
1 Failure

◆ set_parse_early_sources()

void Persisted_variables_cache::set_parse_early_sources ( )
private

Helper to set source information for PARSE_EARLY variables.

◆ set_persisted_options()

bool Persisted_variables_cache::set_persisted_options ( bool  plugin_options,
const char *  target_var_name = nullptr,
int  target_var_name_length = 0 
)

set_persisted_options() will set the options read from persisted config file

This function does nothing when –no-defaults is set or if persisted_globals_load is set to false. Initial call to set_persisted_options(false) is needed to initialize m_persisted_dynamic_plugin_variables set, so that next subsequent set_persisted_options(true) calls will work with correct state.

Parameters
[in]plugin_optionsFlag which tells what options are being set. If set to false non dynamically-registered system variables are set else plugin- and component-registered variables are set.
[in]target_var_nameIf not-null the name of variable to try and set from the persisted cache values
[in]target_var_name_lengthlength of target_var_name
Returns
Error state
Return values
trueAn error occurred
falseSuccess

◆ set_variable()

bool Persisted_variables_cache::set_variable ( THD thd,
set_var setvar 
)

Update in-memory copy for every SET PERSIST statement.

Retrieve variables name/value and update the in-memory copy with this new values.

If value is default then remove this entry from in-memory copy, else update existing key with new value

Parameters
[in]thdPointer to connection handler
[in]setvarPointer to set_var which is being SET
Returns
true Failure
false Success

If server was upgraded, it is possible that persisted variables were initially read from an old format file. If so, all RO variables: PARSE_EARLY or otherwise, persisted before the upgrade may be present in m_persisted_static_parse_early_variables container.

This SET PERSIST/SET PERSIST_ONLY call may be setting one of those variables. If so, remove those values from m_persisted_static_parse_early_variables.

◆ to_hex()

std::string Persisted_variables_cache::to_hex ( const std::string &  value)

◆ unlock()

void Persisted_variables_cache::unlock ( )
inline

Release lock on m_persisted_dynamic_variables/m_persisted_static_variables.

◆ write_persist_file_v2()

bool Persisted_variables_cache::write_persist_file_v2 ( String dest,
bool &  do_cleanup 
)

Write v2 persistent file.

If original file was of File_version::VERSION_V1, some of the variables which may belong to object "mysql_static_variables" could be part of "mysql_static_parse_early_variables" object. This is because we move such variables to "mysql_static_variables" only when SET PERSIST or SET PERSIST_ONLY is executed for them.

Member Data Documentation

◆ m_default_version

File_version Persisted_variables_cache::m_default_version = File_version::VERSION_V2
private

◆ m_fd

MYSQL_FILE* Persisted_variables_cache::m_fd
private

◆ m_instance

Persisted_variables_cache * Persisted_variables_cache::m_instance = nullptr
staticprivate

◆ m_iv

std::string Persisted_variables_cache::m_iv {}
private

◆ m_key_info

Key_info Persisted_variables_cache::m_key_info
private

◆ m_keyring_support_available

bool Persisted_variables_cache::m_keyring_support_available {false}
private

◆ m_LOCK_persist_file

mysql_mutex_t Persisted_variables_cache::m_LOCK_persist_file
private

◆ m_LOCK_persist_variables

mysql_mutex_t Persisted_variables_cache::m_LOCK_persist_variables
private

◆ m_persist_backup_filename

std::string Persisted_variables_cache::m_persist_backup_filename
private

◆ m_persist_filename

std::string Persisted_variables_cache::m_persist_filename
private

◆ m_persisted_dynamic_parse_early_variables

Persisted_variables_uset Persisted_variables_cache::m_persisted_dynamic_parse_early_variables
private

◆ m_persisted_dynamic_plugin_variables

Persisted_variables_uset Persisted_variables_cache::m_persisted_dynamic_plugin_variables
private

◆ m_persisted_dynamic_sensitive_plugin_variables

Persisted_variables_uset Persisted_variables_cache::m_persisted_dynamic_sensitive_plugin_variables
private

◆ m_persisted_dynamic_sensitive_variables

Persisted_variables_uset Persisted_variables_cache::m_persisted_dynamic_sensitive_variables
private

◆ m_persisted_dynamic_variables

Persisted_variables_uset Persisted_variables_cache::m_persisted_dynamic_variables
private

◆ m_persisted_static_parse_early_variables

Persisted_variables_umap Persisted_variables_cache::m_persisted_static_parse_early_variables
private

◆ m_persisted_static_sensitive_variables

Persisted_variables_umap Persisted_variables_cache::m_persisted_static_sensitive_variables
private

◆ m_persisted_static_variables

Persisted_variables_umap Persisted_variables_cache::m_persisted_static_variables
private

◆ m_sensitive_variables_blob

std::string Persisted_variables_cache::m_sensitive_variables_blob {}
private

◆ parse_early_persisted_argv_alloc

MEM_ROOT Persisted_variables_cache::parse_early_persisted_argv_alloc
private
Initial value:
{
PSI_memory_key key_memory_persisted_variables_memroot
Definition: psi_memory_key.cc:125

◆ ro_persisted_argv_alloc

MEM_ROOT Persisted_variables_cache::ro_persisted_argv_alloc {key_memory_persisted_variables_memroot, 512}
private

◆ ro_persisted_plugin_argv_alloc

MEM_ROOT Persisted_variables_cache::ro_persisted_plugin_argv_alloc
private

The documentation for this class was generated from the following files: