openGauss开源数据库二次开发指导手册（下）_opengauss symbol

本节内容主要介绍编译和验证二次开发结果。

编译

编译环境要求

操作系统环境要求

操作系统环境要求如下表。

下文章节中以使用华为云ECS服务的鲲鹏服务器（ARM架构+ openEuler操作系统）为例进行介绍。
您也可以自行选择在本地PC机安装虚拟机进行操作（X86架构），详细步骤可参考《在虚拟机+CentOS上安装部署openGauss数据库指导手册》或《在虚拟机+openEuler上安装部署openGauss数据库指导手册》。

软件依赖要求

openGauss的软件依赖要求如下表所示：

安装命令：

yum install -y autoconf gcc gcc-c++ libaio-devel flex bison ncurses-devel glibc-devel patch readline readline-devel dkms python3-devel pam-devel libffi-devel automake byacc cmake openssl-devel libtool-devel
1

编译环境准备(使用代金券购买华为云ECS服务)

登录华为云

步骤 1进入华为云官网。
华为云官网：https://www.huaweicloud.com/，进入华为云官网，点击登录。

步骤 2输入账号名和密码，点击登录。

如果还没有注册，点击免费注册，按步骤进行注册与实名制认证后进行登录。

• 说明：
  请进行实名制认证后再执行下述操作。

购买弹性云服务器ECS

