Deploy a single-replica OceanBase cluster using the CLI

OceanBase Database can be deployed with a single replica. A single-replica OceanBase cluster can also be scaled out (by adding nodes) and therefore it is also referred to as a standalone cluster.

This topic will guide you through the process of deploying a single-replica OceanBase cluster using the CLI.

Prerequisites

Before installing OceanBase Database, make sure that the following conditions are met:

• The OBServer node has been configured. For more information, see Server configuration and Initialize the OBServer node using oat-cli.

• You have obtained the RPM package of OceanBase Database. For more information, see Prepare the installation packages.

Procedure

Step 1: Install the RPM package

1. Install the OceanBase Database RPM package.

   In this example, $rpm_dir indicates the directory where the RPM package is stored, and $rpm_name indicates the name of the RPM package.

   [root@xxx /]# cd $rpm_dir
   [root@xxx $rpm_dir]# rpm -ivh $rpm_name
   

   Note

   OceanBase Database will be installed in the /home/admin/oceanbase directory.

   Here is an example:

   [root@xxx /home/admin/rpm]# rpm -ivh oceanbase-4.2.0.0-100000052023073123.el7.x86_64.rpm
   Preparing...                          ################################# [100%]
   Updating / installing...
      1:oceanbase-4.2.0.0-100000052023073################################# [100%]
   

2. Install OceanBase Client.

   An OceanBase instance is compatible with Oracle or MySQL. If an Oracle tenant is created, a Java application needs to connect to the tenant using the Java driver file (oceanbase-client-*.jar) provided by OceanBase. If you want to access an Oracle tenant from the command line, you also need to install OBClient.

   OBClient is an OceanBase command-line client that can access MySQL and Oracle tenants of OceanBase.

   Here is an example:

   [root@xxx $rpm_dir]# rpm -ivh obclient-1.2.6-20210510164331.el7.alios7.x86_64.rpm
   
   ##Check whether OBClient has been installed.##
   [root@xxx $rpm_dir]# which obclient
   /usr/bin/obclient
   

Step 2: Configure directories

