Persisted_variables_cache Class Reference

#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_uset *	get_persisted_dynamic_variables ()
	Get persisted variables. More...
Persisted_variables_uset *	get_persisted_dynamic_parse_early_variables ()
	Get persisted parse-early variables. More...
Persisted_variables_uset *	get_persisted_dynamic_sensitive_variables (THD *thd)
	Get SENSITIVE persisted variables. More...
Persisted_variables_umap *	get_persisted_static_variables ()
	Get persisted static variables. More...
Persisted_variables_umap *	get_persisted_static_parse_early_variables ()
	Get persisted parse-early static variables. More...
Persisted_variables_umap *	get_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_cache *	get_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 String *	get_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_FILE *	m_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_cache *	m_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]	argc	Pointer to argc of original program
[in]	argv	Pointer to argv of original program
[out]	arg_separator_added	Whether 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]	argc	Pointer to argc of original program
[in]	argv	Pointer to argv of original program
[in]	arg_separator_added	This flag tells whether arg separator has already been added or not
[in]	plugin_options	This flag tells whether options are handled during plugin install. If set to true options are handled as part of
[in]	root	The 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

false	Success
true	Error

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]	dom	Pointer to the Json_dom object which is an internal representation of parsed json string
[in]	is_read_only	Bool 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

true	An error occurred
false	Success

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_key	Decrypted Key
[out]	file_key_length	Decrypted key length
[in]	generate	Generate key if missing

Returns

status of key extraction operation

Return values

true	Error
false	Success

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]	thd	Pointer to connection handler
[in]	system_var	Pointer to sys_var which is being SET
[in]	str	Pointer to String instance into which value is copied
[out]	is_null	Is 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]	argc	Pointer to argc of original program
[in]	argv	Pointer 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

true	An error occurred
false	Success

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]

flag

file open mode

Returns

Error state

Return values

true	An error occurred
false	Success

open_persist_file()

bool Persisted_variables_cache::open_persist_file ( int  flag )

private

Open persisted config file.

Parameters

[in]

flag

File open mode

Returns

Error state

Return values

true	An error occurred
false	Success

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

-1	or 1 Failure
0	Success

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]	thd	Pointer to connection handle.
[in]	name	Name of variable to remove, if NULL all variables are removed from config file.
[in]	if_exists	Bool 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_options	Flag 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_name	If not-null the name of variable to try and set from the persisted cache values
[in]	target_var_name_length	length of target_var_name

Returns

Error state

Return values

true	An error occurred
false	Success

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]	thd	Pointer to connection handler
[in]	setvar	Pointer 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:

{
      key_memory_persisted_variables_memroot, 512}

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

Initial value:

{
      key_memory_persisted_variables_memroot, 512}

---

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

• sql/persisted_variable.h
• sql/persisted_variable.cc