Deploy OceanBase Database using systemd

This topic describes how to deploy and manage a single-node OceanBase Database instance by using systemd.

Prerequisites

Before you perform the operations in this topic, confirm the following information:

• You are using an RPM-based platform system. The following systems have been verified to be supported:

  • Anolis OS 8.X (Linux kernel version 4.19 or later)

  • CentOS Linux 8.X (Linux kernel version 4.19 or later)

  • Debian 10, 11, and 12 (Linux kernel version 4.19 or later)

  • openEuler 22.03 and 24.03 (Linux kernel version 5.10.0 or later)

  • Ubuntu 18.04, 20.04, and 22.04 (Linux kernel version 4.19 or later)

• The available memory in the current environment is greater than 3 GB.

• The jq command-line tool is installed in your environment, and systemd is correctly configured as the system and service manager.

• A database connection tool (MySQL client or OBClient client) is installed in your environment.

• The OceanBase Database you plan to deploy is V4.2.2 or later.

• The user you are using has the permission to execute the sudo command.

Deploy OceanBase Database

Step 1: Install OceanBase Database

Based on whether the environment can connect to the external network, there are two installation methods: online installation and offline installation.

Step 2: Start OceanBase Database

After installing OceanBase Database, you can start it by following these steps.

1. (Optional) Modify the configuration file

   You can modify the configuration file as described in this step. If you do not modify it, the deployment will use the default configurations from the file.

   [admin@test001 ~]$ sudo vim /etc/oceanbase.cnf
   

   The file contains the following parameters:

   ip=127.0.0.1
   mysql_port=2881
   rpc_port=2882
   obshell_port=2886
   root_pwd=""
   redo_dir=/var/lib/oceanbase/redo
   data_dir=/var/lib/oceanbase/data
   datafile_size=2G
   cpu_count=16
   memory_limit=6G
   system_memory=1G
   log_disk_size=13G
   

   Note

   • You can add other parameters to this configuration file. For detailed descriptions of the parameters, see Overview of configuration items.

   • The zone of an OBServer node (default is zone1) cannot be modified.

   The following table describes the parameters in the configuration file.

   Parameter	Required	Default value	Description
   ip	Optional	127.0.0.1	The IP address of the OBServer node. IPv6 addresses are not currently supported.
   mysql_port	Optional	2881	The port number for the OceanBase Database SQL service protocol.
   rpc_port	Optional	2882	The port number for the OceanBase Database remote access protocol.
   obshell_port	Optional	2886	The port for OceanBase Database O&M.
   root_pwd	Optional	Empty by default	The password for the super administrator (root@sys) of the OceanBase cluster. It is recommended to set a complex password.
   redo_dir	Optional	/var/lib/oceanbase/redo	The directory for clogs, ilogs, and logs. It is recommended to configure it on a separate disk. Note The available disk space on the data disk (default is /var/lib/oceanbase/) should be greater than 15 GB.
   data_dir	Optional	/var/lib/oceanbase/data	The directory for storing data such as SSTables. It is recommended to configure it on a separate disk. Note The available disk space on the data disk (default is /var/lib/oceanbase/) should be greater than 15 GB.
   datafile_size	Optional	0	Specifies the size of the data file (block_file) for the corresponding node. If not configured, the datafile_disk_percentage parameter takes effect. For details, see datafile_size and datafile_disk_percentage.
   cpu_count	Optional	0	The total number of CPUs available for OceanBase Database. If set to 0, the number is automatically detected.
   memory_limit	Optional	0	The maximum memory that the observer process can obtain from the environment. If not configured, the memory_limit_percentage parameter takes effect. For details, see memory_limit and memory_limit_percentage.
   system_memory	Optional	0M	The reserved system memory. This parameter value consumes memory from memory_limit. If not configured, OceanBase Database adapts automatically.
   log_disk_size	Optional	0	Sets the size of the disk for redo logs. If not configured, the log_disk_percentage parameter takes effect. For details, see log_disk_size and log_disk_percentage.

2. Change the owner of the etc directory in the OceanBase installation directory (default is /home/admin/oceanbase)

   [admin@test001 ~]$ sudo chown root /home/admin/oceanbase/etc
   

3. Start OceanBase Database.

   [admin@test001 ~]$ sudo systemctl start oceanbase
   

4. Check the startup status of OceanBase Database.

   [admin@test001 ~]$ sudo systemctl status oceanbase
   

   When the status shows Service is ready, it indicates that OceanBase Database has started normally.

Step 3: Connect to OceanBase Database

