openGauss数据库源码解析系列文章——AI技术（一）

def main():
   …
# 通过命令行参数或连接信息文件构建db_info字典，利用该字典中的信息可以登录到数据库实例和宿主机上
    db_info = build_db_info(args)
    if not db_info:
        parser.print_usage()
        return -1

    # 解析配置文件中给定的配置项
    config = get_config(args.tuner_config_file)
    if not config:
        return -1

try:
    # 当获取到足够的信息后，进入工具的执行流程
        return procedure_main(mode, db_info, config)
    except Exception as e:
        logging.exception(e)
        print('FATAL: An exception occurs during program running. '
              'The exception information is "%s". '
              'For details about the error cause, please see %s.' % (e, config['logfile']),
              file=sys.stderr, flush=True)
        return -1

def procedure_main(mode, db_info, config):
    # 权限最小化
    os.umask(0o0077)
    # 初始化日志模块
    set_logger(config['logfile'])
logging.info('Starting... (mode: %s)', mode)
# 利用new_db_agent函数构造DB_Agent对象，该对象是唯一对数据库操作进行封装的对象
    db_agent = new_db_agent(db_info)

    # 如果用户没有通过配置文件指定负载类型，则通过预定义的算法或规则进行自动判断
    if config['scenario'] in WORKLOAD_TYPE.TYPES:
        db_agent.metric.set_scenario(config['scenario'])
    else:
        config['scenario'] = db_agent.metric.workload_type
    # 同上，如果用户设置为自动模式，则使用下述默认规则补充
    if config['tune_strategy'] == 'auto':
        # If more iterations are allowed, reinforcement learning is preferred.
        if config['rl_steps'] * config['max_episode_steps'] > 1500:
            config['tune_strategy'] = 'rl'
        else:
            config['tune_strategy'] = 'gop'

logging.info("Configurations: %s.", config)
# 如果在配置文件中指定了tuning_list配置项，并且非reocmmend模式，则加载该待调优参数列表的配置文件，否则通过recommend_knobs函数智能获取待调优参数列表
    if config['tuning_list'].strip() != '' and mode != 'recommend':
        knobs = load_knobs_from_json_file(config['tuning_list'])
    else:
        print("Start to recommend knobs. Just a moment, please.")
        knobs = recommend_knobs(mode, db_agent.metric)
    if not knobs:
        logging.fatal('No recommended best_knobs for the database. Stop the execution.')
        return -1

    # 如果是调优和训练模式，由于某些数据库参数是需要重启后才生效的，因此可能会伴随着反复的重启过程
    if mode != 'recommend':  # 不为recommend模式，就只能是tune或者train模式，而这两种模式都是离线过程，需要反复迭代
        prompt_restart_risks()  # 告知用户调优过程中有数据库重启的风险
        # 初始化调优中的记录类
        recorder = Recorder(config['recorder_file'])
        # 分别读取配置文件中的三个配置项：benchmark_script、benchmark_path以及benchmark_cmd，通过这三个配置项就可以获取到benchmark驱动脚本的实例，可以用它来衡量数据库的性能
        bm = benchmark.get_benchmark_instance(config['benchmark_script'],
                                              config['benchmark_path'],
                                              config['benchmark_cmd'],
                                              db_info)
        # 初始化数据库调优环境实例，该对象封装了迭代过程，保持与强化学习库gym.Env的接口一致
        env = DB_Env(db_agent, benchmark=bm, recorder=recorder,
                     drop_cache=config['drop_cache'],
                     mem_penalty=config['used_mem_penalty_term'])
        env.set_tuning_knobs(knobs)
        # 识别不同的模式，不同模式执行对应的子程序
        if mode == 'train':
            rl_model('train', env, config)
        elif mode == 'tune':
            …
    # 执行到此处时，已经完成调优过程。下述代码负责将调优结果输出
    knobs.output_formatted_knobs()
    if config['output_tuning_result'] != '':
        with open(config['output_tuning_result'], 'w+') as fp:
            # train模式是强化学习独有的模式，在该模式下，只输出调优参数，不输出报告参数（建议参数）。这是因为，在强化学习的tune模式下，待调优参数列表应当与train模式下保存的调优列表需要完全相同，即调优参数名相同、调优范围相同、各个参数的顺序相同，否则会导致输入特征不符合。
            knobs.dump(fp, dump_report_knobs=mode != 'train')
    logging.info('X-Tuner is executed and ready to exit. '
                 'Please refer to the log for details of the execution process.')
    return 0

