《OceanBase 配置项&系统变量实现及应用详解》专题导读

在使用OceanBase的过程中，看到大家经常会遇到“参数”、“配置项”、“系统变量”等概念，却不太清楚它们是不是同一个东西，以及应该如何使用。一些对数据库开发感兴趣的朋友，也想知道它们的实现原理是怎样的，并且想尝试自己增加一些配置项或者变量。

目前已经有一些文档和博客介绍过了相关概念和基本的用法（见“参考文档”），并且也有少量的源码解析文章，但总的来说相关资料还不太完整。

《OceanBase 配置项&系统变量实现及应用详解》专题基于大家的常见问题，通过基础篇、开发篇以及应用篇的内容，给大家介绍 OceanBase 配置项以及系统变量的实现原理、使用方法、开发流程、问题排查等知识，希望能够帮助大家解决各种应用问题。

这是专题的第一篇，主要为大家介绍配置项的基本概念和使用方法。

什么是配置项（参数）？

参数（parameter）的概念来源于Oracle，在 OceanBase 中，参数也叫做配置项，它对集群或租户的硬件规格、部署形式、行为方式进行了定义。

在部署 OceanBase 集群时，首先就会用到配置文件。如果是白屏工具，至少也需要设置cpu数量、内存大小、磁盘大小等参数，这些参数就是“配置项”。

集群配置项示例：

// 集群cpu总数
cpu_count=8
// 系统租户内存大小
system_memory=1G
// 集群内存总大小
memory_limit=16G
// 网络线程数量
net_thread_count=4

配置项分为集群级别和租户级别两种，集群配置项对整个集群生效，只能通过系统租户修改。租户配置项只对当前租户生效，可以通过当前租户或系统租户修改。

租户配置项示例：

// 是否开启负载均衡功能
enable_rebalance=true
// 是否开启提前解行锁功能
enable_early_lock_release=true
// 触发冻结的内存使用比例
freeze_trigger_percentage=20

配置项会持久化到安装目录下的 etc/observer.config.bin 文件中，包括集群和租户配置项，但是只存储和默认值不同的配置项，剩下的通过默认值即可恢复。

配置项的生效方式分为动态和静态，大部分配置项都是动态生效的，通过sql命令修改即可生效。少数配置项是静态生效的，修改后需要重启集群才能生效，比如 net_thread_count、enable_cgroup。

查询配置项

配置项可以通过“show parameters”命令查询，这种方式比较推荐。另外也可以通过视图或内部表进行查询，前提是需要对视图或内部表的内容有所了解。

使用 show parameters 命令查询配置项

• 系统租户

1. 查询集群配置项：

show parameters where name = 'xxx';

mysql> show parameters where name = 'cpu_count';
+-------+----------+----------------+----------+-----------+-----------+-------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------+---------+---------+-------------------+
| zone  | svr_type | svr_ip         | svr_port | name      | data_type | value | info                                                                                                                                                                             | section  | scope   | source  | edit_level        |
+-------+----------+----------------+----------+-----------+-----------+-------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------+---------+---------+-------------------+
| zone3 | observer | 192.168.10.3   |    12805 | cpu_count | NULL      | 32    | the number of CPU\'s in the system. If this parameter is set to zero, the number will be set according to sysconf; otherwise, this parameter is used. Range: [0,+∞) in integer   | OBSERVER | CLUSTER | DEFAULT | DYNAMIC_EFFECTIVE |
| zone1 | observer | 192.168.10.1   |    12801 | cpu_count | NULL      | 32    | the number of CPU\'s in the system. If this parameter is set to zero, the number will be set according to sysconf; otherwise, this parameter is used. Range: [0,+∞) in integer   | OBSERVER | CLUSTER | DEFAULT | DYNAMIC_EFFECTIVE |
| zone2 | observer | 192.168.10.2   |    12803 | cpu_count | NULL      | 32    | the number of CPU\'s in the system. If this parameter is set to zero, the number will be set according to sysconf; otherwise, this parameter is used. Range: [0,+∞) in integer   | OBSERVER | CLUSTER | DEFAULT | DYNAMIC_EFFECTIVE |
+-------+----------+----------------+----------+-----------+-----------+-------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------+---------+---------+-------------------+
3 rows in set (0.06 sec)

