MySQL 8.4.0
Source Code Documentation
Sys_var_deprecated_alias Class Reference

A deprecated alias for a variable. More...

#include <sys_vars.h>

Inheritance diagram for Sys_var_deprecated_alias:

Public Member Functions

 Sys_var_deprecated_alias (const char *name_arg, sys_var &base_var)
- Public Member Functions inherited from Sys_var_alias
 Sys_var_alias (const char *name_arg, sys_var &base_var)
sys_varget_base_var ()
void cleanup () override
 All the cleanup procedures should be performed here. More...
sys_var_pluginvarcast_pluginvar () override
 downcast for sys_var_pluginvar. More...
void update_default (longlong new_def_value) override
longlong get_default () override
longlong get_min_value () override
ulonglong get_max_value () override
ulong get_var_type () override
 Returns variable type. More...
void set_arg_source (get_opt_arg_source *arg_source) override
void set_is_plugin (bool is_plugin) override
bool is_non_persistent () override
void saved_value_to_string (THD *thd, set_var *var, char *def_val) override
 This function converts value stored in save_result to string. More...
bool check_update_type (Item_result type) override
enum_variable_source get_source () override
const char * get_source_name () override
void set_source (enum_variable_source src) override
bool set_source_name (const char *path) override
bool set_user (const char *usr) override
const char * get_user () override
const char * get_host () override
bool set_host (const char *hst) override
ulonglong get_timestamp () const override
void set_user_host (THD *thd) override
void set_timestamp () override
void set_timestamp (ulonglong ts) override
- Public Member Functions inherited from sys_var
 sys_var (sys_var_chain *chain, const char *name_arg, const char *comment, int flag_args, ptrdiff_t off, int getopt_id, enum get_opt_arg_type getopt_arg_type, SHOW_TYPE show_val_type_arg, longlong def_val, PolyLock *lock, enum binlog_status_enum binlog_status_arg, on_check_function on_check_func, on_update_function on_update_func, const char *substitute, int parse_flag, sys_var *persisted_alias=nullptr, bool is_persisted_deprecated=false)
 sys_var constructor More...
virtual ~sys_var ()=default
const char * get_deprecation_substitute ()
bool check (THD *thd, set_var *var)
const ucharvalue_ptr (THD *running_thd, THD *target_thd, enum_var_type type, std::string_view keycache_name)
const ucharvalue_ptr (THD *thd, enum_var_type type, std::string_view keycache_name)
my_optionget_option ()
bool set_default (THD *thd, set_var *var)
 Update the system variable with the default value from either session or global scope. More...
bool update (THD *thd, set_var *var)
SHOW_TYPE show_type ()
int scope () const
const CHARSET_INFOcharset (THD *thd)
bool is_readonly () const
bool not_visible () const
bool is_trilevel () const
bool is_persist_readonly () const
bool is_parse_early () const
bool is_sensitive () const
bool is_hint_updateable () const
 Check if the variable can be set using SET_VAR hint. More...
bool is_struct ()
 the following is only true for keycache variables, that support the syntax @keycache_name.variable_name More...
bool is_written_to_binlog (enum_var_type type)
bool check_scope (enum_var_type query_type)
 Return true for success if: Global query and variable scope is GLOBAL or SESSION, or Session query and variable scope is SESSION or ONLY_SESSION. More...
bool is_global_persist (enum_var_type type)
bool is_settable_at_command_line ()
 Return true if settable at the command line. More...
bool register_option (std::vector< my_option > *array, int parse_flags)
void do_deprecated_warning (THD *thd)
Itemcopy_value (THD *thd)
 Create item from system variable value. More...
void save_default (THD *thd, set_var *var)
bool check_if_sensitive_in_context (THD *, bool suppress_errors=true) const

Private Attributes

std::string m_comment

Additional Inherited Members

