This topic describes the cluster commands of OceanBase Shell (OBShell). You can use the cluster commands of OBShell to deploy and manage OceanBase clusters in a production environment.
You can specify the -h or --help option in a command to query its help information. When a task returns an error, you can specify the -v or --verbose option to query the execution details of the command.
obshell cluster join
You can run this command to add the OBServer node where OBShell is stored to an OceanBase cluster before the OceanBase cluster is initialized.
${home_path}/bin/obshell cluster join -z -s [-d] [-r] [-p] [-P] [-o] [-l]
# example
/home/admin/oceanbase/bin/obshell cluster join -z zone1 -s 10.10.10.1
Here, home_path is the installation directory of OceanBase Database. By default, OBShell is installed in the bin directory under the installation directory of OceanBase Database.
The following table describes the options in the command.
| Option | Required? | Data type | Default value | Description |
|---|---|---|---|---|
| -z/--zone | Yes | String | N/A | The zone to which the OBServer node belongs. |
| -s/--server | Yes | String | N/A | The IP address and port number of the OBServer node that you want to add, in the ip:port format. The port number is optional. By default, port 2886 is used. |
| -d/--data_dir | No | String | ${home_path}/store | The directory for storing SSTables and other data, which must be an absolute path. By default, the store directory under the working directory is used. The working directory is specified by the home_path parameter. |
| -r/--redo_dir | No | String | ${data_dir} | The directory for storing clogs, which must be an absolute path. By default, the value of this option is the same as that of the --data_dir option. |
| -p/--mysql_port | No | Integer | 2881 | The port number for the SQL service protocol. By default, port 2881 is used. |
| -P/--rpc_port | No | Integer | 2882 | The protocol port number for remote access. By default, port 2882 is used. |
| -o/--opt_str | No | String | N/A | Other options for the OBServer node. You must specify each option in the key=value format, and separate multiple options with commas (,). The entire value string of the -o option must be enclosed by single quotation marks ('). Example: -o 'memory_limit=16G,system_memory=8G,log_disk_size=24G,datafile_size=24G'. |
| -l/--log_level | No | String | N/A | The log level of the OBServer node. |
obshell cluster remove
You can run this command to remove the OBServer node where OBShell is stored from an OceanBase cluster before the OceanBase cluster is initialized.
${home_path}/bin/obshell cluster remove -s [-y]
# example
/home/admin/oceanbase/bin/obshell cluster remove -s 10.10.10.1
Here, home_path is the installation directory of OceanBase Database. By default, OBShell is installed in the bin directory under the installation directory of OceanBase Database.
The following table describes the options in the command.
| Option | Required? | Data type | Default value | Description |
|---|---|---|---|---|
| -s/--server | Yes | String | N/A | The IP address and port number of the OBServer node that you want to remove, in the ip:port format. The port number is optional. By default, port 2886 is used. |
| -y/--yes | No | N/A | N/A | Specifies to cancel secondary confirmation. You do not need to set a value for this option. |
obshell cluster init
You can run this command to initialize an OceanBase cluster.
${home_path}/bin/obshell cluster init -n --rp [-i] [-d] [-r] [-p] [-P] [--rs] [-o] [-l]
# example
/home/admin/oceanbase/bin/obshell cluster init -n ob-test --rp ********
Here, home_path is the installation directory of OceanBase Database. By default, OBShell is installed in the bin directory under the installation directory of OceanBase Database.
The following table describes the options in the command.
| Option | Required? | Data type | Default value | Description |
|---|---|---|---|---|
| -n/--cluster_name | Yes | String | N/A | The name of the OceanBase cluster. |
| --rp/--rootpassword | No | String | N/A | The password for the root user of the sys tenant. |
| -i/--cluster_id | No | Integer | 1 | The ID of the OceanBase cluster. The default value is 1. |
| -d/--data_dir | No | String | ${home_path}/store | The directory for storing SSTables and other data, which must be an absolute path. By default, the store directory under the working directory is used. The working directory is specified by the home_path parameter. |
| -r/--redo_dir | No | String | ${data_dir} | The directory for storing clogs, which must be an absolute path. By default, the value of this option is the same as that of the --data_dir option. |
| -p/--mysql_port | No | Integer | 2881 | The port number for the SQL service protocol. By default, port 2881 is used. |
| -P/--rpc_port | No | Integer | 2882 | The protocol port number for remote access. By default, port 2882 is used. |
| --rs/--rs_list | No | String | N/A | The list of RootService servers, in the format of observer_ip:rpc_port:mysql_port. The information about multiple RootService servers must be separated with semicolons (;). The entire value string of the --rs option must be enclosed by single quotation marks ('). Example: --rs '10.10.10.1:2882:2881;10.10.10.2:2882:2881'. |
| -o/--opt_str | No | String | N/A | Other options for the OBServer nodes in the OceanBase cluster. You must specify each option in the key=value format, and separate multiple options with commas (,). The entire value string of the -o option must be enclosed by single quotation marks ('). Example: -o 'memory_limit=16G,system_memory=8G,log_disk_size=24G,datafile_size=24G'. |
| -l/--log_level | No | String | N/A | The log level of the OceanBase cluster. |
obshell cluster show
You can run this command to query the details of the current OceanBase cluster.
${home_path}/bin/obshell cluster show [-d]
Here, home_path is the installation directory of OceanBase Database. By default, OBShell is installed in the bin directory under the installation directory of OceanBase Database. The -d or --show_detail option is optional. It specifies to display the details of the current cluster. You do not need to set a value for this option.
If you run this command before the OceanBase cluster is initialized, the following information about OBShell is displayed: IP address, version, and port number.
If you run this command after the OceanBase cluster is initialized, the information about OBShell and the following information about each OBServer node are displayed: cluster, version, zone, SQL port number, server port number, RootService server, and status.
The status of an OBServer node is described as follows:
ACTIVE: The heartbeat connection between the OBServer node and the RootService server is normal.INACTIVE: The OBServer node lost the heartbeat connection with the RootService server.DELETING: The OBServer node is being deleted.STOPPED: The OBServer node is stopped.
obshell cluster start
You can run this command to start the specified one or more observer processes or take over the current OceanBase cluster managed by OBShell.
For more information about how to determine whether an OceanBase cluster is managed by OBShell and how to take over an OceanBase cluster, see Take over an OceanBase cluster not deployed by OBShell. For more information about the applicable scenarios of this command, see Start an OceanBase cluster.
${home_path}/bin/obshell cluster start [-a] [-s] [-z] [-i] [-y] [--ssh_user] [--ssh_port] [--user_password] [--key_file] [--key_passphrase]
# example
/home/admin/oceanbase/bin/obshell cluster start -s 10.10.10.1:2886,10.10.10.2:2886
Here, home_path is the installation directory of OceanBase Database. By default, OBShell is installed in the bin directory under the installation directory of OceanBase Database.
The following table describes the options in the command.
| Option | Required? | Data type | Default value | Description |
|---|---|---|---|---|
| -a/--all | No | N/A | N/A | Specifies to start all observer processes. You do not need to set a value for this option. By default, if you do not specify this option, only the observer processes managed by the current OBShell process are started. |
| -s/--server | No | String | N/A | The IP addresses and port numbers of the OBShell-managed observer processes to be started, in the format of obshell_ip:obshell_port. The information about multiple observer processes must be separated with commas (,). Example: -s x.x.x.x:2886,x.x.x.x:2886. |
| -z/--zone | No | String | N/A | Specifies to start all observer processes in the specified zones. The names of multiple zones must be separated with commas (,). Example: -z zone1,zone2. |
| -i/--id | No | String | N/A | The ID of the preceding task that starts or stops the specified observer processes. You can use this option in special circumstances. When a cluster O&M task is locked by one or more preceding tasks, you can specify the -i option to release the previous tasks. Example: -i 22130706433028869. |
| -y/--yes | No | N/A | N/A | Specifies to cancel secondary confirmation. You do not need to set a value for this option. |
| --ssh_user | No | String | N/A | The username to use for an SSH connection. |
| --ssh_port | No | String | N/A | The port number to use for an SSH connection. |
| --user_password | No | String | N/A | The password to use for an SSH connection. |
| --key_file | No | String | "/~/.ssh/id_rsa" | The private key file to use for an SSH connection. This option takes effect only when --user_password is not specified. |
| --key_passphrase | No | String | N/A | The password to use for viewing the specified private key file. This option takes effect only when the --key_file option takes effect. |
obshell cluster stop
You can run this command to stop the specified one or more observer processes. For more information about the applicable scenarios of this command, see Stop an OceanBase cluster.
${home_path}/bin/obshell cluster stop [-a] [-s] [-z] [-f] [-I] [-i] [-y]
# example
/home/admin/oceanbase/bin/obshell cluster stop -s 10.10.10.1:2886 -I
Here, home_path is the installation directory of OceanBase Database. By default, OBShell is installed in the bin directory under the installation directory of OceanBase Database.
The following table describes the options in the command.
| Option | Required? | Data type | Default value | Description |
|---|---|---|---|---|
| -a/--all | No | N/A | N/A | Specifies to stop all observer processes. You do not need to set a value for this option. By default, if you do not specify this option, only the observer processes managed by the current OBShell process are stopped. |
| -s/--server | No | String | N/A | The IP addresses and port numbers of the OBShell-managed observer processes to be stopped, in the format of obshell_ip:obshell_port. The information about multiple observer processes must be separated with commas (,). Example: -s x.x.x.x:2886,x.x.x.x:2886. |
| -z/--zone | No | String | N/A | Specifies to stop all observer processes in the specified zones. The names of multiple zones must be separated with commas (,). Example: -z zone1,zone2. |
| -f/--force | No | Boolean | false | Specifies whether to forcibly kill the observer processes. |
| -I/--immediate | No | N/A | Specifies to run the STOP SERVER command. You do not need to set a value for this option. For more information about the STOP SERVER command, see Isolate a node.
NoteYou can specify only one of the |
|
| -i/--id | No | String | N/A | The ID of the preceding task that starts or stops the specified observer processes. You can use this option in special circumstances. When a cluster O&M task is locked by one or more preceding tasks, you can specify the -i option to release the previous tasks. Example: -i 22130706433028869. |
| -y/--yes | No | N/A | N/A | Specifies to cancel secondary confirmation. You do not need to set a value for this option. |
obshell cluster upgrade
You can run this command to upgrade OceanBase Database or OBShell to the specified version. For more information about the applicable scenarios of this command, see Upgrade an OceanBase cluster.
${home_path}/bin/obshell cluster upgrade -d [-m] [-V] [-t] [-y]
# example
/home/admin/oceanbase/bin/obshell cluster upgrade -d /home/admin/oceanbase/upgrade/ -V 4.2.2.0-20231224224959
Here, home_path is the installation directory of OceanBase Database. By default, OBShell is installed in the bin directory under the installation directory of OceanBase Database.
The following table describes the options in the command.
| Option | Required? | Data type | Default value | Description |
|---|---|---|---|---|
| -d/--pkg_directory | Yes | String | N/A | The directory where the upgrade package is stored, which must be an absolute path. |
| -m/--mode | No | String | ROLLING | The upgrade mode. Valid values:
|
| -V/--target_version | No | String | N/A | The target version. You must specify the version in a valid format, such as 4.2.2.0 or 4.2.2.0-20231224224959. If you do not specify this option, the latest OceanBase Database RPM package in the directory specified by -d is used. |
| -t/--tmp_directory | No | String | ${home_path}/upgrade | The temporary directory to use during the upgrade, which stores the downloaded packages and all files generated during decompression and installation. It must be an absolute path. |
| -y/--yes | No | N/A | N/A | Specifies to cancel secondary confirmation. You do not need to set a value for this option. |
obshell cluster scale-out
You can run this command to add an OBServer node to the current cluster to be scaled out. For more information about the applicable scenarios of this command, see Use OBShell to scale out an OceanBase cluster.
${home_path}/bin/obshell cluster scale-out -z -s [--rp] [-d] [-r] [-p] [-P] [-l] [-o] [-y]
# example
/home/admin/oceanbase/bin/obshell cluster scale-out -s '10.10.10.4:2886' -z 'zone1' -o 'memory_limit=16G,system_memory=8G,log_disk_size=24G,datafile_size=24G' --rp *****
Here, home_path is the installation directory of OceanBase Database. By default, OBShell is installed in the bin directory under the installation directory of OceanBase Database.
The following table describes the options in the command.
| Option | Required? | Data type | Default value | Description |
|---|---|---|---|---|
| -s/--server | Yes | String | N/A | The IP address and port number of the OBServer node to be added to the cluster, in the ip:port format. The port number is optional. By default, port 2886 is used. |
| -z/--zone | Yes | String | N/A | The zone to which the OBServer node is to add. |
| --rp/--rootpassword | No | String | N/A | The password for the root user of the sys tenant in the cluster to be scaled out. If the password is incorrect, the scale-out cannot be initiated. |
| -d/--data_dir | No | String | ${home_path}/store | The directory for storing SSTables and other data, which must be an absolute path. By default, the store directory under the working directory is used. The working directory is specified by the home_path parameter. |
| -r/--redo_dir | No | String | ${data_dir} | The directory for storing clogs, which must be an absolute path. By default, the value of this option is the same as that of the --data_dir option. |
| -p/--mysql_port | No | Integer | 2881 | The port number for the SQL service protocol. By default, port 2881 is used. |
| -P/--rpc_port | No | Integer | 2882 | The protocol port number for remote access. By default, port 2882 is used. |
| -l/--log_level | No | String | N/A | The log level of the OBServer node. |
| -o/--opt_str | No | String | N/A | Other options for the OBServer node. You must specify each option in the key=value format, and separate multiple options with commas (,). The entire value string of the -o option must be enclosed by single quotation marks ('). Example: -o 'memory_limit=16G,system_memory=8G,log_disk_size=24G,datafile_size=24G'. |
| -y/--yes | No | N/A | N/A | Specifies to cancel secondary confirmation. You do not need to set a value for this option. |