可以看到，一个配置项在每个节点都有一个副本，他们的值是一致的。其中 name 是配置项名；value是配置项的值；scope 表示作用域，也就是集群级别（CLUSTER）或租户级别（TENANT）；edit_level 表示生效方式，分为动态生效（DYNAMIC_EFFECTIVE）和静态生效（STATIC_EFFECTIVE）。

2. 查询当前租户的配置项：

show parameters where name = 'xxx';

3. 查询指定租户的配置项；

show parameters where name = 'xxx' tenant = xxx;

• 普通租户

1. 查询集群配置项：

show parameters where name = 'xxx';

2. 查询当前租户的配置项：

show parameters where name = 'xxx';

mysql> show parameters where name = 'freeze_trigger_percentage';
+-------+----------+----------------+----------+---------------------------+-----------+-------+----------------------------------------------------------------------------------------+---------+--------+---------+-------------------+
| zone  | svr_type | svr_ip         | svr_port | name                      | data_type | value | info                                                                                   | section | scope  | source  | edit_level        |
+-------+----------+----------------+----------+---------------------------+-----------+-------+----------------------------------------------------------------------------------------+---------+--------+---------+-------------------+
| zone1 | observer | 192.168.10.1   |    12801 | freeze_trigger_percentage | NULL      | 20    | the threshold of the size of the mem store when freeze will be triggered. Rang:(0,100) | TENANT  | TENANT | DEFAULT | DYNAMIC_EFFECTIVE |
| zone2 | observer | 192.168.10.2   |    12803 | freeze_trigger_percentage | NULL      | 20    | the threshold of the size of the mem store when freeze will be triggered. Rang:(0,100) | TENANT  | TENANT | DEFAULT | DYNAMIC_EFFECTIVE |
| zone3 | observer | 192.168.10.3   |    12805 | freeze_trigger_percentage | NULL      | 20    | the threshold of the size of the mem store when freeze will be triggered. Rang:(0,100) | TENANT  | TENANT | DEFAULT | DYNAMIC_EFFECTIVE |
+-------+----------+----------------+----------+---------------------------+-----------+-------+----------------------------------------------------------------------------------------+---------+--------+---------+-------------------+
3 rows in set (0.02 sec)

通过内部表与视图查询配置项

集群配置项和租户配置项存在于不同的表中，通过执行“select * from xxx; ”命令即可查询所有配置项，增加where参数也可查找指定配置项。

• __all_virtual_sys_parameter_stat

集群配置项和系统租户的租户配置项。

• __all_virtual_tenant_parameter_info

所有租户的租户配置项。

• __all_virtual_tenant_parameter_stat

集群配置项和所有租户配置项。

• GV$OB_PARAMETERS

集群配置项和所有租户配置项，即 __all_virtual_tenant_parameter_stat 的视图。