1. Clear the OceanBase directory (if it has been deployed).

   If you want to clear the previous OceanBase environment or the environment is messy or contains files that will affect the next installation due to errors during OceanBase installation and deployment, you can choose to clear the old OceanBase directory. In this case, you must specify the cluster name $cluster_name.

   [root@xxx admin]# su - admin
   -bash-4.2$ kill -9 `pidof observer` 
   -bash-4.2$ rm -rf /data/1/$cluster_name 
   -bash-4.2$ rm -rf /data/log1/$cluster_name 
   -bash-4.2$ rm -rf /home/admin/oceanbase/store/$cluster_name /home/admin/oceanbase/log/* /home/admin/oceanbase/etc/*config*
   -bash-4.2$ ps -ef|grep observer
   

   Here is an example:

   [root@xxx admin]# su - admin
   -bash-4.2$ kill -9 `pidof observer` 
   -bash-4.2$ rm -rf /data/1/obdemo 
   -bash-4.2$ rm -rf /data/log1/obdemo 
   -bash-4.2$ rm -rf /home/admin/oceanbase/store/obdemo /home/admin/oceanbase/log/* /home/admin/oceanbase/etc/*config*
   -bash-4.2$ ps -ef|grep observer
   

2. Initialize the OceanBase directory.

   We recommend that you install the data directory of OceanBase on an independent disk and then link it to the software home directory through a soft link. In this way, you can effectively improve the performance of your database and shorten the response time of your applications. In this case, you must specify the cluster name $cluster_name.

   Note

   Starting from V4.3.0, OceanBase Database allows you to separate the slog from the data (data) disk. In other words, the slog and data files do not need to be on the same disk. You can configure the disks to share an SSD for slog and clog. For more information about the installation directories of OceanBase Database, see OBServer node installation directory structure.

   [root@xxx admin]# su - admin
   -bash-4.2$ mkdir -p /data/1/$cluster_name/{etc3,sstable,slog} 
   -bash-4.2$ mkdir -p /data/log1/$cluster_name/{clog,etc2} 
   -bash-4.2$ mkdir -p /home/admin/oceanbase/store/$cluster_name
   -bash-4.2$ for t in {etc3,sstable,slog};do ln -s /data/1/$cluster_name/$t /home/admin/oceanbase/store/$cluster_name/$t; done
   -bash-4.2$ for t in {clog,etc2};do ln -s /data/log1/$cluster_name/$t /home/admin/oceanbase/store/$cluster_name/$t; done
   

   Here is an example:

   [root@xxx admin]# su - admin
   -bash-4.2$ mkdir -p /data/1/obdemo/{etc3,sstable,slog} 
   -bash-4.2$ mkdir -p /data/log1/obdemo/{clog,etc2} 
   -bash-4.2$ mkdir -p /home/admin/oceanbase/store/obdemo
   -bash-4.2$ for t in {etc3,sstable,slog};do ln -s /data/1/obdemo/$t /home/admin/oceanbase/store/obdemo/$t; done
   -bash-4.2$ for t in {clog,etc2};do ln -s /data/log1/obdemo/$t /home/admin/oceanbase/store/obdemo/$t; done
   

   Note

   The obdemo directory is created based on the cluster name and can be customized. It is used by the startup process.

   The check result is as follows:

   -bash-4.2$ cd /home/admin/oceanbase
   -bash-4.2$ tree store/
   store/
   `-- obdemo
    |-- clog -> /data/log1/obdemo/clog
    |-- etc2 -> /data/log1/obdemo/etc2
    |-- etc3 -> /data/1/obdemo/etc3
    |-- slog -> /data/1/obdemo/slog
    `-- sstable -> /data/1/obdemo/sstable
   
   6 directories, 0 files
   

Step 3: Initialize the OceanBase cluster

1. Start the observer process.

   Notice

   You must start the observer process as the admin user.

   OceanBase Database allows you to start the observer process with either an IPv4 or an IPv6 address.

   Start the observer process with an IPv4 address:

   cd /home/admin/oceanbase && /home/admin/oceanbase/bin/observer {-I $ip | -i $devname} -P $rpc_port -p $sql_port -z $zone_name -d /home/admin/oceanbase/store/$cluster_name -r '$ip:2882:2881' -c $cluster_id -n $cluster_name -o "system_memory=30G,datafile_size=500G,config_additional_dir=/data/1/$cluster_name/etc3;/data/log1/$cluster_name/etc2"
   

   Start the observer process with an IPv6 address:

   cd /home/admin/oceanbase && /home/admin/oceanbase/bin/observer -6 {-I $ip | -i $devname} -P $rpc_port -p $sql_port -z $zone_name -d /home/admin/oceanbase/store/$cluster_name -r '[$ip]:2882:2881' -c $cluster_id -n $cluster_name -o "system_memory=30G,datafile_size=500G,config_additional_dir=/data/1/$cluster_name/etc3;/data/log1/$cluster_name/etc2"
   

   The parameters are described as follows:

   Parameter	Description
   -6	If you start the observer process with an IPv6 address, you must specify -6.
   -I | -i	-I: the IP address of the node to be started. In a multi-server deployment scenario, you cannot specify 127.0.0.1 as the target IP address. We recommend that you specify the IP address (-I 10.10.10.1) to start the node. -i: the name of the network interface card. You can use the ifconfig command to view the network interface card names. Note You can also specify both the IP address and the network interface card name (-I 10.10.10.1 -i eth0) to start the node, but we do not recommend that you do so.
   -p	the service port number, which is generally set to 2881.
   -P	the RPC port number, which is generally set to 2882.
   -n	the cluster name. Custom cluster names must not be repeated.
   -z	the zone to which the started observer process belongs.
   -d	the directory where the cluster is located. The directory is created when the cluster is initialized. Except for the cluster name $cluster_name, other parameters must not be changed.
   -c	the cluster ID. It is a group of numbers, and custom cluster IDs must not be repeated.
   -l	the log level.
   -r	the list of Root Service nodes in the format of $ip:2882:2881. The list is separated by semicolons. Notice When you start the observer process with an IPv6 address, you must wrap the IP address with [].
   -o	Specifies the list of cluster startup parameters (configuration items), which is optional. You can specify values for multiple configuration items, with values separated by commas. Based on actual needs, select appropriate startup parameters and assign suitable values to each parameter to optimize cluster performance and resource utilization. Below are some commonly used cluster startup configuration items: cpu_count: Sets the total number of CPUs in the system. system_memory: Sets the memory capacity reserved for the tenant with ID 500, i.e., specifies the internal reserved memory of the OceanBase database. In cases where machine memory is limited, consider reducing this value, but note that insufficient memory issues may occur during performance testing. memory_limit: Sets the total available memory size. datafile_size: Sets the disk space occupied by data files. This specifies the size of the OceanBase database data file sstable (initialized once). Based on the available space in /data/1/, it is recommended to set it to no less than 100G. datafile_disk_percentage: The percentage of disk space occupied by disk data files out of the total disk space. datafile_next: Sets the step size for automatic expansion of disk data files. datafile_maxsize: Sets the maximum space for automatic expansion of disk data files. config_additional_dir: Sets multiple directories for storing local configuration files for redundancy purposes. log_disk_size: Sets the size of the Redo log disk. log_disk_percentage: Sets the percentage of disk space occupied by Redo logs out of the total disk space. syslog_level: Sets the system log level. syslog_io_bandwidth_limit: Sets the upper limit of disk IO bandwidth that system logs can occupy; system logs exceeding this bandwidth will be discarded. max_syslog_file_count: Sets the number of log files that can be accommodated before log file recycling begins. enable_syslog_recycle: Sets whether to enable the switch for recording old logs prior to OBServer node startup. Used in conjunction with max_syslog_file_count, it determines whether the recycling logic considers old log files. The configuration items datafile_size, datafile_disk_percentage, datafile_next, and datafile_maxsize work together to achieve automatic expansion of disk data files. For more details, see Configuring Dynamic Expansion of Disk Data Files. For more information on cluster configurations, see Overview of Configuration Items - Cluster-Level Configuration Items.

   Here is an example of how to start the observer process with an IPv4 address:

   [root@xxx /home/admin]# su - admin
   -bash-4.2$ cd /home/admin/oceanbase && /home/admin/oceanbase/bin/observer -I 10.10.10.1 -P 2882 -p 2881 -z zone1 -d /home/admin/oceanbase/store/obdemo -r '10.10.10.1:2882:2881' -c 10001 -n obdemo -o "system_memory=30G,datafile_size=500G,config_additional_dir=/data/1/obdemo/etc3;/data/log1/obdemo/etc2"
   

   Run the following command to check whether the observer process has started successfully:

   • Use the netstat -ntlp command to check whether the observer process is listening on the 2881 and 2882 ports. If yes, the observer process has started successfully.
   • Use the ps -ef|grep observer command to return the information about the observer process.

   Here is an example:

   -bash-4.2$ netstat -ntlp
   (Not all processes could be identified, non-owned process info
   will not be shown, you would have to be root to see it all.)
   Active Internet connections (only servers)
   Proto Recv-Q Send-Q Local Address           Foreign Address         State       PID/Program name
   tcp        0      0 0.0.0.0:2881            0.0.0.0:*               LISTEN      11111/observer
   tcp        0      0 0.0.0.0:2882            0.0.0.0:*               LISTEN      11111/observer
   ...        ...    ...                       ...                     ...         ...
   
   -bash-4.2$ ps -ef|grep observer
   admin    11111      0 43 17:58 ?        00:00:14 /home/admin/oceanbase/bin/observer -I 10.10.10.1 -P 2882 -p 2881 -z zone1 -d /home/admin/oceanbase/store/obdemo -r 10.10.10.1:2882:2881 -c 10001 -n obdemo -o system_memory=30G,datafile_size=500G,config_additional_dir=/data/1/obdemo/etc3;/data/log1/obdemo/etc2
   

   Here is an example of how to start the observer process with an IPv6 address:

   [root@xxx /home/admin]# su - admin
   

   
   -bash-4.2$ cd /home/admin/oceanbase && /home/admin/oceanbase/bin/observer -6 -I xxxx:xxxx:xxxx:xxxx:xxx:xxxx:xxxx:ebd8 -P 2882 -p 2881 -z zone1 -d /home/admin/oceanbase/store/obdemo -r '[xxxx:xxxx:xxxx:xxxx:xxx:xxxx:xxxx:ebd8]:2882:2881' -c 10001 -n obdemo -o "system_memory=30G,datafile_size=500G,config_additional_dir=/data/1/obdemo/etc3;/data/log1/obdemo/etc2"
   

2. Perform the bootstrap operation to initialize the cluster.

   1. Use the OBClient client to connect to the started observer process. The password is empty.

      [root@xxx /home/admin]# obclient -h127.0.0.1 -uroot -P2881 -p******
      

   2. Set the maximum execution time for SQL queries.

      obclient [(none)]> SET SESSION ob_query_timeout=1000000000;
      

   3. Specify the list of Root Service nodes and start the cluster.

      • Specify the list of Root Service nodes by using their IPv4 addresses and start the cluster.

        obclient [(none)]> ALTER SYSTEM BOOTSTRAP ZONE 'zone1' SERVER '10.10.10.1:2882';
        

      • Specify the list of Root Service nodes by using their IPv6 addresses and start the cluster.

        obclient [(none)]> ALTER SYSTEM BOOTSTRAP ZONE 'zone1' SERVER '[xxxx:xxxx:xxxx:xxxx:xxx:xxxx:xxxx:ebd8]:2882';
        

   Notice

   If this step fails, check whether the observer process startup parameters are correctly specified, whether the directory permissions for the OBServer node are correct, whether the log directory has sufficient space (if the data directory and the log directory are in the same large directory, the data directory occupies the log directory's space), and whether the node has sufficient memory resources. If the problem persists, clear the OceanBase directory and start over.

3. Verify that the cluster has been initialized.

   After the cluster is initialized, execute the SHOW DATABASES; command to verify that the oceanbase database is listed in the query result. If yes, the cluster has been initialized successfully.

4. Change the password.

   The password of the root user in the sys tenant is empty by default. Change the password after the initialization.

   ALTER USER root IDENTIFIED BY '******';
   

Next steps

After the cluster is created, you can create user tenants as needed.

For more information about how to create a user tenant using the CLI, see Create a tenant.

References

• Connect to an OceanBase tenant by using OBClient
• Overview of system configuration items
• ALTER USER
• Introduction to user tenants
• CREATE TENANT