MySQL 8.4.3
Source Code Documentation
persisted_variable.h
Go to the documentation of this file.
1/* Copyright (c) 2016, 2024, Oracle and/or its affiliates.
2
3 This program is free software; you can redistribute it and/or modify
4 it under the terms of the GNU General Public License, version 2.0,
5 as published by the Free Software Foundation.
6
7 This program is designed to work with certain software (including
8 but not limited to OpenSSL) that is licensed under separate terms,
9 as designated in a particular file or component or in included license
10 documentation. The authors of MySQL hereby grant you an additional
11 permission to link the program and your derivative works with the
12 separately licensed software that they have either included with
13 the program or referenced in the documentation.
14
15 This program is distributed in the hope that it will be useful,
16 but WITHOUT ANY WARRANTY; without even the implied warranty of
17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 GNU General Public License, version 2.0, for more details.
19
20 You should have received a copy of the GNU General Public License
21 along with this program; if not, write to the Free Software
22 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */
23
24#ifndef PERSISTED_VARIABLE_H_INCLUDED
25#define PERSISTED_VARIABLE_H_INCLUDED
26
27#include <stddef.h>
28#include <map>
29#include <string>
30#include <unordered_set>
31
32#include "map_helpers.h"
33#include "my_alloc.h"
34#include "my_inttypes.h"
35#include "my_psi_config.h"
39#include "sql/psi_memory_key.h"
40#include "sql_string.h"
41
42class Json_dom;
43class Json_object;
44class THD;
45class set_var;
46class sys_var;
47struct MYSQL_FILE;
48
49/**
50 STRUCT st_persist_var
51
52 This structure represents information of a variable which is to
53 be persisted in mysql-auto.cnf file.
54*/
55struct st_persist_var final {
56 std::string key;
57 std::string value;
59 std::string user;
60 std::string host;
61 bool is_null;
63 st_persist_var(THD *thd);
64 st_persist_var(const std::string key, const std::string value,
65 const ulonglong timestamp, const std::string user,
66 const std::string host, const bool is_null);
67 /* This is custom comparison function used to make the unordered_set
68 work with the default std::hash for user defined types. */
69 bool operator==(const st_persist_var &persist_var) const {
70 return key == persist_var.key;
71 }
72};
73
74/**
75 STRUCT st_persist_var_hash
76
77 This structure has a custom hasher function used to make the unordered_set
78 to work with the default std::hash for user defined types.
79*/
81 size_t operator()(const st_persist_var &pv) const { return pv.key.length(); }
82};
83
84/**
85 CLASS Persisted_variables_cache
86 Holds <name,value> pair of all options which needs to be persisted
87 to a file.
88
89 OVERVIEW
90 --------
91 When first SET PERSIST statement is executed we instantiate
92 Persisted_variables_cache which loads the config file if present into
93 m_persisted_dynamic_variables set. This is a singleton operation.
94 m_persisted_dynamic_variables is an in-memory copy of config file itself. If
95 the SET statement passes then this in-memory is updated and flushed to file as
96 an atomic operation.
97
98 Next SET PERSIST statement would only update the in-memory copy and sync
99 to config file instead of loading the file again.
100*/
101
102#ifdef HAVE_PSI_INTERFACE
103void my_init_persist_psi_keys(void);
104#endif /* HAVE_PSI_INTERFACE */
105
110
112 protected:
113 enum class File_version {
114 VERSION_V1 = 1,
116 };
117
118 public:
119 explicit Persisted_variables_cache();
120 int init(int *argc, char ***argv);
122 /**
123 Update in-memory copy for every SET PERSIST statement
124 */
125 bool set_variable(THD *thd, set_var *system_var);
126 /**
127 Driver: Flush in-memory copy to persistent file
128 */
129 bool flush_to_file();
130 /**
131 Write v2 persistent file
132 */
133 bool write_persist_file_v2(String &dest, bool &do_cleanup);
134 /**
135 Driver function: Read options from persistent file
136 */
137 int read_persist_file();
138 /**
139 Read v1 persistent file
140 */
141 int read_persist_file_v1(const Json_object *json_object);
142 /**
143 Read v2 persistent file
144 */
145 int read_persist_file_v2(const Json_object *json_object);
146 /**
147 Search for persisted config file and if found read persistent options
148 */
149 bool load_persist_file();
150 bool set_persisted_options(bool plugin_options,
151 const char *target_var_name = nullptr,
152 int target_var_name_length = 0);
153 /**
154 Reset persisted options
155 */
156 bool reset_persisted_variables(THD *thd, const char *name, bool if_exists);
157
158 /**
159 Get persisted variables
160 */
162 /**
163 Get persisted parse-early variables
164 */
166 /**
167 Get SENSITIVE persisted variables
168 */
170
171 /**
172 Get persisted static variables
173 */
175 /**
176 Get persisted parse-early static variables
177 */
179 /**
180 Get SENSITIVE persisted static variables
181 */
183
184 /**
185 append read only persisted variables to command line options with a
186 separator.
187 */
188 bool append_read_only_variables(int *argc, char ***argv,
189 bool arg_separator_added = false,
190 bool plugin_options = false,
191 MEM_ROOT *root_to_use = nullptr);
192
193 /**
194 append PARSE EARLY read only persisted variables to command
195 line options with a separator.
196 */
197 bool append_parse_early_variables(int *argc, char ***argv,
198 bool &arg_separator_added);
199
200 void cleanup();
201
202 /**
203 Acquire lock on m_persisted_dynamic_variables/m_persisted_static_variables
204 */
206 /**
207 Release lock on m_persisted_dynamic_variables/m_persisted_static_variables
208 */
210 /**
211 Assert caller that owns lock on
212 m_persisted_dynamic_variables/m_persisted_static_variables
213 */
216 }
217 /**
218 Set internal state to reflect keyring support status
219 */
221
222 std::string to_hex(const std::string &value);
223 std::string from_hex(const std::string &value);
224
225 private:
226 /* Helper function to get variable value */
227 static String *get_variable_value(THD *thd, sys_var *system_var, String *str,
228 bool *is_null);
229 /**
230 If the variable has an alias, return the name for the alias.
231 */
232 static const char *get_variable_alias(const sys_var *system_var);
233 static std::string get_variable_alias(const char *name);
234 /* Helper function to extract variables from json formatted string */
236 bool is_read_only = false);
237 /**
238 After extracting the variables from the JSON, we duplicate any
239 variable definition that relates to an alias.
240 */
241 void load_aliases();
242
244 bool get_file_encryption_key(std::unique_ptr<unsigned char[]> &file_key,
245 size_t &file_key_length, bool generate = false);
248
249 /** Helper to set source information for PARSE_EARLY variables */
251
252 /** Helper function to handle changes in option type */
254
255 private:
256 /* Helper functions for file IO */
258 bool open_persist_file(int flag);
260 void close_persist_file();
261
262 private:
263 /*
264 There are two main types of variables:
265 1. Static variables: Those which cannot be set at runtime
266 2. Dynamic variables: Those which can be set on a running server
267
268 Each of these types is further divided in 3 sub-types:
269 A. PARSE_EARLY variables - This set of variables require to be set very
270 early in server start-up sequence
271 B. SENSITIVE variables - This set of variables may be stored in
272 encrypted format if a suitable keyring
273 component is available
274 C. All other variables - These are the variables that do not have
275 none of the mentioned properties
276
277 Two of the above mentioned sub-types exist because we treat
278 variables with certain properties in special manner for reasons mentioned
279 above for each of the In future, more categories may need special
280 treatment and if so, above mentioned sub-categories will increase.
281
282 These gives us total of 6 categories (3 each for static and dynamic
283 types of variables). Each of these categories of variables are processed
284 and/or loaded at different point of time in start-up sequence:
285
286 - 1A and 2A variables are added to command line argument at the very
287 beginning of the start-up
288 - 1B and 2B are decrypted once keyring component is loaded.
289 - 1B and 1C are added to command line
290 - 2B and 2C are set at a later point in start-up cycle when THD
291 initialization is possible. Some of the variables of types 2B and 2C
292 are not processed until corresponding component or plugin is loaded.
293 These subsets of variables are moved to special in-memory containers
294 reserved for them.
295
296 The persisted options file contains 6 JSON objects - one each for
297 above mentioned categories. When file is read, data from each JSON object
298 is loaded in different in-memory containers.
299 */
300
301 /* In memory copy of Persisted PARSE EARLY static variables' values */
303 /* In memory copy of Persisted SENSITIVE static variables' values */
305 /* In memory copy of all other Persisted static variables' values */
307
308 /* In memory copy of Persisted PARSE EARLY dynamic variables' values */
310 /* In memory copy of Persisted SENSITIVE dynamic variables' values */
312 /* In memory copy of all other Persisted dynamic variables' values */
314
315 /*
316 In memory copy of Persisted SENSITIVE dynamic
317 variables whose plugin is not yet installed
318 */
320 /*
321 In memory copy of all other Persisted dynamic
322 variables whose plugin is not yet installed
323 */
325
326 struct Key_info {
327 std::string m_master_key_name{"persisted_variables_key"};
328 std::string m_master_key_type{"AES"};
329 const size_t m_master_key_size{32};
330
331 std::string m_file_key{};
332 std::string m_file_key_iv{};
333 };
334
335 /* Key */
337
338 /* Status of keyring support */
340 /* Sensitive variables blob - HEX representation */
342 /* IV - HEX representation */
343 std::string m_iv{};
344
347
348 /* File handler members */
353 /* Memory for parse early read only persisted options */
356 /* Memory for read only persisted options */
358 /* Memory for read only persisted plugin options */
361
362 /* default version */
364};
365
366#endif /* PERSISTED_VARIABLE_H_INCLUDED */
JSON DOM abstract base class.
Definition: json_dom.h:173
Represents a JSON container value of type "object" (ECMA), type J_OBJECT here.
Definition: json_dom.h:369
Definition: persisted_variable.h:111
Key_info m_key_info
Definition: persisted_variable.h:336
bool m_keyring_support_available
Definition: persisted_variable.h:339
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.
Definition: persisted_variable.cc:2063
Persisted_variables_uset * get_persisted_dynamic_variables()
Get persisted variables.
Definition: persisted_variable.cc:2276
bool reset_persisted_variables(THD *thd, const char *name, bool if_exists)
Reset persisted options.
Definition: persisted_variable.cc:2152
void clear_sensitive_blob_and_iv()
Definition: persisted_variable.cc:2337
void unlock()
Release lock on m_persisted_dynamic_variables/m_persisted_static_variables.
Definition: persisted_variable.h:209
void load_aliases()
After extracting the variables from the JSON, we duplicate any variable definition that relates to an...
Definition: persisted_variable.cc:1747
int read_persist_file_v2(const Json_object *json_object)
Read v2 persistent file.
Definition: persisted_variable.cc:1641
void close_persist_file()
Close persisted config file.
Definition: persisted_variable.cc:875
Persisted_variables_uset m_persisted_dynamic_variables
Definition: persisted_variable.h:313
void set_parse_early_sources()
Helper to set source information for PARSE_EARLY variables.
Definition: persisted_variable.cc:892
File_version
Definition: persisted_variable.h:113
bool load_persist_file()
Search for persisted config file and if found read persistent options.
Definition: persisted_variable.cc:887
std::string to_hex(const std::string &value)
Definition: persisted_variable.cc:2342
Persisted_variables_uset * get_persisted_dynamic_parse_early_variables()
Get persisted parse-early variables.
Definition: persisted_variable.cc:2298
bool open_persist_backup_file(int flag)
Open persisted backup config file.
Definition: persisted_variable.cc:865
Persisted_variables_uset m_persisted_dynamic_parse_early_variables
Definition: persisted_variable.h:309
static Persisted_variables_cache * m_instance
Definition: persisted_variable.h:346
return_status decrypt_sensitive_variables()
Decrypt sensitive variables values.
Definition: persisted_variable.cc:2580
int read_persist_file_v1(const Json_object *json_object)
Read v1 persistent file.
Definition: persisted_variable.cc:1526
Persisted_variables_umap * get_persisted_static_sensitive_variables(THD *thd)
Get SENSITIVE persisted static variables.
Definition: persisted_variable.cc:2314
void cleanup()
Definition: persisted_variable.cc:2329
bool write_persist_file_v2(String &dest, bool &do_cleanup)
Write v2 persistent file.
Definition: persisted_variable.cc:675
bool get_file_encryption_key(std::unique_ptr< unsigned char[]> &file_key, size_t &file_key_length, bool generate=false)
Get file encryption key.
Definition: persisted_variable.cc:2381
return_status encrypt_sensitive_variables()
Encrypt sensitive variables values.
Definition: persisted_variable.cc:2508
static Persisted_variables_cache * get_instance()
Return a singleton object.
Definition: persisted_variable.cc:336
MYSQL_FILE * m_fd
Definition: persisted_variable.h:349
void handle_option_type_change()
Helper function to handle changes in option type.
Definition: persisted_variable.cc:1859
MEM_ROOT ro_persisted_argv_alloc
Definition: persisted_variable.h:357
std::string m_persist_filename
Definition: persisted_variable.h:350
Persisted_variables_uset m_persisted_dynamic_plugin_variables
Definition: persisted_variable.h:324
void keyring_support_available()
Set internal state to reflect keyring support status.
Definition: persisted_variable.cc:2652
Persisted_variables_uset m_persisted_dynamic_sensitive_variables
Definition: persisted_variable.h:311
Persisted_variables_umap * get_persisted_static_variables()
Get persisted static variables.
Definition: persisted_variable.cc:2306
std::string from_hex(const std::string &value)
Definition: persisted_variable.cc:2350
return_status
Definition: persisted_variable.h:243
static const char * get_variable_alias(const sys_var *system_var)
If the variable has an alias, return the name for the alias.
Definition: persisted_variable.cc:583
int read_persist_file()
Driver function: Read options from persistent file.
Definition: persisted_variable.cc:1893
Persisted_variables_uset m_persisted_dynamic_sensitive_plugin_variables
Definition: persisted_variable.h:319
bool set_variable(THD *thd, set_var *system_var)
Update in-memory copy for every SET PERSIST statement.
Definition: persisted_variable.cc:376
std::string m_sensitive_variables_blob
Definition: persisted_variable.h:341
Persisted_variables_umap m_persisted_static_variables
Definition: persisted_variable.h:306
Persisted_variables_uset * get_persisted_dynamic_sensitive_variables(THD *thd)
Get SENSITIVE persisted variables.
Definition: persisted_variable.cc:2284
mysql_mutex_t m_LOCK_persist_file
Definition: persisted_variable.h:352
void lock()
Acquire lock on m_persisted_dynamic_variables/m_persisted_static_variables.
Definition: persisted_variable.h:205
static String * get_variable_value(THD *thd, sys_var *system_var, String *str, bool *is_null)
Retrieve variables value from sys_var.
Definition: persisted_variable.cc:557
MEM_ROOT parse_early_persisted_argv_alloc
Definition: persisted_variable.h:354
std::string m_iv
Definition: persisted_variable.h:343
Persisted_variables_umap m_persisted_static_parse_early_variables
Definition: persisted_variable.h:304
Persisted_variables_cache()
Definition: persisted_variable.cc:231
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.
Definition: persisted_variable.cc:1983
int init(int *argc, char ***argv)
Initialize class members.
Definition: persisted_variable.cc:261
mysql_mutex_t m_LOCK_persist_variables
Definition: persisted_variable.h:345
Persisted_variables_umap m_persisted_static_sensitive_variables
Definition: persisted_variable.h:302
std::string m_persist_backup_filename
Definition: persisted_variable.h:351
void assert_lock_owner()
Assert caller that owns lock on m_persisted_dynamic_variables/m_persisted_static_variables.
Definition: persisted_variable.h:214
bool flush_to_file()
Driver: Flush in-memory copy to persistent file.
Definition: persisted_variable.cc:793
bool open_persist_file(int flag)
Open persisted config file.
Definition: persisted_variable.cc:844
File_version m_default_version
Definition: persisted_variable.h:363
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
Definition: persisted_variable.cc:940
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...
Definition: persisted_variable.cc:1423
Persisted_variables_umap * get_persisted_static_parse_early_variables()
Get persisted parse-early static variables.
Definition: persisted_variable.cc:2325
MEM_ROOT ro_persisted_plugin_argv_alloc
Definition: persisted_variable.h:359
Using this class is fraught with peril, and you need to be very careful when doing so.
Definition: sql_string.h:167
For each client connection we create a separate thread with THD serving as a thread/connection descri...
Definition: sql_lexer_thd.h:36
set_var_base descendant for assignments to the system variables.
Definition: set_var.h:978
A class representing one system variable - that is something that can be accessed as @global....
Definition: set_var.h:106
#define mysql_mutex_lock(M)
Definition: mysql_mutex.h:50
#define mysql_mutex_unlock(M)
Definition: mysql_mutex.h:57
#define mysql_mutex_assert_owner(M)
Wrapper, to use safe_mutex_assert_owner with instrumented mutexes.
Definition: mysql_mutex.h:112
static int flag
Definition: hp_test1.cc:40
This file follows Google coding style, except for the name MEM_ROOT (which is kept for historical rea...
Some integer typedefs for easier portability.
unsigned long long int ulonglong
Definition: my_inttypes.h:56
Defines various enable/disable and HAVE_ macros related to the performance schema instrumentation sys...
ABI for instrumented mutexes.
std::string str(const mysqlrouter::ConfigGenerator::Options::Endpoint &ep)
Definition: config_generator.cc:1081
std::conditional_t< !std::is_array< T >::value, std::unique_ptr< T, detail::Deleter< T > >, std::conditional_t< detail::is_unbounded_array_v< T >, std::unique_ptr< T, detail::Array_deleter< std::remove_extent_t< T > > >, void > > unique_ptr
The following is a common type that is returned by all the ut::make_unique (non-aligned) specializati...
Definition: ut0new.h:2439
void my_init_persist_psi_keys(void)
CLASS Persisted_variables_cache Holds <name,value> pair of all options which needs to be persisted to...
Definition: persisted_variable.cc:161
Instrumentation helpers for mutexes.
Performance schema instrumentation interface.
PSI_memory_key key_memory_persisted_variables_memroot
Definition: psi_memory_key.cc:124
Our own string classes, used pervasively throughout the executor.
case opt name
Definition: sslopt-case.h:29
The MEM_ROOT is a simple arena, where allocations are carved out of larger blocks.
Definition: my_alloc.h:83
An instrumented FILE structure.
Definition: mysql_file.h:484
Definition: persisted_variable.h:326
std::string m_file_key_iv
Definition: persisted_variable.h:332
const size_t m_master_key_size
Definition: persisted_variable.h:329
std::string m_master_key_name
Definition: persisted_variable.h:327
std::string m_master_key_type
Definition: persisted_variable.h:328
std::string m_file_key
Definition: persisted_variable.h:331
An instrumented mutex structure.
Definition: mysql_mutex_bits.h:50
STRUCT st_persist_var_hash.
Definition: persisted_variable.h:80
size_t operator()(const st_persist_var &pv) const
Definition: persisted_variable.h:81
STRUCT st_persist_var.
Definition: persisted_variable.h:55
st_persist_var()
Definition: persisted_variable.cc:201
std::string user
Definition: persisted_variable.h:59
ulonglong timestamp
Definition: persisted_variable.h:58
std::string value
Definition: persisted_variable.h:57
bool is_null
Definition: persisted_variable.h:61
std::string key
Definition: persisted_variable.h:56
std::string host
Definition: persisted_variable.h:60
bool operator==(const st_persist_var &persist_var) const
Definition: persisted_variable.h:69