# 提示：你需要先把数据导入到数据库中
# 调优程序会自动调用下述函数，该函数返回结果值就是benchmark测试结果
# path 变量表示实际benchmark所在路径
path = ''
# cmd变量定义了使用什么shell命令才可以启动benchmark
cmd = ''

# 函数定义了远端和本地的命令行接口，通过exec_command_sync()方法执行shell命令
def run(remote_server, local_host) -> float:
    return 0

from tuner.exceptions import ExecutionError

# 提示：你需要自己下载benchmark-sql测试工具，同时使用openGauss的JDBC驱动替换PostgreSQL目录下的JDBC驱动文件。你需要自己配置好TPC-C测试配置

# 测试程序通过下述命令运行
path = '/path/to/benchmarksql/run'  # TPC-C测试脚本benchmark-sql的存放路径
cmd = "./runBenchmark.sh props.gs"  # 自定义一个名为props.gs的benchmark-sql测试配置文件
    
    
def run(remote_server,local_host):
    # 切换到TPC-C脚本目录下，清除历史错误日志，然后运行测试命令
    # 此处最好等待几秒钟，因为benchmark-sql测试脚本生成最终测试报告是通过一个shell脚本实现的，整个过程会有延迟
    # 为了保证能够获取到最终的tpmC数值报告，这里选择等待3秒钟
    stdout, stderr = remote_server.exec_command_sync(['cd %s' % path, 'rm -rf benchmarksql-error.log', cmd, 'sleep 3'])
    # 如果标准错误流中有数据，则报异常退出
    if len(stderr) > 0:
        raise ExecutionError(stderr)
    
    # 寻找最终tpmC结果
    tpmC = None
    split_string = stdout.split()  # 对标准输出流结果进行分词
    for i, st in enumerate(split_string):
        # 在benchmark-sql 5.0中，tpmC最终测试结果数值在‘(NewOrders)’关键字的后两位，正常情况下，找到该字段后直接返回即可
        if "(NewOrders)" in st:
            tpmC = split_string[i + 2]
            break
    stdout, stderr = remote_server.exec_command_sync(
        "cat %s/benchmarksql-error.log" % path)
    nb_err = stdout.count("ERROR:")  # 判断整个benchmark运行过程中，是否有报错，记录报错的错误数
    return float(tpmC) - 10 * nb_err  # 这里将报错的错误数作为一个惩罚项，惩罚系数为10，越高的惩罚系数表示越看中报错的数量

db=opengauss
driver=org.postgresql.Driver
// 配置连接信息
conn=jdbc:postgresql://192.168.1.100:5678/tpcc
…

// 定义数据量
warehouses=1
loadWorkers=4

// 定义并发量
terminals=100
//To run specified transactions per terminal- runMins must equal zero
runTxnsPerTerminal=10
//To run for specified minutes- runTxnsPerTerminal must equal zero
runMins=0
//Number of total transactions per minute
limitTxnsPerMin=300
  …

import time
    
from tuner.exceptions import ExecutionError
    
# 提示：你需要先自行导入数据，然后准备sql测试文件
# 下述程序会自动采集整体运行时延
path = '/path/to/tpch/queries'  # 存放TPC-H测试用的SQL脚本目录
cmd = "gsql -U {user} -W {password} -d {db} -p {port} -f {file}"  # 需要运行TPC-H测试脚本的命令，一般使用'gsql -f 脚本文件'来运行
# 需要指出的是，由于可能会通过gsql连接数据库，因此可能会需要用户名、密码等信息，可以通过上述占位符，如{user}、{password}等进行占位，X-Tuner会自行渲染
    