mysql> select * from GV$OB_PARAMETERS where name like '%weak_read%' and zone = 'zone1';
+---------------+----------+-------+---------+-----------+------------------------------------+-----------+-------+----------------------------------------------------------------------------+----------+-------------------+
| SVR_IP        | SVR_PORT | ZONE  | SCOPE   | TENANT_ID | NAME                               | DATA_TYPE | VALUE | INFO                                                                       | SECTION  | EDIT_LEVEL        |
+---------------+----------+-------+---------+-----------+------------------------------------+-----------+-------+----------------------------------------------------------------------------+----------+-------------------+
| 192.168.10.1  |    12801 | zone1 | CLUSTER |      NULL | weak_read_version_refresh_interval | NULL      | 100ms | the time interval to refresh cluster weak read version Range: [50ms, +∞)   | OBSERVER | DYNAMIC_EFFECTIVE |
| 192.168.10.1  |    12801 | zone1 | TENANT  |         1 | enable_monotonic_weak_read         | NULL      | False | specifies observer supportting atomicity and monotonic order read          | TENANT   | DYNAMIC_EFFECTIVE |
| 192.168.10.1  |    12801 | zone1 | TENANT  |      1001 | enable_monotonic_weak_read         | NULL      | False | specifies observer supportting atomicity and monotonic order read          | TENANT   | DYNAMIC_EFFECTIVE |
| 192.168.10.1  |    12801 | zone1 | TENANT  |      1002 | enable_monotonic_weak_read         | NULL      | False | specifies observer supportting atomicity and monotonic order read          | TENANT   | DYNAMIC_EFFECTIVE |
+---------------+----------+-------+---------+-----------+------------------------------------+-----------+-------+----------------------------------------------------------------------------+----------+-------------------+
4 rows in set (0.00 sec)

查询该视图，可以同时看到集群配置项和租户配置项，集群配置项全局唯一，租户配置项每个租户各有一个。

• V$OB_PARAMETERS

当前节点下所有集群配置项和租户配置项。

• __tenant_parameter

增量租户配置项内部表。修改租户配置项时，会将新值写到租户对应的该表中，每个租户各有一张该表。

• __all_sys_parameter

增量集群配置项内部表。系统租户修改集群配置项时，会将新值写到全局唯一的该表中。

修改配置项

配置项可以通过4种方式进行修改和设置：

1. 部署配置文件（xxx.yaml）；
2. 启动参数（./bin/observer -o xxx=xx）；
3. 持久化配置文件（etc/observer.config.bin）；
4. SQL命令（alter system set xxx=xx）：

通过部署配置文件设置配置项

在使用obd工具或脚本部署 OceanBase 集群时，一般都会用到一个部署配置文件（single.yaml、distributed.yaml 等），里面的参数就是集群配置项，它们指定了集群部署的节点地址、安装目录、硬件规格等参数。

其中 observer.include.yaml 文件是部署工具自带的默认配置，包含了安装部署所需要的配置项，其中的值和代码中配置项的默认值可能有所不同。在部署时会优先选择用户编写的 xxx.yaml 中的值，然后再去 observer.include.yaml 文件中寻找配置项的值，最后才会从代码中获取默认值。

部署配置文件示例：

oceanbase:
  servers:
    - name: server1
      ip: 127.0.0.1
  server1:
    mysql_port: 23410
    rpc_port: 23411
    home_path: /data/observer1
    zone: zone1
    data_dir: /data/observer1/data
    redo_dir: /data/observer1/redo
  tag: latest
  include: /data/oceanbase/tools/deploy/obd/observer.include.yaml
  global: 
    devname: lo
    memory_limit: '8G'
    system_memory: '1G'
    datafile_size: '40G'
    log_disk_size: '40G'
    cpu_count: '4'

在部署过程中，这些配置会以参数的形式出现在observer进程的启动命令中，最终和“通过启动参数设置配置项”殊途同归。

通过启动参数设置配置项

通过在 observer 的启动命令中增加参数，可以在部署集群时直接设置配置项的值。这种方式一般很少手动使用，但在重启observer时也是一种可行的方法。

在启动命令中设置参数：

./observer -o xxx=xx,yyy=yy

observer启动命令示例：

/data/user/observer1/bin/observer -p 23400 -P 23401 -z zone1 -c 1 -d /data/user/observer1/store -i lo -r 127.0.0.1:23401:23400 -o __min_full_resource_pool_memory=268435456,major_freeze_duty_time=Disable,datafile_size=20G,memory_limit=10G,system_memory=5G,cpu_count=24,stack_size=512K,cache_wash_threshold=1G,workers_per_cpu_quota=10,schema_history_expire_time=1d,net_thread_count=4,minor_freeze_times=10,enable_separate_sys_clog=False,enable_merge_by_turn=False,syslog_io_bandwidth_limit=10G,enable_async_syslog=False

