UWAL

Introduction

This chapter describes how to install and use the Unified Write-Ahead Log (UWAL) feature of the openGauss database. This feature combines the database and a Huawei-developed UWAL component to improve the performance of active/standby transaction submission as well as streaming replication and transmission, accelerating the Write-Ahead Log (WAL) processing efficiency.

Preparations

Obtaining the Installation Package

Obtain the UWAL installation package from the openGauss community.

Environment Requirements

Installation and Uninstallation

One-Click Deployment of the UWAL Feature

UWAL allows one-click deployment through a simple deployment script.

• Prerequisites

  • openGauss has been deployed.
  • Obtain the UWAL installation package corresponding to the OS and CPU architecture in use, for example, OCK_UWAL_23.0.0_openeuler_22.03-aarch64_gcc10.tar.gz.
  • The following directories exist on both the active and standby nodes:
    • ${GAUSSHOME}/lib
    • UWAL file storage path (value of uwal_devices_path)
    • UWAL log file storage path (value of uwal_log_path)

• Procedure

  NOTE: Unless otherwise specified, perform the following operations only on the active node.

  1. Upload the installation package to the node and run the following command in the directory where the installation package is stored to grant permissions to the openGauss database user:

     chown omm:dbgrp OCK_UWAL_23.0.0_openeuler_22.03-aarch64_gcc10.tar.gz
     

     NOTE:

     • omm: database administrator
     • dbgrp: user group of the database administrator

  2. Switch to the openGauss database administrator and decompress the installation package.

     su - omm
     tar -xzvf OCK_UWAL_23.0.0_openeuler_22.03-aarch64_gcc10.tar.gz
     

     The following files are extracted.

     File	Description
     OCK_UWAL_23.0.0_openeuler_aarch64.tar.gz	Source package
     OCK_UWAL_23.0.0_openeuler_aarch64.tar.gz.txt	Signature file
     OCK_UWAL_23.0.0_openeuler_aarch64.tar.gz.cms	Description file

  3. Decompress the source package.

     tar -xzvf OCK_UWAL_23.0.0_openeuler_22.03_aarch64_gcc10.tar.gz
     

     The following files are extracted.

     File	Description
     lib	SO file
     scripts	Installation script
     include	UWAL header file
     bin	Signature verification file

     NOTE: To decompress the source package again, delete the preceding files before performing decompression operations.

  4. Use the verification binary file in the bin directory to verify the software package signature.

     ./bin/verification OCK_UWAL_23.0.0_openeuler_22.03_aarch64_gcc10.tar.gz OCK_UWAL_23.0.0_openeuler_22.03_aarch64_gcc10.tar.gz.cms OCK_UWAL_23.0.0_openeuler_22.03_aarch64_gcc10.tar.gz.txt
     

     NOTE: The verification binary file requires three parameters in sequence: source package, signature file, and description file.

     • If the verification is successful, the console displays the following information:

       Starting to verify OCK_UWAL_23.0.0_openeuler_22.03_aarch64_gcc10.tar.gz...
       Verify the source file passed.
       Verify the sha file passed.
       

     • If the verification fails, the console displays the following information:

       Starting to verify OCK_UWAL_23.0.0_openeuler_22.03_aarch64_gcc10.tar.gz...
       ...
       Verify the source file failed.
       

       Or

       Starting to verify OCK_UWAL_23.0.0_openeuler_22.03_aarch64_gcc10.tar.gz...
       ...
       Verify the sha file failed.
       

       NOTE: If the verification fails, the installation package has been tampered with. You are advised to obtain the installation package again and verify it again.

  5. After the installation package is verified, go to the scripts directory.

     cd scripts
     

  6. Run the script to complete the UWAL deployment.

     sh ock_uwal_install.sh -H '192.168.4.164 192.168.4.165 192.168.4.166' -U omm -D /home/omm/lib
     

     NOTE:

     • -H: IP addresses in the cluster. Example: '192.168.4.164 192.168.4.165 192.168.4.166'
     • -U: user name of the database administrator. Example: omm
     • -D: path to the ${GAUSSHOME}/lib library. Example: /home/omm/lib
     • -h: help information.

  7. (Optional) Kill the om_monitor process.

     gs_om -t killmonitor
     

  8. Run the following command to load environment variables:

     source ~/.bashrc
     

     NOTICE: This step is also required on the standby node.

  9. (Optional) The UWAL component depends on the HCOM component for RPC communication. Configure the following environment variables as required.

     export HCOM_FILE_PATH_PREFIX="/home/uds/socket/file"
     export HCOM_OPENSSL_PATH="/home/openssl"
     export HCOM_TRACE_LEVEL=0
     export HCOM_QP_TRAFFIC_CLASS=106
     export HCOM_SHM_EXCHANGE_FD_QUEUE_SIZE=10
     export HCOM_CONNECTION_RETRY_TIMES=5
     export HCOM_CONNECTION_RETRY_INTERVAL_SEC=2
     

     The following table describes the parameters.

     Parameter	Type	Description	Value Range	Default Value
     HCOM_FILE_PATH_PREFIX	Character string	Prefix of the path to files generated by HCOM. The prefix ensures that the files are generated and deleted only in the current path (the path must exist).	-	-
     HCOM_OPENSSL_PATH	Character string	Path to the OpenSSL library on which HCOM depends. This path is the directory of libssl.so and libcrypt.so.	-	-
     HCOM_TRACE_LEVEL	Integer	HCOM trace level. The options are as follows: 0: Disables tracing. 1: Enables high-priority tracing. 2: Enables medium-priority tracing. 3: Enables low-priority tracing.	0–3	0
     HCOM_QP_TRAFFIC_CLASS	Integer	Set the priority of the traffic_class field of the RDMA protocol in HCOM.	0–255	106
     HCOM_SHM_EXCHANGE_FD_QUEUE_SIZE	Integer	Size of the FDS internal queue sent by HCOM.	10–256	10
     HCOM_CONNECTION_RETRY_TIMES	Integer	Number of HCOM connection setup retries.	0–10	5
     HCOM_CONNECTION_RETRY_INTERVAL_SEC	Integer	Interval between each HCOM connection setup retry, in seconds.	0–60	20