def run(remote_server, local_host):
    …
    # 代价为全部测试用例的执行总时长
    cost = time.time() - time_start
    # 取相反数，适配run 函数的定义：返回结果越大表示性能越好。
    return - cost

def get_benchmark_instance(script, path, cmd, db_info):
    …
# 验证benchmark 脚本有效性，如果没有指定path与cmd变量，会抛出异常
    if (not getattr(bm, 'path', False)) or (not getattr(bm, 'cmd', False)) or (not getattr(bm, 'run', False)):
        raise ConfigureError('The benchmark script %s is invalid. '
                             'For details, see the example template and description document.' % script)
    # 检查run函数是否存在，且参数数量为2，即本地和远程两个shell接口
    check_run_assertion = isinstance(bm.run, types.FunctionType) and bm.run.__code__.co_argcount == 2
    if not check_run_assertion:
        raise ConfigureError('The run function in the benchmark instance is not correctly defined. '
                             'Redefine the function by referring to the examples.')

# cmd与path变量，优先使用配置文件中的配置项，如果没有对应的配置项，则默认使用脚本中的内容
    if path.strip() != '':
        bm.path = path
    if cmd.strip() != '':
        bm.cmd = cmd

    # 渲染cmd命令中的占位符
    bm.cmd = bm.cmd.replace('{host}', db_info['host']) \
        .replace('{port}', str(db_info['port'])) \
        .replace('{user}', db_info['db_user']) \
        .replace('{password}', db_info['db_user_pwd']) \
        .replace('{db}', db_info['db_name'])

    # 将数据库宿主机的shell接口包装起来
    def wrapper(server_ssh):
        return bm.run(server_ssh, local_ssh)

    return wrapper

class Knob(object):
    def __init__(self, name, knob):
        …

    # 将整形数值转换为数据库可以接受的字符串型字面量
    def to_string(self, val):
        …

    #  将字符串型的字面量转换为数值型
    def to_numeric(self, val):
        …

class DB_Agent:
    def __init__(self, host, host_user, host_user_pwd,
                 db_user, db_user_pwd, db_name, db_port, ssh_port=22):
        …

        # 设置语句的执行时间不限
        self.set_knob_value("statement_timeout", 0)

        # 初始化数据库的特征指标接口
        self.metric = openGaussMetric(self)

    def check_connection_params(self):
        # 检查数据库连接参数是否正确
        …

    def set_tuning_knobs(self, knobs):
        # 设置调优参数，参数类型为RecommendedKnobs, 该类在knob.py文件中定义
        if not isinstance(knobs, RecommendedKnobs):
            raise TypeError

        self.knobs = knobs
        self.ordered_knob_list = self.knobs.names()
        … 