通过持久化配置文件修改配置项

前面说过，配置项会持久化到文件 etc/observer.config.bin 中。如果直接修改该文件，然后再启动集群，也可以达到修改配置项的效果。不过这种方式并不推荐，有一定风险。

持久化配置文件示例：

^Aû<8d><80><80>^@¼Þ^@ ^@^Aÿ8^@^@^@^@^@^@^@^@^@^@^FÛ^@^@^FÛ^@^@^@^@,^L<90>4^A<9d><85><80><80>^@observer_id=1
local_ip=xxx.xxx.xxx.1
all_server_list=xxx.xxx.xxx.1:23401,xxx.xxx.xxx.2:23403,xxx.xxx.xxx.3:23405
__min_full_resource_pool_memory=1073741824
log_disk_size=100G
min_observer_version=4.2.0.0
workers_per_cpu_quota=10
cache_wash_threshold=1G
enable_syslog_wf=False
syslog_io_bandwidth_limit=10G
syslog_level=WDIAG
cluster_id=1
rootservice_list=xxx.xxx.xxx.1:23401:23400;xxx.xxx.xxx.2:23403:23402;xxx.xxx.xxx.3:23405:23404
schema_history_expire_time=1d
cpu_count=11
system_memory=2G
memory_limit=32G
net_thread_count=4
zone=zone1
devname=eth0
mysql_port=23400
rpc_port=23401
datafile_maxsize=8G
datafile_next=2G
datafile_size=80G
data_dir=/data/1/user/observer1/store
^A²<88><80><80>^@^Aí<81><80><80>^@[1]
^Aã<81><80><80>^@enable_sql_extension=True
ob_compaction_schedule_interval=10s
_enable_adaptive_compaction=False
merger_check_interval=10s
partition_balance_schedule_interval=0
balancer_idle_time=10s
compatible=4.2.0.0
cpu_quota_concurrency=10
^AÀ<81><80><80>^@[1001]
^A³<81><80><80>^@enable_sql_extension=True
ob_compaction_schedule_interval=10s
_enable_adaptive_compaction=False
merger_check_interval=10s
partition_balance_schedule_interval=0
compatible=4.2.0.0
^AÀ<81><80><80>^@[1002]
^A³<81><80><80>^@enable_sql_extension=True
ob_compaction_schedule_interval=10s
_enable_adaptive_compaction=False
merger_check_interval=10s
partition_balance_schedule_interval=0
compatible=4.2.0.0

通过SQL命令修改配置项

用命令修改配置项是最常用的一种方式。

• 系统租户

1. 修改集群配置项：

alter system set xxx = 'xxx';

2. 修改当前租户的配置项：

alter system set xxx = 'xxx';

3. 修改指定租户的配置项：

alter system set xxx = 'xxx' tenant = xxx;

4. 修改所有租户的配置项：

alter system set xxx = 'xxx' tenant = all;

• 普通租户

修改当前租户的配置项：

alter system set xxx = 'xxx';

小结

本期博客介绍了配置项（参数）的概念和使用方法，相信大家只要注意区分作用域和生效方式，在使用配置项时就不会有太大问题。如果大家在部署集群或者创建租户时遇到问题，建议看看集群或租户配置项设置是否合理。如果测试性能不符合预期，有可能是因为租户规格不太合适，可以试着调整下相关配置项。

下一篇博客将会介绍“系统变量”的概念和用法，并对配置项和系统变量进行对比，感兴趣的同学不妨关注一下。

参考文档

1. 配置项和系统变量概述
2. 配置项总览
3. OB有问必答 | 参数和变量的区别是什么？
4. ​​​​​​​调整 OceanBase 配置项参数​​​​​​​