This example shows how to connect to OceanBase Database using OBClient. The command is as follows:

[admin@test001 ~]$ obclient -h<IP> -uroot@sys -P<Port> -p<Passwd> -A oceanbase

Parameter description:

• -h: Specifies the IP address for connecting to OceanBase Database. For an OceanBase Database instance started by using systemd, the default IP address is 127.0.0.1.

• -u: Specifies the account for connecting to OceanBase Database in the format username@tenant_name. The default administrator username for a MySQL tenant is root.

• -P: Specifies the port for connecting to OceanBase Database, which is the value of mysqlPort in the /etc/oceanbase.cnf file.

• -p: Specifies the password for connecting to OceanBase Database, which is the value of rootPwd in the /etc/oceanbase.cnf file. It is recommended not to specify this option in the connection command. Instead, enter the password after the command is executed. The password text will be invisible.

• -A: Indicates that statistical information will not be automatically retrieved when OBClient connects to the database.

• oceanbase: The name of the database to access. You can change it to the name of your business database.

Manage OceanBase Database

Currently, only starting (start), stopping (stop), and checking the status (status) of OceanBase Database are supported using systemd.

Check the status of OceanBase Database

You can run the following command to check the status of OceanBase Database.

[admin@test001 ~]$ sudo systemctl status oceanbase

The status of OceanBase Database can be as follows:

• If Active is displayed as active (running) and Status is displayed as Service is running, it means OceanBase Database is starting.

• If Active is displayed as active (running) and Status is displayed as Service is ready, it means OceanBase Database has been successfully started.

• If Active is displayed as inactive (dead), it means the service has stopped, i.e., OceanBase Database has stopped.

• If Active is displayed as failed, it means an error has occurred in the service. You need to check the logs for troubleshooting.

View detailed logs of OceanBase Database

When an exception occurs in the status of OceanBase Database, you can run the following command to view detailed information of OceanBase Database.

[admin@test001 ~]$ sudo journalctl -u oceanbase

Systemd actually communicates with the management tool obshell of OceanBase Database by sending requests, thereby actually controlling the status of OBServer nodes. In the logs, you can see many trace IDs. You can use the interface of obshell and the trace IDs to debug. The command is as follows:

[admin@test001 ~]$ curl -X GET http://<ip>:<obshell_port>/api/v1/task/dag/<trace id> | jq

If an error occurs during the observer start or bootstrap phase, you also need to check the logs of the OBServer node. The default directory is /home/admin/oceanbase/log.

FAQ

• ERROR: current user(uid=0) that starts observer is not the same with the original one(uid=500)

  A common cause of this error is that the ownership of the etc directory under the installation directory of OceanBase Database (default is /home/admin/oceanbase) does not match the current user. You can run the following command to resolve it:

  chown root /home/admin/oceanbase/etc
  

• errcode=-4290, file="ob_server_log_block_mgr.cpp", line_no=1127, info="::fallocate failed"

  A common cause of this error is insufficient disk space in the data disk directory of OceanBase Database (default is /var/lib/oceanbase/). You can increase the disk space of the data directory.

Stop OceanBase Database

You can follow these steps to stop OceanBase Database started by systemd.

1. Stop OceanBase Database

   [admin@test001 ~]$ sudo systemctl stop oceanbase
   

2. Uninstall OceanBase Database

   1. Remove the OceanBase Database package.

      For online installation, run the following command:

      [admin@test001 ~]$ sudo yum erase package 
      

      Replace package with the name of the package to be removed. You can view the package name by running the yum list | grep oceanbase command.

      For offline installation, run the following command:

      [admin@test001 ~]$ sudo rpm -e package
      

      Replace package with the name of the package to be removed. You can view the package name by running the rpm -qa | grep oceanbase command.

   2. (Optional) Delete the data from OceanBase Database.

      After you perform the first step, OceanBase Database is uninstalled from your environment, but its data remains. If you redeploy OceanBase Database later, you can still view and operate this data.

      After you perform this step to delete the data from OceanBase Database, the deployed OceanBase Database will be completely uninstalled.

      Delete the OceanBase Database installation directory.

      [admin@test001 ~]$ sudo rm -rf /home/admin/oceanbase 
      

      Delete the OceanBase Database data directory.

      [admin@test001 ~]$ sudo rm -rf /var/lib/oceanbase 
      

References

• You can log in to the cluster and execute the ALTER USER statement to change the user password. For more information about this statement, see ALTER USER.

• After you deploy OceanBase Database, for more information about how to connect to it, see Connect to OceanBase Database.