def exec_statement(self, sql, timeout=None):
        # 在数据库内执行SQL语句，是通过调用gsql命令来实现的
        command = "gsql -p {db_port} -U {db_user} -d {db_name} -W {db_user_pwd} -c \"{sql}\";".format(
            db_port=self.db_port,
            db_user=self.db_user,
            db_name=self.db_name,
            db_user_pwd=self.db_user_pwd,
            sql=sql
        ) 
        …

    def is_alive(self):
        # 检查数据库是否运行
        ...

    def exec_command_on_host(self, cmd, timeout=None, ignore_status_code=False):
        # 在数据库的宿主机上执行shell命令
        ...

    def get_knob_normalized_vector(self):
        # 获取待调优参数的结果，并将其进行归一化（映射到0与1之间）。返回结果是一个列表
        nv = list()
        for name in self.ordered_knob_list:
            val = self.get_knob_value(name)
            nv.append(self.knobs[name].to_numeric(val))
        return nv

    def set_knob_normalized_vector(self, nv):
        # 与get_knob_normalized_vector()方法对应，参数nv表示normalized_vector，即都是已经映射到0与1之间的、经过数值化的参数值，将这些参数值设置到数据库上
        restart = False
        for i, val in enumerate(nv):
            name = self.ordered_knob_list[i]
            knob = self.knobs[name]
            self.set_knob_value(name, knob.to_string(val))
            restart = True if knob.restart else restart

        # 如果这些待设置的参数中有需要重启数据库的，则重启数据库以便使设置后的参数生效
        if restart:
            self.restart()

    def get_knob_value(self, name):
        # 单独获取某个参数的值，该参数值是不经标准化的
        check_special_character(name)
        sql = "SELECT setting FROM pg_settings WHERE name = '{}';".format(name)
        _, value = self.exec_statement(sql)
        return value

    def set_knob_value(self, name, value):
        # 单独设置某个参数的值，该参数值是不经标准化的，通过gs_guc命令设置数据库参数值
        logging.info("change knob: [%s=%s]", name, value)
        try:
            self.exec_command_on_host("gs_guc reload -c \"%s=%s\" -D %s" % (name, value, self.data_path))
        except ExecutionError as e:
            if str(e).find('Success to perform gs_guc!') < 0:
                logging.warning(e)

    def reset_state(self):
        # 重置数据库的状态，例如对 pg_stat_database等系统表进行重置
        self.metric.reset()

    def set_default_knob(self):
        # 设置数据库的参数值为默认值，该默认值通过knob类型指定，即在对应的配置文件中指定的值
        restart = False

        for knob in self.knobs:
            self.set_knob_value(knob.name, knob.default)
            restart = True if knob.restart else restart

        self.restart()

    def restart(self):
        # 重启数据库
        ...

    def drop_cache(self):
        # 对于openGauss数据库来说，drop cache可以使每次benchmark的跑分更加稳定，但是这需要root权限
        # 如果用户需要drop cache，则可以向/etc/sudoers中写入'username ALL=(ALL) NOPASSWD: ALL'

def rl_model(mode, env, config):
    # 由于加载tensorflow的过程过于耗时，且并非是必要的，因此采用懒加载的模式
from tuner.algorithms.rl_agent import RLAgent

# 启动强化学习代理类
rl = RLAgent(env, alg=config['rl_algorithm'])

# 训练和调优两种模式对应不同的执行流程
# 模型需要先训练，然后才可以利用该模型进行调优。训练和调优过程的输出是待调优参数列表，由于共用一套模型，因此两种模式下，要求待调优的参数列表必须是一致的，否则会抛出输出维度不同的异常。
    if mode == 'train':
        logging.warning('The list of tuned knobs in the training mode '
                        'based on the reinforcement learning algorithm must be the same as '
                        'that in the tuning mode. ')
# 比较关键的参数是最大迭代轮次rl_steps，理论上越长越精准，但是也更加耗时
# max_episode_steps是强化学习算法中的每一轮的最大回合次数，在X-Tuner实现中，该参数被弱化了，一般默认即可
        rl.fit(config['rl_steps'], nb_max_episode_steps=config['max_episode_steps'])
        rl.save(config['rl_model_path'])
        logging.info('Saved reinforcement learning model at %s.', config['rl_model_path'])
    elif mode == 'tune':
        …

def global_search(env, config):
method = config['gop_algorithm']

