如何在OceanBase中新增系统变量及应用实践

因为系统变量涉及复杂的工程文件，为防止新增变量操作对软件系统的潜在影响，OceanBase为多数开发者设计了一套高效的编程框架。此框架允许开发者在新增及使用系统变量时，仅需专注于变量定义的细节。具体来说，通过运行一个Python脚本，开发者可以自动化地生成新增系统变量所需的代码，极大地简化了操作过程。

本文以一个案例，说明如何在OceanBase中新增一个系统变量，以及如何进行应用。

系统变量（variables）

生效范围：global（租户隔离）/session（会话级隔离）

案例：

ob_query_timeout 用于设置对SQL语句进行DML操作的超时时间，单位是微秒。

系统变量的生成

如何去为OB新增一个系统变量

需要注意的点1.修改/src/share/system_variables/ob_system_variable_init.json，并执行/src/share/system_variables/gen_ob_sys_variables.py即可。 下图就是ob_system_variable_init.json中的一个变量对应json对象。

2.系统变量的id应该保证单调递增3.无法废弃系统变量 (只增不删)4.修改ob_system_variable_init.json文件，哪怕是改了info，实际都等价于修改了upgrade_pre.py，是需要推版本号的。

ob_system_variable_init.json涉及到的字段

base_value 和 default_value

这里存在两个value，一个是default_value， 一个是base_value。第一次申请新增变量时，两个值是相同的，如果后面新版本需要修改默认值时，只需要修改default_value即可，base_value仅作为基线不会再被修改。

data_type 变量的数据类型，包括int、uint、varchar、enum、bool。

on_check_and_convert_func

对此变量的校验方法，需要在ob_system_variable.cpp中去实现对这个变量的校验与转换。

例：

"ob_query_timeout": {
      "id": 10005,
      "name": "ob_query_timeout",
      "default_value": "10000000",
      "base_value": "10000000",
      "data_type": "int",
      "info": "Query timeout in microsecond(us)",
      "flags": "GLOBAL | SESSION | NEED_SERIALIZE",
      "on_check_and_convert_func": "ObSysVarOnCheckFuncs::check_and_convert_timeout_too_large",
      "publish_version": "",
      "info_cn": "",
      "background_cn": "",
      "ref_url": ""
}

//ObSysVarOnCheckFuncs::check_and_convert_timeout_too_large 将对ob_query_timeout进行限制

enum_names

限制该变量的可选项

例子：enum_names 限制了mysql租户还是oracle租户类型

"ob_compatibility_mode": {
    "id": 10030,
    "name": "ob_compatibility_mode",
    "default_value": "0",
    "base_value": "0",
    "data_type": "enum",
    "info": "What DBMS is OceanBase compatible with? MYSQL means it behaves like MySQL while ORACLE means it behaves like Oracle.",
    "flags": "GLOBAL | SESSION | READONLY | WITH_UPGRADE | NEED_SERIALIZE",
    "enum_names": [
          "MYSQL",
          "ORACLE"
          ],
    "publish_version": "",
    "info_cn": "",
    "background_cn": "",
    "ref_url": ""
},

​flags

变量的标记，记录这个变量的特性。

GLOBAL 租户全局生效
SESSION sesssion生效
NEED_SERIALIZE 需要序列化到远端（涉及远程、分布式执行计划）
INFLUENCE_PLAN 变量的改变是否清空相关的Plan cache。
INVISIBLE 隐藏变量
READONLY 变量只读，不可更改
SESSION_READONLY session级别只读，global级别可更改
WITH_UPGRADE 只有ob_compatibility_mode有此flag，用来区别其他READONLY的变量。
NULL  只有字符类型相关的变量才具有的flag，作用未知。

生成新增系统变量

执行gen_ob_sys_variables.py后，如下的工程文件发生了变化。受影响的工程文件如下图所示，这些文件会被底层一套复杂的分布式session管理模块所调用。

重新编译后，show variables可以看到成功添加了新的变量。

系统变量的使用

变量的调用是 基于ObBasicSessionInfo这个类实现的，需要为其实现一个方法，以便其他逻辑通过session对象获取系统变量。

ObBasicSessionInfo存储系统变量及其相关变量，并存储远程执行SQL任务时需要序列化到远端的状态信息，例如上面提到的ob_query_timeout这个需要序列化的变量。

ObSQLSessionInfo是ObBasicSessionInfo的一个子类，存储其他状态信息，如prepared statment相关信息等。

使用的话需要在ObBasicSessionInfo中定义一个获取变量的方法，例：

class ObBasicSessionInfo
{ 
      ...
      public:
      int get_query_timeout(int64_t &query_timeout) const
      {
            query_timeout = sys_vars_cache_.get_ob_query_timeout();
            return common::OB_SUCCESS;
      }
      ...
      
      ...
      int ObBasicSessionInfo::get_enable_parallel_dml(bool &v) const
      {
            return get_bool_sys_var(SYS_VAR__ENABLE_PARALLEL_DML, v);
      }
      ...
}

get_query_timeout这个方法内的sys_vars_cache有一个成员对象SysVarsCacheData，它是ObBasicSessionInfo的内部缓存以提升性能，部分经常被使用到的变量就会加入到缓存中，如ob_query_timeout，该变量会提前初始化到内存中。而大部分的系统变量还是基于sys_vars_存储的，如get_enable_parallel_dml这个方法底层还是从sys_vars_中获取变量。

class ObBasicSessionInfo
{ 
​    ...
    class SysVarsCache
    {
        ...
        public:
        SysVarsCacheData inc_data_;
        ...
    }
    ...
    private:
    SysVarsCache sys_vars_cache_;
    ...
    
    private:
    share::ObBasicSysVar *sys_vars_[share::ObSysVarFactory::ALL_SYS_VARS_COUNT];
    ...
}

调用变量例子：

int ObMPQuery::process()
{
...
ObSQLSessionInfo &session = *sess;
...
else if (OB_FAIL(session.get_query_timeout(query_timeout))) {
LOG_WARN("fail to get query timeout", K_(sql), K(ret));
...
}