步骤 1在华为云主页(https://www.huaweicloud.com/)点击产品，选择基础服务，再选择弹性云服务器ECS。

步骤 2进入弹性云服务器ECS购买界面。

步骤 3自定义购买进行基础配置。

其余默认即可，点击下一步网络配置。
步骤 4自定义购买进行网路配置。

其余默认即可，点击下一步高级配置。
步骤 5自定义购买进行高级配置。

记住用户名为root，然后输入自定义密码和确认密码，其余默认即可，点击下一步确认设置。

步骤 6确认配置购买成功。

确认设置信息，尤其是配置费用，然后勾选协议“我已经阅读并同意《华为镜像免责声明》”，点击立即购买。

查看云服务器列表。

等待几分钟后，状态为“运行中“则表示购买成功！
注意：本次购买鲲鹏服务器价格为公测价格，具体价格以华为云官网为准。

版本编译

openGauss的编译过程和生成安装包的过程已有一个一键式的脚本build.sh，可以方便地通过build.sh脚本进行编译操作；
本节介绍openGauss使用一键式脚本编译的操作步骤，编译流程如下图所示：

代码下载

步骤 1登录购买的ECS实例。
在弹性云服务列表上，单击服务器后面的“远程登录“操作，以root用户登录至服务器。

步骤 2在linux环境下安装软件依赖包。

[root@ecs-5045 ~]# yum install -y autoconf gcc gcc-c++ libaio-devel flex bison ncurses-devel glibc-devel patch readline readline-devel dkms python3-devel pam-devel libffi-devel automake byacc cmake openssl-devel libtool-devel
1

步骤 3在linux环境下安装Git工具并配置Git环境。

[root@ecs-5045 ~]# yum install git -y    ---安装git工具
[root@ecs-5045 ~]# git config --global user.name "Your Name"          --- 配置git用户名
[root@ecs-5045 ~]# git config --global user.email "email@example.com"  --- 配置git全局邮件账号
1
2
3

Your Name为自己的git用户名，请替换为实际自己实际用户名。
email@example.com为注册Gitee的主邮箱，请替换为实际自己实际主邮箱。
生成git公钥和私钥。

[root@ecs-5045 ~]# ssh-keygen -t rsa -C "email@example.com"         --- 生成git公钥和私钥
1

email@example.com为注册Gitee的主邮箱，请替换为实际自己实际主邮箱。
执行结果如下：

/root/.ssh/id_rsa.pub 为生成的git公钥文件，读取该文件内容。

复制出上面文件内容，并在个人Gitee账户中添加此SSH公钥。

步骤 4用Git工具下载openGauss-server和openGauss-OM代码。
先创建本地代码仓库存放目录/openGauss-lab/soft。

[root@ecs-5045 ~]# mkdir -p /openGauss-lab/soft
[root@ecs-5045 ~]# cd /openGauss-lab/soft
[root@ecs-5045 soft]#
1
2
3

openGauss-server是server代码仓库，openGauss-OM是工具代码仓库，两者均用于后续安装openGauss。

# git clone [git ssh address] openGauss-server  ##下载个人server代码仓库
# git clone [git ssh address] openGauss-OM    ##下载个人OM代码仓库
1
2

上述命令中：
[git ssh address]表示实际代码下载地址，即个人库地址，可在openGauss社区获取。
个人server代码仓库地址：

个人OM代码仓库地址：

执行下载结果如下：

步骤 5获取已编译好的第三方二进制代码。
该二进制文件用于openGauss-server代码的编译。

[root@ecs-5045 soft]# wget https://opengauss.obs.cn-south-1.myhuaweicloud.com/1.1.0/openGauss-third_party_binarylibs.tar.gz
1

下载项进度均显示为100%时表示下载成功，具体如下：

解压并移动该二进制文件。

[root@ecs-5045 soft]# tar -zxf openGauss-third_party_binarylibs.tar.gz    ----数分钟后解压成功
[root@ecs-5045 soft]# mv openGauss-third_party_binarylibs binarylibs
1
2

软件安装编译

前提条件

• 已按照搭建编译环境的要求准备好相关软硬件，并且已经下载了代码；
• 了解 build.sh脚本的参数选项和功能；
• 代码环境干净，没有以前编译生成的文件。

编译openGauss-server

步骤 1执行如下命令进入到软件代码编译脚本目录。

[root@ecs-5045 soft]# cd /openGauss-lab/soft/openGauss-server
1

步骤 2执行如下命令，编译安装openGauss。

[root@ecs-5045 openGauss-server] # sh build.sh -m release -3rd /openGauss-lab/soft/binarylibs -pkg
1

该步骤执行大概需要15-30分钟，与主机规格有关，请耐心等待。
步骤 3显示如下内容，表示安装包编译成功。

…………………………………….
make server(all) package success!
packaging libpq...
success!
packaging tools...
success!
Begin to install upgrade_sql files...
Successfully packaged upgrade_sql files.
End package opengauss.
now, all packages has finished!
1
2
3
4
5
6
7
8
9
10

生成的安装包存放在“/openGauss-lab/soft/openGauss-server/output”目录下，编译结果：
openGauss-1.1.0-openEuler-64bit-Libpq.tar.gz
openGauss-1.1.0-openEuler-64bit.sha256
openGauss-1.1.0-openEuler-64bit-symbol.tar.gz
openGauss-1.1.0-openEuler-64bit.tar.bz2 -----此包大概有89M
openGauss-1.1.0-openEuler-64bit-toosl.tar.gz
upgrade_sql.sha256
upgrade_sql.tar.gz

[root@ecs-5045 openGauss-server]# cd /openGauss-lab/soft/openGauss-server/output
[root@ecs-5045 output]# ll
total 334M
-rw------- 1 root root  12M Apr 20 15:28 openGauss-2.0.0-openEuler-64bit-Libpq.tar.gz
-rw------- 1 root root   65 Apr 20 15:28 openGauss-2.0.0-openEuler-64bit.sha256
1
2
3
4
5

如下图：

编译日志为“./build/script/makemppdb_pkg.log”，安装包打包日志为“./build/script/make_package.log”。

编译openGauss-OM

安装openGauss时需要OM工具，因此需要编译openGauss-OM。
步骤 1执行如下命令进入到软件代码编译脚本目录。

[root@ecs-5045 soft]# cd /openGauss-lab/soft/openGauss-OM
1

步骤 2执行如下命令，编译安装OM。

[root@ecs-5045 openGauss-OM] # sh build.sh -3rd /openGauss-lab/soft/binarylibs
1

步骤 3显示如下内容，表示安装包编译成功。

Everything is ready
success!
1
2

编译结果路径：/openGauss-lab/soft/openGauss-OM/package/。
编译结果：
openGauss-1.1.0-openEuler-64bit-om.tar.gz
openGauss-1.1.0-openEuler-64bit-om.sha256

[root@ecs-5045 openGauss-OM]# cd /openGauss-lab/soft/openGauss-OM/package/
[root@ecs-5045 package]# ll
total 17M
-rw------- 1 root root  65 Apr 16 16:27 openGauss-2.0.0-openEuler-64bit-om.sha256
-rw------- 1 root root 17M Apr 16 16:27 openGauss-2.0.0-openEuler-64bit-om.tar.gz
1
2
3
4
5

验证二次开发结果

安装编译后的openGauss安装包

修改操作系统配置

为了操作方便，也可以使用SSH工具（比如：PuTTY等）从本地电脑通过配置弹性云服务器的弹性公网IP地址（如:124.70.36.251）来连接ECS，并使用ROOT用户来登录。

设置字符集参数

将各数据库节点的字符集设置为相同的字符集，可以在/etc/profile文件中添加"export LANG=XXX"（XXX为Unicode编码）。

步骤 1 在/etc/profile文件中添加"export LANG= en_US.UTF‐8"

[root@ecs-5045 ~]# cat >>/etc/profile<<EOF
export LANG=en_US.UTF‐8
EOF
1
2
3

步骤 2 输入如下命令，使修改生效。

[root@ecs-5045 ~]# source /etc/profile
1

修改python版本

之后安装过程中openGauss用户互信，openEuler服务器需要用到Python-3.7.x命令，但是默认Python版本为Python-2.7.x，所以需要切换Python版本。
步骤 1进入/usr/bin文件，备份python文件。

[root@ecs-5045 ~]# cd /usr/bin
1

备份python文件。

[root@ecs-5045 bin] # mv python python.bak 
1

步骤 2建立python3软连接。

[root@ecs-5045 bin] # ln -s python3 /usr/bin/python 
1

步骤 3验证python版本。

[root@ecs-5045 bin] # python -V 
1

显示如下，说明切换成功：

Python 3.7.4
1

规划数据库安装包目录

步骤 1 登录ECS，规划存放安装包的目录并创建，并将内容设置为当前用户可读可执行。

[root@ecs-5045 bin]# mkdir -p /opt/software/openGauss
[root@ecs-5045 bin]# chmod 755 -R /opt/software
1
2

注：

• 不建议把安装包的存放目录规划到openGauss用户的家目录或其子目录下，可能导致权限问题。
• openGauss用户须具有/opt/software/openGauss目录的读写权限。

步骤 2 将数据库安装包放置到规划目录下。

[root@ecs-5045 bin]# cp /openGauss-lab/soft/openGauss-server/output/* /opt/software/openGauss
[root@ecs-5045 bin]# cp /openGauss-lab/soft/openGauss-OM/package/* /opt/software/openGauss
1
2

说明：/openGauss-lab/soft/openGauss-server /output 路径是编译openGauss-server后安装包的默认存放路径；
/openGauss-lab/soft/openGauss-OM/package是编译openGauss-OM后安装包的默认存放路径。

创建XML配置文件

• 安装openGauss前需要创建XML文件。XML文件包含部署openGauss的服务器信息、安装路径、IP地址以及端口号等。用于告知openGauss如何部署。用户需根据不同场合配置对应的XML文件。
• 以单节点配置的方案为例，说明如何创建XML配置文件。
  步骤 1 以root用户登录待安装openGauss的主机，切换到存放安装包的目录。

[root@ecs-5045 bin]# cd /opt/software/openGauss
1

步骤 2 创建XML配置文件，用于数据库安装。

[root@ecs-5045 openGauss]# vi clusterconfig.xml
1

输入”i”进入INSERT模式，添加文本如下，加粗字体内容为示例，可自行替换。其中“ecs-5045”是弹性云服务器的名称，“192.168.0.58”为弹性云服务器的IP地址（私有），其他value值可以不进行修改。

<?xml version="1.0" encoding="UTF-8"?> 
<ROOT> 
    <CLUSTER> 
        <PARAM name="clusterName" value="dbCluster" /> 
        <PARAM name="nodeNames" value="ecs-5045" /> 
        <PARAM name="backIp1s" value="192.168.0.58"/> 
        <PARAM name="gaussdbAppPath" value="/opt/gaussdb/app" /> 
        <PARAM name="gaussdbLogPath" value="/var/log/gaussdb" /> 
        <PARAM name="gaussdbToolPath" value="/opt/huawei/wisequery" /> 
        <PARAM name="corePath" value="/opt/opengauss/corefile"/> 
        <PARAM name="clusterType" value="single-inst"/> 
    </CLUSTER> 
   
    <DEVICELIST> 
        
        <DEVICE sn="1000001"> 
            <PARAM name="name" value="ecs-5045"/> 
            <PARAM name="azName" value="AZ1"/> 
            <PARAM name="azPriority" value="1"/> 
            <PARAM name="backIp1" value="192.168.0.58"/> 
            <PARAM name="sshIp1" value="192.168.0.58"/> 
             
	    <!--dbnode--> 
	    <PARAM name="dataNum" value="1"/> 
	    <PARAM name="dataPortBase" value="26000"/> 
	    <PARAM name="dataNode1" value="/gaussdb/data/db1"/> 
        </DEVICE> 
    </DEVICELIST> 
</ROOT>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

弹性云服务器名称及私有IP查看：

步骤 4点击“ESC”退出INSERT模式，然后输入“:wq”后回车退出编辑并保存文本。

表5-1配置文件参数附加说明

须知：

• “/opt/huawei/newsql/tools”存放互信等工具，避免权限问题，不要把实例数据目录放在此目录下；
• 安装目录和数据目录需为空或者不存在，否则可能导致安装失败；
• 在对数据库节点的实例进行具体配置时，需确保配置的目录之间不相互耦合。即各个配置目录不关联，删除其中任意一个目录，不会级联删除其它目录。如gaussdbAppPath为"/opt/gaussdb/app"，gaussdbLogPath为"/opt/gaussdb/app/omm"。当gaussdbAppPath目录被删除时，会级联删除gaussdbLogPath目录，从而引起其它问题；
• 若需要安装脚本自动创建安装用户时各配置的目录需保证不与系统创建的默认用户目录耦合关联；
• 配置openGauss路径和实例路径时，路径中不能包含"|",";","&","$","<",">","`","\","’",""","{","}","(",")","[","]","~","*","?"特殊字符。

初始化安装环境

为了保证openGauss的正确安装，请首先对主机环境进行配置。

准备安装用户及环境

创建完openGauss配置文件后，在执行安装前，为了后续能以最小权限进行安装及openGauss管理操作，保证系统安全性，需要运行安装前置脚本gs_preinstall准备好安装用户及环境。

前提条件

已完成安装准备的所有任务。

注意事项

• 用户需要检查上层目录权限，保证安装用户对安装包和配置文件目录读写执行的权限；
• xml文件中主机的名称与IP映射配置正确；
• 只能使用root用户执行gs_preinstall命令。

操作步骤

步骤 1修改performance.sh文件。
使用vi打开文件“/etc/profile.d/performance.sh”，具体如下：

[root@ecs-5045 openGauss]# vi /etc/profile.d/performance.sh
1

输入”i”，进入INSERT模式。用#注释sysctl -w vm.min_free_kbytes=112640 &> /dev/null这行。

CPUNO=`cat /proc/cpuinfo|grep processor|wc -l`
export GOMP_CPU_AFFINITY=0-$[CPUNO - 1]

#sysctl -w vm.min_free_kbytes=112640 &> /dev/null
sysctl -w vm.dirty_ratio=60 &> /dev/null
sysctl -w kernel.sched_autogroup_enabled=0 &> /dev/null
          
1
2
3
4
5
6
7

点击“ESC”退出INSERT模式。输入“:wq”后回车，保存退出。
步骤 2 为确保openssl版本正确，执行预安装前加载安装包中lib库。
执行命令如下。

[root@ecs-5045 openGauss]# vi /etc/profile
1

输入i，进入INSERT模式，在文件的底部添加如下代码，加载安装包中lib库，其中packagePath为用户安装包放置的路径，本示例中为/opt/software/openGauss。按下“Esc”退出INSERT模式，输入”:wq”后回车，保存后退出。

export packagePath=/opt/software/openGauss
export LD_LIBRARY_PATH=$packagePath/script/gspylib/clib:$LD_LIBRARY_PATH
1
2

配置完成后，输入如下命令，使设置生效。

[root@ecs-5045 openGauss]# source /etc/profile
1

步骤 3 在安装包所在的目录下，解压安装包。
执行以下命令进入安装包目录。

[root@ecs-5045 openGauss]# cd /opt/software/openGauss
1

解压openGauss-1.1.0-openEuler-64bit-om.tar.gz包。

[root@ecs-5045 openGauss]# tar -zxvf openGauss-2.0.0-openEuler-64bit-om.tar.gz
1

解压后，用ls命令查看如下。

[root@ecs-5045 openGauss]# ls
clusterconfig.xml                             
openGauss-2.0.0-openEuler-64bit-om.sha256  
openGauss-2.0.0-openEuler-64bit-symbol.tar.gz  script  pgrade_sql.tar.gz                                              
openGauss-2.0.0-openEuler-64bit-om.tar.gz  
openGauss-2.0.0-openEuler-64bit.tar.bz2        simpleInstall       version.cfg
openGauss-2.0.0-openEuler-64bit-Libpq.tar.gz  openGauss-2.0.0-openEuler-64bit.sha256     openGauss-2.0.0-openEuler-64bit-tools.tar.gz   upgrade_sql.sha256
1
2
3
4
5
6
7

安装包解压后，会在/opt/software/openGauss路径下自动生成script子目录，并且在script目录下生成gs_preinstall等各种OM工具脚本。
步骤 4 使用gs_preinstall准备好安装环境，切换到gs_preinstall命令所在目录。

[root@ecs-5045 openGauss]# cd /opt/software/openGauss/script/
1

script中内容显示如下：

[root@ecs-5045 script]# ls
gs_backup   gs_checkperf  gs_om             gspylib      gs_uninstall   __init__.py
gs_check    gs_collector  gs_postuninstall  gs_ssh       gs_upgradectl  killall
gs_checkos  gs_install    gs_preinstall     gs_sshexkey  impl           local
1
2
3
4

步骤 5 采用交互模式执行，并在执行过程中会创建root用户互信和openGauss用户互信：

[root@ecs-5045 script]# python gs_preinstall -U omm -G dbgrp -X /opt/software/openGauss/clusterconfig.xml
1

这里的omm为操作系统用户（注：同时omm也是openGauss的数据库管理员账号，在下面的5.1.5 环节中会创建），dbgrp为运行openGauss的操作系统用户的群组名称，/opt/software/openGauss/clusterconfig.xml为openGauss配置文件路径。在执行过程中，用户根据提示选择是否创建互信，并输入root用户或openGauss用户的密码。
对root创建trust，输入root的密码，购买弹性服务云时自定义的密码。

Are you sure you want to create trust for root (yes/no)? yes
Please enter password for root.
Password: --说明：此处输入密码时，屏幕上不会有任何反馈，不用担心，这是LINUX操作系统对密码的保护.
Creating SSH trust for the root permission user.
1
2
3
4

创建操作系统omm用户，并对omm创建trust，并设置密码，设置为Admin@123(建议用户自定义设置密码)。

Are you sure you want to create the user[omm] and create trust for it (yes/no)? yes
Please enter password for cluster user.
Password: --说明：此处输入密码时，屏幕上不会有任何反馈，不用担心，这是LINUX操作系统对密码的保护.
Please enter password for cluster user again.
Password: --说明：此处输入密码时，屏幕上不会有任何反馈，不用担心，这是LINUX操作系统对密码的保护.
Successfully created [omm] user on all nodes.
1
2
3
4
5
6

成功后显示为：

……
Setting finish flag.
Successfully set finish flag.
Preinstallation succeeded.
1
2
3
4

执行安装

按上述步骤准备好openGauss安装环境之后，按照启动安装过程部署openGauss。

前提条件

• 已成功执行前置脚本gs_preinstall；
• 服务器操作系统和网络均正常运行。

操作步骤

步骤 1改文件权限。

[root@ecs-5045 script]# chmod -R 755/opt/software/openGauss/script 
1

步骤 2登录到openGauss的主机，并切换到omm用户。

[root@ecs-5045 script]# su - omm
1

注：

• omm指的是前置脚本gs_preinstall中-U参数指定的用户。
• 安装脚本gs_install必须以前置脚本中指定的omm执行，否则，脚本执行会报错。

步骤 3使用gs_install安装openGauss。
执行以下命令进行安装：

gs_install -X /opt/software/openGauss/clusterconfig.xml --gsinit-parameter="--encoding=UTF8"  --dn-guc="max_process_memory=3GB"  --dn-guc="shared_buffers=256MB" --dn-guc="bulk_write_ring_size=256MB" --dn-guc="cstore_buffers=16MB"
1

具体如下：

[omm@ecs-c9bf ~]$ gs_install -X /opt/software/openGauss/clusterconfig.xml --gsinit-parameter="--encoding=UTF8"  --dn-guc="max_process_memory=3GB"  --dn-guc="shared_buffers=256MB" --dn-guc="bulk_write_ring_size=256MB" --dn-guc="cstore_buffers=16MB"
1

/opt/software/ openGauss/clusterconfig.xml为openGauss配置文件的路径。在执行过程中，用户需根据提示输入数据库管理员omm用户的密码，密码具有一定的复杂度，为保证用户正常使用该数据库，请记住输入的密码。
按照设置密码要求，比如设置密码为GaussDB@123（建议用户自定义设置密码）：

encrypt cipher and rand files for database.
Please enter password for database:       --说明：此处输入密码时，屏幕上不会有任何反馈
Please repeat for database:               --说明：此处输入密码时，屏幕上不会有任何反馈
begin to create CA cert files
1
2
3
4

设置的密码要符合复杂度要求：

• 最少包含8个字符；
• 不能和用户名和当前密码（ALTER）相同，或和当前密码反序；
• 至少包含大写字母（A-Z），小写字母（a-z），数字，非字母数字字符（限定为~!@#$%^&*()-_=+|[{}];:,<.>/?）四类字符中的三类字符。
  如果安装成功，显示如下：

……
Successfully deleted instances from all nodes.
Checking node configuration on all nodes.
Initializing instances on all nodes.
Updating instance configuration on all nodes.
Check consistence of memCheck and coresCheck on database nodes.
Configuring pg_hba on all nodes.
Configuration is completed.
Successfully started cluster.
Successfully installed application.
end deploy..
1
2
3
4
5
6
7
8
9
10
11

安装生成的目录

安装后的目录及各目录下的文件说明请参见下表。

登录数据库验证结果

步骤 1 在数据库主节点服务器上，如果当前不在omm用户环境下，请如下命令切换至omm操作系统用户环境（可选操作）。

[root@ecs-5045 script]# su - omm 
1

步骤 2启动数据库服务（可选操作，安装完毕后默认启动，如未启动，请按此步骤启动）。
启动服务命令：

[omm@ecs-504 ~]$ gs_om -t start
Starting cluster.
=========================================
Successfully started.
1
2
3
4

查看服务是否启动：

[omm@ecs-504 ~]$ gs_om -t status
-----------------------------------------------------------------------
cluster_name    : dbCluster
cluster_state   : Normal
redistributing  : No
-----------------------------------------------------------------------
1
2
3
4
5
6

步骤 3连接数据库。

[omm@ecs-504 ~]$ gsql -d postgres -p 26000 -r 
1

当结果显示为如下信息，则表示连接成功。

gsql ((openGauss 2.0.0 build 38463266) compiled at 2021-04-16 16:11:37 commit 0 last mr  )
Non-SSL connection (SSL connection is recommended when requiring high-security)
Type "help" for help. 
postgres=# 
1
2
3
4

其中，postgres为openGauss安装完成后默认生成的数据库。初始可以连接到此数据库进行新数据库的创建。26000为数据库主节点的端口号，需根据openGauss的实际情况做替换，请确认连接信息获取。

• 说明：
  gsql是openGauss数据库提供的命令行方式的数据库连接工具。

步骤 4 验证第3 章中开发的gauss_hello函数是否新增成功。

postgres=# select gauss_hello('openGauss User');
1

成功显示如下：

gauss_hello
----------------------------------------
Hello, openGauss User
1
2
3

本实验结束。