Enabling the UWAL Feature

To enable the UWAL feature, modify the configuration file and restart the database for the modification to take effect.

NOTICE: Once the UWAL feature is enabled, it cannot be disabled.

• Prerequisites

  • The openGauss version that contains the UWAL feature has been installed on the active and standby nodes.
  • The UWAL feature has been deployed in one-click mode.

• Procedure

  1. Log in to the management node as the database administrator.

  2. Modify the postgresql.conf file of the database.

     1. Open the postgresql.conf file.

        vim postgresql.conf
        

     2. Press i to enter the insert mode and add the following parameters to the end of the file. One active node and one standby node are used as an example. Set the parameters based on the actual environment. For details about the parameters, see Table 1.

        replconninfo1='localhost=10.10.10.201 localport=5432 remotehost=10.10.10.207 remoteport=5432 remotenodeid=2 remoteuwalhost=10.10.10.207 remoteuwalport=9991'
        enable_uwal = on
        uwal_config = '{"uwal_nodeid": 0, "uwal_ip": "10.10.10.201", "uwal_port": 9991, "uwal_protocol": "tcp", "cpu_bind_switch": "true", "cpu_bind_start": 1, "cpu_bind_num": 3}'
        uwal_disk_size = 8589934592
        uwal_devices_path = '/home/Data/uwal/'
        uwal_log_path = '/home/Data/opengauss_master/uwal_log'
        uwal_rpc_compression_switch = true
        uwal_rpc_flowcontrol_switch = true
        uwal_rpc_flowcontrol_value = 128
        uwal_async_append_switch = false
        application_name = 'node201'
        

        NOTE:

        • If there are one active node and two standby nodes, add the replconninfo2 parameter to the next line of the replconninfo1 parameter. For example:

        replconninfo2='localhost=10.10.10.201 localport=5432 remotehost=10.10.10.208 remoteport=5432 remotenodeid=2 remoteuwalhost=10.10.10.208 remoteuwalport=9991'
        

        • If there are one active node and N standby nodes, add parameters replconninfo2 to replconninfoN in sequence.

        Table 1 UWAL configuration parameters

        Parameter	Type	Description	Value Range	Default Value
        replconninfo{N}	Character string	Configures the IP address and port number of the remote UWAL node. Add remotenodeid (uwal_nodeid of the remote node), remoteuwalhost (uwal_ip of the remote node), and remoteuwalport (uwal_port of the remote node) to the end of the original parameters. N specifies the information about the Nth node to be listened on and authenticated by the current node.	Character string. An empty string indicates that no information about the Nth node is configured.	Empty string
        enable_uwal	Boolean	Specifies whether to enable the UWAL feature.	on: enable. off: disable.	off
        uwal_config	Character string	UWAL configuration.	Character string of the JSON type.	Empty string
        uwal_disk_size	Integer	Disk size occupied by UWAL. The value cannot exceed the total disk size. Unit: byte.	Minimum value: 8589934592 Maximum value: 4398046511104	8589934592
        uwal_devices_path	Character string	Path for storing UWAL files. The path must be an existing path. It is the input parameter name when the UwalInit() function is invoked.	Character string of the file storage path.	Empty string
        uwal_log_path	Character string	Path for storing UWAL log files. The path must be an existing path.	Character string of the file storage path.	Empty string
        uwal_rpc_compression_switch	Boolean	Specifies whether to enable compressed transfer.	true: enable. false: disable.	false
        uwal_rpc_flowcontrol_switch	Boolean	Specifies whether to enable flow control for the asynchronous standby database. This parameter is set on the active database.	on: enable. off: disable.	off
        uwal_rpc_flowcontrol_value	Integer	Flow control threshold of the asynchronous standby database. Unit: MB.	8–2048	128
        uwal_async_append_switch	Boolean	Specifies whether UWAL uses synchronous write or asynchronous write.	true: Asynchronous write is used. false: Synchronous write is used.	false
        application_name	Character string	Specifies the client name used in the current connection request.	Any character string.	Empty string

        Table 2 uwal_config parameters

        Parameter	Type	Description	Value Range	Default Value
        uwal_nodeid	Integer	ID of the current UWAL node.	0–7	None
        uwal_ip	Character string	UWAL listening address, which is the input parameter name when the UwalInit() function is invoked.	IPv4	Empty string
        uwal_port	Integer	UWAL listening port, which is the input parameter name when the UwalInit() function is invoked.	9000–65535	None
        uwal_protocol	Character string	(Optional) Connection protocol of the current node, which is the input parameter name when the UwalInit() function is invoked.	tcp rdma	tcp
        cpu_bind_switch	Character string	(Optional) Specifies whether to enable core binding for UWAL core threads.	true: enable. false: disable.	false
        cpu_bind_start	Integer	(Optional) Start CPU core used for UWAL core binding.	0–1024	1
        cpu_bind_num	Integer	(Optional) Number of CPU cores bound to UWAL.	2–16	3

     3. Press Esc, type :wq!, and press Enter to save the file and exit.

  3. Restart the database to enable the UWAL feature.

     1. Stop openGauss.

        cm_ctl stop
        

     2. Start openGauss.

        cm_ctl start
        

        NOTE: If the startup fails, rectify the fault based on the postgresql-YYYY-MM-DD_HHMMSS.log file in the openGauss log directory.

  4. Verify that the UWAL feature is successfully enabled.

     gsql -d postgres -p 16600 -c "show enable_uwal"
     

     If the following information is displayed, the feature is enabled successfully:

     enable_uwal
     -------------------
     on
     (1 row)
     

     NOTE:

     • -p 16600: 16600 indicates the database port number. Change it based on the actual environment.
     • To view UWAL log files, go to the path specified by uwal_log_path and run the following command:

     cat uwal*.log