# 判断选择使用哪种算法
    if method == 'bayes':
        from bayes_opt import BayesianOptimization

        action = [0 for _ in range(env.nb_actions)]
        pbound = {name: (0, 1) for name in env.db.ordered_knob_list}

        # 定义一个黑盒函数，用于适配第三方库的接口
        def performance_function(**params):
            assert len(params) == env.nb_actions, 'Failed to check the input feature dimension.'

            for name, val in params.items():
                index = env.db.ordered_knob_list.index(name)
                action[index] = val

            s, r, d, _ = env.step(action)
            return r  # 期望结果越大越好

        optimizer = BayesianOptimization(
            f=performance_function,
            pbounds=pbound
        )
        optimizer.maximize(
            # 最大迭代轮次越大结果越精准，但是也更耗时
            n_iter=config['max_iterations']
        )
    elif method == 'pso':
        from tuner.algorithms.pso import Pso

        def performance_function(v):
            s, r, d, _ = env.step(v, False)
            return -r  # 因为PSO算法的实现中是寻找全局最小值，这里取相反数，就改为取全局最大值

        pso = Pso(
            func=performance_function,
            dim=env.nb_actions,
            particle_nums=config['particle_nums'],
# 最大迭代轮次越大结果越精准，但是也更耗时
            max_iteration=config['max_iterations'],
            x_min=0, x_max=1, max_vel=0.5
        )
        pso.minimize()
    else:
        raise ValueError('Incorrect method value: %s.' % method)

 @cached_property
    def shared_buffers(self):
        # 此处应用的是DBA普遍认同的调优策略：在大内存环境下，shared_buffer占比可更高一些，小内存情况下占比应下调
        mem_total = self.metric.os_mem_total  # unit: kB
        if mem_total < 1 * SIZE_UNIT_MAP['GB']:
            default = 0.15 * mem_total
        elif mem_total > 8 * SIZE_UNIT_MAP['GB']:
            default = 0.4 * mem_total
        else:
            default = 0.25 * mem_total

        recommend = default / self.metric.block_size
        if self.metric.is_64bit:
            database_blocks = self.metric.all_database_size / self.metric.block_size
            # 如果数据库文件的比较小，则shared_buffer 也无须设置得太大，否则便是浪费资源
            if database_blocks < recommend:
                self.report.print_warn("The total size of all databases is less than the memory size. "
                                       "Therefore, it is unnecessary to set shared_buffers to a large value.")

            recommend = min(database_blocks, recommend)
            upper = recommend * 1.15
            lower = min(0.15 * mem_total / self.metric.block_size, recommend)

            return Knob.new_instance(name="shared_buffers",
                                     value_default=recommend,
                                     knob_type=Knob.TYPE.INT,
                                     value_max=upper,
                                     value_min=lower,
                                     restart=True)
        else:
            # 对于非64位操作系统，shared_buffer无须设置得太大
            upper = min(recommend, 2 * SIZE_UNIT_MAP["GB"] / self.metric.block_size)  # 32-bit OS only can use 2 GB mem.
            lower = min(0.15 * mem_total / self.metric.block_size, recommend)
            return Knob.new_instance(name="shared_buffers",
                                     value_default=recommend,
                                     knob_type=Knob.TYPE.INT,
                                     value_max=upper,
                                     value_min=lower,
                                     restart=True)

pip install -r requirements.txt

cd tuner # 切换到main.py文件所在的目录中
export PYTHONPATH='..'  # 将上一级目录添加到PYTHONPATH环境变量中，即可寻找到包所在的路径
python main.py --help  # 执行相应的功能，此处以获取帮助为例

python setup.py install

gs_xtuner --help

gs_xtuner recommend --db-name opengauss --db-user omm --port 5678 --host 192.168.1.100 --host-user omm

{
  "db_name": "opengauss",  # 数据库名
  "db_user": "omm",       # 登录到数据库上的用户名
  "host": "127.0.0.1",    # 数据库宿主机的IP地址
  "host_user": "omm",     # 登录到数据库宿主机的用户名
  "port": 5432,           # 数据库的侦听端口号
  "ssh_port": 22          # 数据库宿主机的SSH侦听端口号
}

gs_xtuner recommend –f connection.json

select name, setting from pg_settings;

...  
 -x TUNER_CONFIG_FILE, --tuner-config-file TUNER_CONFIG_FILE
                        This is the path of the core configuration file of the
                        X-Tuner. You can specify the path of the new
                        configuration file. The default path is /path/to/xtuner/xtuner.conf.
                        You can modify the configuration file to control the
                        tuning process.
...

{
  "work_mem": {
    "default": 65536,
    "min": 65536,
    "max": 655360,
    "type": "int",
    "restart": false
  },
  "shared_buffers": {
    "default": 32000,
    "min": 16000,
    "max": 64000,
    "type": "int",
    "restart": true
  },
  "random_page_cost": {
    "default": 4.0,
    "min": 1.0,
    "max": 4.0,
    "type": "float",
    "restart": false
  },
  "enable_nestloop": {
    "default": true,
    "type": "bool",
    "restart": false
  }
}

gs_xtuner train -f connection.json

gs_xtuner tune -f connection.json