MySQL 8.0.30
Source Code Documentation
persisted_variable.h
Go to the documentation of this file.
1/* Copyright (c) 2016, 2022, 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 also distributed 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 included with MySQL.
13
14 This program is distributed in the hope that it will be useful,
15 but WITHOUT ANY WARRANTY; without even the implied warranty of
16 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 GNU General Public License, version 2.0, for more details.
18
19 You should have received a copy of the GNU General Public License
20 along with this program; if not, write to the Free Software
21 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */
22
23#ifndef PERSISTED_VARIABLE_H_INCLUDED
24#define PERSISTED_VARIABLE_H_INCLUDED
25
26#include <stddef.h>
27#include <map>
28#include <string>
29#include <unordered_set>
30
31#include "map_helpers.h"
32#include "my_alloc.h"
33#include "my_inttypes.h"
34#include "my_psi_config.h"
38#include "sql/psi_memory_key.h"
39#include "sql_string.h"
40
41class Json_dom;
42class Json_object;
43class THD;
44class set_var;
45class sys_var;
46struct MYSQL_FILE;
47
48/**
49 STRUCT st_persist_var
50
51 This structure represents information of a variable which is to
52 be persisted in mysql-auto.cnf file.
53*/
54struct st_persist_var final {
55 std::string key;
56 std::string value;
58 std::string user;
59 std::string host;
60 bool is_null;
62 st_persist_var(THD *thd);
63 st_persist_var(const std::string key, const std::string value,
64 const ulonglong timestamp, const std::string user,
65 const std::string host, const bool is_null);
66 /* This is custom comparison function used to make the unordered_set
67 work with the default std::hash for user defined types. */
68 bool operator==(const st_persist_var &persist_var) const {
69 return key == persist_var.key;
70 }
71};
72
73/**
74 STRUCT st_persist_var_hash
75
76 This structure has a custom hasher function used to make the unordered_set
77 to work with the default std::hash for userdefined types.
78*/
80 size_t operator()(const st_persist_var &pv) const { return pv.key.length(); }
81};
82
83/**
84 CLASS Persisted_variables_cache
85 Holds <name,value> pair of all options which needs to be persisted
86 to a file.
87
88 OVERVIEW
89 --------
90 When first SET PERSIST statement is executed we instantiate
91 Persisted_variables_cache which loads the config file if present into
92 m_persisted_dynamic_variables set. This is a singleton operation.
93 m_persisted_dynamic_variables is an in-memory copy of config file itself. If
94 the SET statement passes then this in-memory is updated and flushed to file as
95 an atomic operation.
96
97 Next SET PERSIST statement would only update the in-memory copy and sync
98 to config file instead of loading the file again.
99*/
100
101#ifdef HAVE_PSI_INTERFACE
102void my_init_persist_psi_keys(void);
103#endif /* HAVE_PSI_INTERFACE */
104
109
111 protected:
112 enum class File_version {
113 VERSION_V1 = 1,
115 };
116
117 public:
118 explicit Persisted_variables_cache();
119 int init(int *argc, char ***argv);
121 /**
122 Update in-memory copy for every SET PERSIST statement
123 */
124 bool set_variable(THD *thd, set_var *system_var);
125 /**
126 Driver: Flush in-memory copy to persistent file
127 */
128 bool flush_to_file();
129 /**
130 Write v2 persistent file
131 */
132 bool write_persist_file_v2(String &dest, bool &do_cleanup);
133 /**
134 Driver function: Read options from persistent file
135 */
136 int read_persist_file();
137 /**
138 Read v1 persistent file
139 */
140 int read_persist_file_v1(const Json_object *json_object);
141 /**
142 Read v2 persistent file
143 */
144 int read_persist_file_v2(const Json_object *json_object);
145 /**
146 Search for persisted config file and if found read persistent options
147 */
148 bool load_persist_file();
149 /**
150 Set persisted options
151 */
152 bool set_persisted_options(bool plugin_options);
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
192 /**
193 append PARSE EARLY read only persisted variables to command
194 line options with a separator.
195 */
196 bool append_parse_early_variables(int *argc, char ***argv,
197 bool &arg_separator_added);
198
199 void cleanup();
200
201 /**
202 Acquire lock on m_persisted_dynamic_variables/m_persisted_static_variables
203 */
205 /**
206 Release lock on m_persisted_dynamic_variables/m_persisted_static_variables
207 */
209 /**
210 Assert caller that owns lock on
211 m_persisted_dynamic_variables/m_persisted_static_variables
212 */
215 }
216 /**
217 Set internal state to reflect keyring support status
218 */
220
221 std::string to_hex(const std::string &value);
222 std::string from_hex(const std::string &value);
223
224 private:
225 /* Helper function to get variable value */
226 static String *get_variable_value(THD *thd, sys_var *system_var, String *str,
227 bool *is_null);
228 /**
229 If the variable has an alias, return the name for the alias.
230 */
231 static const char *get_variable_alias(const sys_var *system_var);
232 static std::string get_variable_alias(const char *name);
233 /* Helper function to extract variables from json formatted string */
235 bool is_read_only = false);
236 /**
237 After extracting the variables from the JSON, we duplicate any
238 variable definition that relates to an alias.
239 */
240 void load_aliases();
241
243 bool get_file_encryption_key(std::unique_ptr<unsigned char[]> &file_key,
244 size_t &file_key_length, bool generate = false);
247
248 /** Helper to set source information for PARSE_EARLY variables */
250
251 private:
252 /* Helper functions for file IO */
254 bool open_persist_file(int flag);
256 void close_persist_file();
257
258 private:
259 /*
260 There are two main types of variables:
261 1. Static variables: Those which cannot be set at runtime
262 2. Dynamic variables: Those which can be set on a running server
263
264 Each of these types is further divided in 3 sub-types:
265 A. PARSE_EARLY variables - This set of variables require to be set very
266 early in server start-up sequence
267 B. SENSITIVE variables - This set of variables may be stored in
268 encrypted format if a suitable keyring
269 component is available
270 C. All other variables - These are the variables that do not have
271 none of the mentioned properties
272
273 Two of the above mentioned sub-types exist because we treat
274 variables with certain properties in special manner for reasons mentioned
275 above for each of the In future, more categories may need special
276 treatment and if so, above mentioned sub-categories will increase.
277
278 These gives us total of 6 categories (3 each for static and dynamic
279 types of variables). Each of these categories of variables are processed
280 and/or loaded at different point of time in start-up sequence:
281
282 - 1A and 2A variables are added to command line argument at the very
283 beginning of the start-up
284 - 1B and 2B are decrypted once keyring component is loaded.
285 - 1B and 1C are added to command line
286 - 2B and 2C are set at a later point in start-up cycle when THD
287 initialization is possible. Some of the variables of types 2B and 2C
288 are not processed until corresponding component or plugin is loaded.
289 These subsets of variables are moved to special in-memory containers
290 reserved for them.
291
292 The persisted options file contains 6 JSON objects - one each for
293 above mentioned categories. When file is read, data from each JSON object
294 is loaded in different in-memory containers.
295 */
296
297 /* In memory copy of Persisted PARSE EARLY static variables' values */
299 /* In memory copy of Persisted SENSITIVE static variables' values */
301 /* In memory copy of all other Persisted static variables' values */
303
304 /* In memory copy of Persisted PARSE EARLY dynamic variables' values */
306 /* In memory copy of Persisted SENSITIVE dynamic variables' values */
308 /* In memory copy of all other Persisted dynamic variables' values */
310
311 /*
312 In memory copy of Persisted SENSITIVE dynamic
313 variables whose plugin is not yet installed
314 */
316 /*
317 In memory copy of all other Persisted dynamic
318 variables whose plugin is not yet installed
319 */
321
322 struct Key_info {
323 std::string m_master_key_name{"persisted_variables_key"};
324 std::string m_master_key_type{"AES"};
325 const size_t m_master_key_size{32};
326
327 std::string m_file_key{};
328 std::string m_file_key_iv{};
329 };
330
331 /* Key */
333
334 /* Status of keyring support */
336 /* Sensitive variables blob - HEX representation */
338 /* IV - HEX representation */
339 std::string m_iv{};
340
343
344 /* File handler members */
349 /* Memory for parse early read only persisted options */
352 /* Memory for read only persisted options */
354 /* Memory for read only persisted plugin options */
357
358 /* default version */
360};
361
362#endif /* PERSISTED_VARIABLE_H_INCLUDED */
JSON DOM abstract base class.
Definition: json_dom.h:172
Represents a JSON container value of type "object" (ECMA), type J_OBJECT here.
Definition: json_dom.h:372
Definition: persisted_variable.h:110
Key_info m_key_info
Definition: persisted_variable.h:332
bool m_keyring_support_available
Definition: persisted_variable.h:335
Persisted_variables_uset * get_persisted_dynamic_variables()
Get persisted variables.
Definition: persisted_variable.cc:2193
bool reset_persisted_variables(THD *thd, const char *name, bool if_exists)
Reset persisted options.
Definition: persisted_variable.cc:2069
void clear_sensitive_blob_and_iv()
Definition: persisted_variable.cc:2254
void unlock()
Release lock on m_persisted_dynamic_variables/m_persisted_static_variables.
Definition: persisted_variable.h:208
void load_aliases()
After extracting the variables from the JSON, we duplicate any variable definition that relates to an...
Definition: persisted_variable.cc:1703
int read_persist_file_v2(const Json_object *json_object)
Read v2 persistent file.
Definition: persisted_variable.cc:1597
void close_persist_file()
Close persisted config file.
Definition: persisted_variable.cc:883
Persisted_variables_uset m_persisted_dynamic_variables
Definition: persisted_variable.h:309
void set_parse_early_sources()
Helper to set source information for PARSE_EARLY variables.
Definition: persisted_variable.cc:900
File_version
Definition: persisted_variable.h:112
bool load_persist_file()
Search for persisted config file and if found read persistent options.
Definition: persisted_variable.cc:895
std::string to_hex(const std::string &value)
Definition: persisted_variable.cc:2259
Persisted_variables_uset * get_persisted_dynamic_parse_early_variables()
Get persisted parse-early variables.
Definition: persisted_variable.cc:2215
bool open_persist_backup_file(int flag)
Open persisted backup config file.
Definition: persisted_variable.cc:873
Persisted_variables_uset m_persisted_dynamic_parse_early_variables
Definition: persisted_variable.h:305
bool append_read_only_variables(int *argc, char ***argv, bool arg_separator_added=false, bool plugin_options=false)
append read only persisted variables to command line options with a separator.
Definition: persisted_variable.cc:1983
static Persisted_variables_cache * m_instance
Definition: persisted_variable.h:342
return_status decrypt_sensitive_variables()
Decrypt sensitive variables values.
Definition: persisted_variable.cc:2497
int read_persist_file_v1(const Json_object *json_object)
Read v1 persistent file.
Definition: persisted_variable.cc:1482
Persisted_variables_umap * get_persisted_static_sensitive_variables(THD *thd)
Get SENSITIVE persisted static variables.
Definition: persisted_variable.cc:2231
void cleanup()
Definition: persisted_variable.cc:2246
bool write_persist_file_v2(String &dest, bool &do_cleanup)
Write v2 persistent file.
Definition: persisted_variable.cc:682
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:2298
return_status encrypt_sensitive_variables()
Encrypt sensitive variables values.
Definition: persisted_variable.cc:2425
static Persisted_variables_cache * get_instance()
Return a singleton object.
Definition: persisted_variable.cc:333
MYSQL_FILE * m_fd
Definition: persisted_variable.h:345
MEM_ROOT ro_persisted_argv_alloc
Definition: persisted_variable.h:353
std::string m_persist_filename
Definition: persisted_variable.h:346
Persisted_variables_uset m_persisted_dynamic_plugin_variables
Definition: persisted_variable.h:320
void keyring_support_available()
Set internal state to reflect keyring support status.
Definition: persisted_variable.cc:2569
Persisted_variables_uset m_persisted_dynamic_sensitive_variables
Definition: persisted_variable.h:307
Persisted_variables_umap * get_persisted_static_variables()
Get persisted static variables.
Definition: persisted_variable.cc:2223
std::string from_hex(const std::string &value)
Definition: persisted_variable.cc:2267
return_status
Definition: persisted_variable.h:242
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:590
int read_persist_file()
Driver function: Read options from persistent file.
Definition: persisted_variable.cc:1818
Persisted_variables_uset m_persisted_dynamic_sensitive_plugin_variables
Definition: persisted_variable.h:315
bool set_variable(THD *thd, set_var *system_var)
Update in-memory copy for every SET PERSIST statement.
Definition: persisted_variable.cc:373
std::string m_sensitive_variables_blob
Definition: persisted_variable.h:337
Persisted_variables_umap m_persisted_static_variables
Definition: persisted_variable.h:302
Persisted_variables_uset * get_persisted_dynamic_sensitive_variables(THD *thd)
Get SENSITIVE persisted variables.
Definition: persisted_variable.cc:2201
mysql_mutex_t m_LOCK_persist_file
Definition: persisted_variable.h:348
void lock()
Acquire lock on m_persisted_dynamic_variables/m_persisted_static_variables.
Definition: persisted_variable.h:204
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:564
MEM_ROOT parse_early_persisted_argv_alloc
Definition: persisted_variable.h:350
std::string m_iv
Definition: persisted_variable.h:339
Persisted_variables_umap m_persisted_static_parse_early_variables
Definition: persisted_variable.h:300
Persisted_variables_cache()
Definition: persisted_variable.cc:228
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:1905
int init(int *argc, char ***argv)
Initialize class members.
Definition: persisted_variable.cc:258
mysql_mutex_t m_LOCK_persist_variables
Definition: persisted_variable.h:341
Persisted_variables_umap m_persisted_static_sensitive_variables
Definition: persisted_variable.h:298
bool set_persisted_options(bool plugin_options)
Set persisted options.
Definition: persisted_variable.cc:942
std::string m_persist_backup_filename
Definition: persisted_variable.h:347
void assert_lock_owner()
Assert caller that owns lock on m_persisted_dynamic_variables/m_persisted_static_variables.
Definition: persisted_variable.h:213
bool flush_to_file()
Driver: Flush in-memory copy to persistent file.
Definition: persisted_variable.cc:801
bool open_persist_file(int flag)
Open persisted config file.
Definition: persisted_variable.cc:852
File_version m_default_version
Definition: persisted_variable.h:359
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:1379
Persisted_variables_umap * get_persisted_static_parse_early_variables()
Get persisted parse-early static variables.
Definition: persisted_variable.cc:2242
MEM_ROOT ro_persisted_plugin_argv_alloc
Definition: persisted_variable.h:355
Using this class is fraught with peril, and you need to be very careful when doing so.
Definition: sql_string.h:166
For each client connection we create a separate thread with THD serving as a thread/connection descri...
Definition: sql_class.h:922
set_var_base descendant for assignments to the system variables.
Definition: set_var.h:970
A class representing one system variable - that is something that can be accessed as @global....
Definition: set_var.h:104
#define mysql_mutex_lock(M)
Definition: mysql_mutex.h:49
#define mysql_mutex_unlock(M)
Definition: mysql_mutex.h:56
char * argv[]
Definition: do_ctype.cc:45
get_options & argc
Definition: do_ctype.cc:51
#define mysql_mutex_assert_owner(M)
Wrapper, to use safe_mutex_assert_owner with instrumented mutexes.
Definition: mysql_mutex.h:111
static int flag
Definition: hp_test1.cc:39
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:55
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:1055
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:2436
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:158
Instrumentation helpers for mutexes.
Performance schema instrumentation interface.
PSI_memory_key key_memory_persisted_variables_memroot
Definition: psi_memory_key.cc:119
Our own string classes, used pervasively throughout the executor.
case opt name
Definition: sslopt-case.h:32
The MEM_ROOT is a simple arena, where allocations are carved out of larger blocks.
Definition: my_alloc.h:82
An instrumented FILE structure.
Definition: mysql_file.h:482
Definition: persisted_variable.h:322
std::string m_file_key_iv
Definition: persisted_variable.h:328
const size_t m_master_key_size
Definition: persisted_variable.h:325
std::string m_master_key_name
Definition: persisted_variable.h:323
std::string m_master_key_type
Definition: persisted_variable.h:324
std::string m_file_key
Definition: persisted_variable.h:327
An instrumented mutex structure.
Definition: mysql_mutex_bits.h:49
STRUCT st_persist_var_hash.
Definition: persisted_variable.h:79
size_t operator()(const st_persist_var &pv) const
Definition: persisted_variable.h:80
STRUCT st_persist_var.
Definition: persisted_variable.h:54
st_persist_var()
Definition: persisted_variable.cc:198
std::string user
Definition: persisted_variable.h:58
ulonglong timestamp
Definition: persisted_variable.h:57
std::string value
Definition: persisted_variable.h:56
bool is_null
Definition: persisted_variable.h:60
std::string key
Definition: persisted_variable.h:55
std::string host
Definition: persisted_variable.h:59
bool operator==(const st_persist_var &persist_var) const
Definition: persisted_variable.h:68