- Public Types inherited from sys_var
enum  flag_enum {
  GLOBAL = 0x0001 , SESSION = 0x0002 , ONLY_SESSION = 0x0004 , SCOPE_MASK = 0x03FF ,
  READONLY = 0x0400 , ALLOCATED = 0x0800 , INVISIBLE = 0x1000 , TRI_LEVEL = 0x2000 ,
  NOTPERSIST = 0x4000 , HINT_UPDATEABLE = 0x8000 , PERSIST_AS_READ_ONLY = 0x10000 , SENSITIVE = 0x20000
 Enumeration type to indicate for a system variable whether it will be written to the binlog or not. More...
- Public Attributes inherited from sys_var
 If the variable has an alias in the persisted variables file, this should point to it. More...
bool m_is_persisted_deprecated
 If m_persist_alias is set, and the current variable is deprecated and m_persist_alias is the recommended substitute, then this flag should be set to true. More...
enum sys_var::binlog_status_enum binlog_status
- Static Public Attributes inherited from sys_var
static const int PARSE_EARLY = 1
static const int PARSE_NORMAL = 2
- Protected Types inherited from sys_var
typedef bool(* on_check_function) (sys_var *self, THD *thd, set_var *var)
typedef bool(* pre_update_function) (sys_var *self, THD *thd, set_var *var)
typedef bool(* on_update_function) (sys_var *self, THD *thd, enum_var_type type)
- Protected Member Functions inherited from Sys_var_alias
 Sys_var_alias (const char *name_arg, sys_var &base_var, const char *deprecation_substitute_arg, sys_var *persisted_alias, bool is_persisted_deprecated)
 Special constructor used to implement Sys_var_deprecated alias. More...
const ucharsession_value_ptr (THD *running_thd, THD *target_thd, std::string_view keycache_name) override
 A pointer to a value of the variable for SHOW. More...
const ucharglobal_value_ptr (THD *thd, std::string_view keycache_name) override
- Protected Member Functions inherited from sys_var
ucharsession_var_ptr (THD *thd)
 A pointer to a storage area of the variable, to the raw data. More...
ucharglobal_var_ptr ()
- Protected Attributes inherited from sys_var
int flags
 or'ed flag_enum values More...
int m_parse_flag
 either PARSE_EARLY or PARSE_NORMAL. More...
const SHOW_TYPE show_val_type
 what value_ptr() returns for More...
my_option option
 min, max, default values are stored here More...
 second lock that protects the variable More...
ptrdiff_t offset
 offset to the value from global_system_variables More...
on_check_function on_check
pre_update_function pre_update
 Pointer to function to be invoked before updating system variable (but after calling on_check hook), while we do not hold any locks yet. More...
on_update_function on_update
const char *const deprecation_substitute
bool is_os_charset
 true if the value is in character_set_filesystem More...
struct get_opt_arg_source source
char host [HOSTNAME_LENGTH+1]
ulonglong timestamp

Detailed Description

A deprecated alias for a variable.

This tool allows us to rename system variables without breaking backward compatibility.

Procedure for a developer to create a new name for a variable in version X and remove the old name in version X+1:

  • In version X:
    • Change the string passed to the Sys_var constructor for the variable the new new name. All existing code for this should remain as it is.
    • Create a Sys_var_deprecated_alias taking the old name as the first argument and the Sys_var object having the new name as the second argument.
  • In version X+1:
    • Remove the Sys_var_deprecated_alias.

This has the following effects in version X:

  • Both variables coexist. They are both visible in performance_schema tables and accessible in SET statements and SELECT @variable statements. Both variables always have the same values.
  • A SET statement using either the old name or the new name changes the value of both variables.
  • A SET statement using the old name generates a deprecation warning.
  • The procedure that loads persisted variables from file accepts either the old name, or the new name, or both. It generates a deprecation warning in case only the old name exists in the file. A SET PERSIST statement writes both variables to the file.

The procedures for a user to upgrade or downgrade are:

  • After upgrade from version X-1 to X, all persisted variables retain their persisted values. User will see deprecation warnings when loading the persisted variables file, with instructions to run a SET PERSIST statement any time before the next upgrade to X+1.
  • While on version X, user needs to run a SET PERSIST statement any time before upgrading to X+1. Due to the logic described above, it will write both variables to the file.
  • While on version X, user needs to change their cnf files, command-line arguments, and @variables accessed through application logic, to use the new names, before upgrading to X+1. The deprecation warnings will help identify the relevant places to update.
  • After upgrade from X to X+1, the server will read the old variables from the file. Since this version does not know about the old variables, it will ignore them and print a warning. The user can remove the unknown variable from the persisted variable file, and get rid of the warning, using RESET PERSIST OLD_VARIABLE_NAME.
  • After downgrade from version X+1 to version X, all persisted variables retain their values. User will not see deprecation warnings. If user needs to further downgrade to version X-1, user needs to first run SET PERSIST for some variable in order to rewrite the file so that the old variable names exist in the file.
  • After downgrade from version X to version X-1, all persisted variables retain their values. If the new variable names exist in the persisted variables file, a warning will be printed stating that the variable is not known and will be ignored. User can get rid of the warning by running RESET PERSIST NEW_VARIABLE_NAME.

Constructor & Destructor Documentation

◆ Sys_var_deprecated_alias()

Sys_var_deprecated_alias::Sys_var_deprecated_alias ( const char *  name_arg,
sys_var base_var 

Member Data Documentation

◆ m_comment

std::string Sys_var_deprecated_alias::m_comment

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