proxysql/doc/internal/global_variables.txt

Each module of ProxySQL can have global variables and should be configurable
through the admin interface.
As such, the interface for the management of these global variables should be
either very simple, or managed by a simple API.

Trying to make a standard API, the proposed functions are:
  virtual char **get_variables_list() {return NULL;}
  virtual bool has_variable(char *name) {return false;}
  virtual char *get_variable(char *name) {return NULL;};
  virtual bool set_variable(char *name, char *value) {return false;};
  virtual void commit() {};
  virtual void wrlock() {};
  virtual void wrunlock() {};

In order:
- get_variables_list() returns an array of pointer to variables name, where the
  last element is NULL;
- has_variable() returns true if the given name is the name of one of the module
  variables;
- get_variable() returns the value of a specific variable. If the variable was
  not previously set, the module should return the default value. If the
  variable doesn't exist, NULL should be returned;
- set_variable() set the variable "name" to the value "value" . On success, true
  is returned. If "name" does not exist or if "value" is not valid, false is
  return;
- commit() trigger the module to read the new setting. Its implementation is
  specific to the module;
- wrlock() and wrunlock() are a way to acquire and release mutex or write lock,
  as it is not guaranteed that the any of the previous command is thread-safe.


Current specific implementation.

Standard_ProxySQL_Admin is the current Admin Module.
It allows users to modify such global variables through a table called
global_variables that has 2 columns:
- variable_name (VARCHAR NOT NULL PRIMARY KEY)
- variable_value (VARCHAR NOT NULL)

To distinguish variables from different modules, variable_name has the follow
format: <module>-<name>
For example:
admin-admin_credentials
admin-interfaces
mysql-poll_timeout
mysql-server_version

Current modules that support global variables:
- MySQL_Threads_Handler ("mysql" prefix) : currently implemented in
  Standard_MySQL_Threads_Handler, that then handles Standard_MySQL_Thread;
- ProxySQL_Admin ("admin" prefix) : currently implemented in
  Standard_ProxySQL_Admin . Although ProxySQL_Admin don't interact with other
  modules when processing its own variables, the same interface is used for
  semplicity and to provide threads safety.


Implementation details in Standard_ProxySQL_Admin.
Standard_ProxySQL_Admin uses the follow functions to handle global variables: 
- flush_<module>_variables___database_to_runtime
- flush_<module>_variables___runtime_to_database

flush_<module>_variables___database_to_runtime :
a) selects all the variables that have name like "<module>-%" and strips the
   prefix
b) for each of them try to set it with set_variable()
c) if #b fails, it calls get_variable() with the same name
d) if #c succeed, update the value in the table; if #c fails, delete the row
   from the table


Global variable scope
Some variables are specific to a certain module (for example Admin), while
other variables could have a less specific scope.
For example, global variable mysql-stats_time_query_processor is relavent
only in MySQL_Thread module, while global variable mysql-monitor_username is
relevant in many modules: MySQL_Thread, MySQL_Monitor, and
MySQL_Hostgroups_Manager.
If a global variable is relevant only in a specific module, it is defined in
the specific module only (Admin, MySQL_Thread, ClickHouse Server, etc).
When a global variable is relevant in many modules, it is defined as a thread
local storage, in proxysql_structs.h .
For historical reasons (legacy code), a lot of global variables that are
relevant only to MySQL_Thread are still defined as thread local storage.
No matter if a thread local storage is used or not, the thread using it will
always make a local copy so that it can safely access its own copy with no
locking needed.


Variable type
Variables can be of 3 types:
- string
- interger
- boolean


Adding a new global variable
Adding a new global variable requires:
- define the scope of it
- register its name in the relevant module
- define its default value (to be assigned during the creation of the module)
- define its input validation in set_variable()
- define the retrieval method in refresh_variables() and get_variable_*()
  (depending from data type)
- add the code where the variable itself is evaluated and action is taken

For example:
- if the scope is global, define a variable named mysql_thread___variable_name
  in proxysql_struct.h
- if the scope is not global, define a variable named variable_name in
  MySQL_Thread_Handler::variables and MySQL_Thread::variables
- register the name variable_name in mysql_thread_variables_names[]
- define its default in MySQL_Threads_Handler::MySQL_Threads_Handler()
- define the input validation (range, possible values, etc) in
  MySQL_Threads_Handler::set_variable(), where the value is processed
- in MySQL_Thread::refresh_variables() defines how to copy the global value
  into the local value, either in mysql_thread___variable_name or
  variables.variable_name, calling MySQL_Threads_Handler::get_variable_int()
- if the variable is a pointer of char, remember to free it when it goes out
  of scope