This topic describes the cluster commands of obshell, which can be used to deploy and manage OceanBase clusters.
You can use the -h/--help option with a command to view its help information. If a task fails during execution, you can use the -v/--verbose option to view detailed execution logs.
obshell cluster join
You can use this command to add the current obshell to a specified cluster (run this command before initializing the OceanBase cluster).
${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
home_path refers to the installation directory of OceanBase Database. By default, obshell is located in the bin directory under the installation directory.
The following table describes the options available for this command.
| Option | Required | Data type | Default value | Description |
|---|---|---|---|---|
| -z/--zone | Yes | string | N/A | Specifies the zone to which the node belongs. |
| -s/--server | Yes | string | N/A | Specifies the target node to join. The format is ip:port. The port parameter is optional; the default is 2886. |
| -d/--data_dir | No | string | ${home_path}/store | Specifies the directory for storing data such as SSTables. The value must be an absolute path. The default is the store directory under the working directory (home_path). |
| -r/--redo_dir | No | string | ${data_dir} | Specifies the directory for storing clog data. The value must be an absolute path. The default is the same as --data_dir. |
| -p/--mysql_port | No | int | 2881 | Specifies the port number for the SQL service protocol. The default is 2881. |
| -P/--rpc_port | No | int | 2882 | Specifies the port number for the remote access protocol. The default is 2882. |
| -o/--opt_str | No | string | N/A | Specifies additional parameters for the OBServer node. Each parameter is in the format key=value, and multiple parameters are separated by commas. The -o option must be enclosed in single quotation marks, for example: -o 'memory_limit=16G,system_memory=8G,log_disk_size=24G,datafile_size=24G'. |
| -l/--log_level | No | string | N/A | Specifies the log output level for the OBServer node. |
obshell cluster remove
You can run this command to remove the specified obshell from the 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
home_path specifies the installation directory of OceanBase Database, and obshell is located in the bin directory of the installation directory by default.
The following table describes the options available for this command.
| Option | Required | Data type | Default value | Description |
|---|---|---|---|---|
| -s/--server | Yes | string | N/A | The target node to be removed. The format is ip:port. The port parameter is optional. The default value is 2886. |
| -y/--yes | No | N/A | N/A | Specifies whether to skip the confirmation prompt. This option is not required. |
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 ********
home_path specifies the installation directory of OceanBase Database. By default, obshell is located in the bin directory of the installation directory.
The following table describes the options available for this command.
| Option | Required | Data type | Default value | Description |
|---|---|---|---|---|
| -n/--cluster_name | Yes | string | N/A | The name of the current OceanBase cluster. |
| --rp/--rootpassword | No | string | N/A | The password of the root user of the sys tenant. |
| -i/--cluster_id | No | int | 1 | The ID of the current OceanBase cluster. The default value is 1. |
| -d/--data_dir | No | string | ${home_path}/store | The directory for storing data such as the SSTable. The directory must be an absolute path. The default value is the store directory under the working directory (home_path). |
| -r/--redo_dir | No | string | ${data_dir} | The directory for storing clog data. The directory must be an absolute path. The default value is the same as that of --data_dir. |
| -p/--mysql_port | No | int | 2881 | The port number of the SQL service protocol. The default value is 2881. |
| -P/--rpc_port | No | int | 2882 | The port number of the remote access protocol. The default value is 2882. |
| --rs/--rs_list | No | string | N/A | The list of Root Services. The format is observer_ip:rpc_port:mysql_port. Separate each Root Server with ;. The --rs option must be enclosed in single quotation marks, for example, --rs '10.10.10.1:2882:2881;10.10.10.2:2882:2881'. |
| --import_script | No | bool | false | Specifies whether to import timezone data and GIS metadata to the sys tenant. The default value is false. |
| -o/--opt_str | No | string | N/A | The other parameters of the OceanBase cluster. The format of each parameter is key=value. Separate multiple parameters with commas (,). The -o option must be enclosed in single quotation marks, for example: -o 'memory_limit=16G,system_memory=8G,log_disk_size=24G,datafile_size=24G'. |
| -l/--log_level | No | string | N/A | The log printing level of the OceanBase cluster. |
obshell cluster show
You can run this command to view the information of the current cluster.
${home_path}/bin/obshell cluster show [-d]
home_path specifies the installation directory of OceanBase Database. By default, obshell is located in the bin directory of the installation directory. The -d/--show_detail option is optional. It specifies whether to view the detailed information of the cluster. You can omit the value.
The output of this command varies depending on the status of the OceanBase cluster.
If the OceanBase cluster is not initialized, only the information of obshell is displayed, including the IP address, version, and port number.
If the OceanBase cluster is initialized, the information of obshell and OceanBase Database is displayed. The information of OceanBase Database includes the cluster name, version, zone, SQL port, server port, root server, and status.
The status can be one of the following values:
ACTIVE: The OBServer node is connected to the Root Service.INACTIVE: The OBServer node is disconnected from the Root Service.DELETING: The OBServer node is being deleted.STOPPED: The OBServer node is stopped.
obshell cluster start
You can run this command to start OBServer nodes within a specified range or take over an OceanBase cluster. If you run this command to start OBServer nodes within a specified range, the OceanBase cluster must be fully managed by obshell.
For more information about whether the cluster is managed by obshell and how to use obshell to take over an OceanBase cluster, see Take over a non-obshell-deployed cluster. For more information about how to start OBServer nodes, 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
home_path specifies the installation directory of OceanBase Database. By default, obshell is installed in the bin directory of the installation directory of OceanBase Database.
The following table describes the options available for this command.
| Option | Required | Data type | Default value | Description |
|---|---|---|---|---|
| -a/--all | No | N/A | N/A | Specifies whether to start all OBServer nodes. No value is required. If this option is not specified in the command, only the OBServer nodes managed by the current obshell are started by default. |
| -s/--server | No | string | N/A | Specifies the OBServer nodes managed by obshell to start. The format is obshell_ip:obshell_port. Separate multiple obshell instances with commas (,), for example, -s x.x.x.x:2886,x.x.x.x:2886. |
| -z/--zone | No | string | N/A | Specifies all OBServer nodes in the specified zone. Separate multiple zones with commas (,), for example, -z zone1,zone2. |
| -i/--id | No | string | N/A | Specifies the ID of a preceding start/stop task. This option is used only in special cases. When an OceanBase cluster is locked by one or more preceding start/stop tasks, you can use -i to unlock the preceding task, for example, -i 22130706433028869. |
| -y/--yes | No | N/A | N/A | Specifies whether to skip the secondary confirmation. No value is required. |
| --ssh_user | No | string | N/A | Specifies the user for an SSH connection. |
| --ssh_port | No | string | N/A | Specifies the port number for an SSH connection. |
| --user_password | No | string | N/A | Specifies the user password for an SSH connection. |
| --key_file | No | string | "/~/.ssh/id_rsa" | Specifies the private key file for an SSH connection. This option is effective only when --user_password is not specified. |
| --key_passphrase | No | string | N/A | Specifies the password for viewing the specified private key file. This option is effective only when --key_file is specified. |
obshell cluster stop
You can run this command to stop the observer processes in the specified range. For more information, 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
home_path specifies the installation directory of OceanBase Database. By default, obshell is located in the bin directory of the installation directory.
The following table describes the options available for this command.
| Option | Required | Data type | Default value | Description |
|---|---|---|---|---|
| -a/--all | No | N/A | N/A | Specifies whether to stop all observer processes. This option is optional. If this option is not specified in the command, by default, only the observer processes of the OBServer nodes managed by the current obshell are stopped. |
| -s/--server | No | string | N/A | Specifies the observer process to stop. The format is obshell_ip:obshell_port. Multiple obshells are separated with commas (,), for example, -s x.x.x.x:2886,x.x.x.x:2886. |
| -z/--zone | No | string | N/A | Specifies all observer processes in the specified zone. Multiple zones are separated with commas (,), for example, -z zone1,zone2. |
| -f/--force | No | bool | false | Specifies whether to forcibly kill the observer process. This option is optional. |
| -I/--immediate | No | N/A | Specifies whether to execute STOP SERVER. This option is optional. For more information about STOP SERVER, see Isolate a node.
NoteThe |
|
| -i/--id | No | string | N/A | Specifies the ID of the preceding start/stop task. This option is used only in special cases. When the cluster is locked by one or more preceding start/stop tasks, you can use -i to unlock the preceding task. For example, -i 22130706433028869. |
| -y/--yes | No | N/A | N/A | Specifies whether to cancel the secondary confirmation. This option is optional. |
obshell cluster upgrade
You can run this command to upgrade OceanBase Database or obshell to the specified version. For more information, 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
home_path specifies the installation directory of OceanBase Database. By default, obshell is located in the bin directory of the installation directory of OceanBase Database.
The following table describes the options available for this command.
| Option | Required | Data type | Default value | Description |
|---|---|---|---|---|
| -d/--pkg_directory | Yes | string | N/A | The absolute path of the directory where the upgrade package is located. |
| -m/--mode | No | string | ROLLING | The upgrade mode. Valid values:
|
| -V/--target_version | No | string | N/A | The target version. The value must be in the correct format, such as 4.2.2.0 or 4.2.2.0-20231224224959. If this option is not specified, the latest version of OceanBase Database RPM packages in the directory specified by -d is used. |
| -t/--tmp_directory | No | string | ${home_path}/upgrade | The temporary directory for storing the downloaded installation packages and all files generated during decompression and installation. The value must be an absolute path. |
| -y/--yes | No | N/A | N/A | Specifies whether to skip the confirmation prompt. This option does not require a value. |
obshell cluster scale-out
You can run this command to scale out the current node to the specified cluster. For more information about the usage scenarios of this command, see Scale out an OceanBase cluster by using obshell.
${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.1:2886' -z 'zone1' -o 'memory_limit=16G,system_memory=8G,log_disk_size=24G,datafile_size=24G' --rp *****
home_path specifies the installation directory of OceanBase Database. By default, obshell is installed in the bin directory of the installation directory of OceanBase Database.
The following table describes the options available for this command.
| Option | Required | Data type | Default value | Description |
|---|---|---|---|---|
| -s/--server | Yes | string | N/A | The existing node in the cluster to be scaled out. If the cluster to be scaled out contains multiple nodes, specify one of them. The format is ip:obshell_port, where obshell_port is optional. The default value is 2886. |
| -z/--zone | Yes | string | N/A | The zone to which the current node belongs after the scale-out operation. |
| --rp/--rootpassword | No | string | N/A | The password of the root user of the sys tenant in the cluster to be scaled out. If the password is incorrect, the scale-out operation cannot be initiated. |
| -d/--data_dir | No | string | ${home_path}/store | The directory for storing data such as the SSTable. The value must be an absolute path. The default value is the store directory in the working directory (home_path). |
| -r/--redo_dir | No | string | ${data_dir} | The directory for storing clog data. The value must be an absolute path. The default value is the same as that of --data_dir. |
| -p/--mysql_port | No | int | 2881 | The port number for the SQL service protocol. The default value is 2881. |
| -P/--rpc_port | No | int | 2882 | The port number for remote access. The default value is 2882. |
| -l/--log_level | No | string | N/A | The log print level of the OBServer node. |
| -o/--opt_str | No | string | N/A | Other parameters of the OBServer node. The format of each parameter is key=value. Multiple parameters are separated with commas (,). The option -o must be enclosed with single quotation marks ('), for example: -o 'memory_limit=16G,system_memory=8G,log_disk_size=24G,datafile_size=24G'. |
| -y/--yes | No | N/A | N/A | Specifies whether to skip the confirmation prompt. The option does not need to be specified. |
obshell cluster scale-in
You can run this command to remove a specified node or zone from the cluster.
${home_path}/bin/obshell cluster scale-in [-z] [-s]
# example
/home/admin/oceanbase/bin/obshell cluster scale-in -z zone1
/home/admin/oceanbase/bin/obshell cluster scale-in -s "10.10.10.1:2886" -f
home_path specifies the installation directory of OceanBase Database. By default, obshell is located in the bin directory of the installation directory of OceanBase Database.
The following table describes the options available for this command.
| Option | Required | Data type | Default value | Description |
|---|---|---|---|---|
| -s/--server | No | string | N/A | Specifies the node to be removed from the cluster. The format is ip:obshell_port, where obshell_port is optional. The default value is 2886.
NoteYou can specify either |
| -z/--zone | Yes | string | N/A | Specifies the zone to be removed from the cluster.
NoteYou can specify either |
| -f/--force | No | N/A | N/A | Specifies whether to kill the observer process on the node to be removed. This option is valid only when you remove a node. If you specify this option, the observer process on the node to be removed is killed before the node is removed.
NoteYou must specify |
| -y/--yes | No | N/A | N/A | Specifies whether to skip the secondary confirmation. This option does not require a value. |
obshell cluster backup
You can run this command to set backup-related configurations for all tenants in the cluster and perform backup. For more information, see Initiate cluster-level backup.
${home_path}/bin/obshell cluster backup [flags]
# example
/home/admin/oceanbase/bin/obshell cluster backup -u /path/to/backup --backup_mode incremental --encryption MySecretPassword
home_path specifies the installation directory of OceanBase Database. By default, obshell is installed in the bin directory of the installation directory of OceanBase Database.
The following table describes the options available for this command.
| Option | Required | Data type | Default value | Description |
|---|---|---|---|---|
| -u/--backup_base_uri | No | string | N/A | The backup destination for all tenants. After this option is specified, the backup destination for each tenant is concatenated based on a specific rule in this path. If the backup destination has been specified before, the value specified for this option is not used. If the backup destination has not been specified before, the value specified for this option is not used, and the default value is an empty string. |
| -m/--backup_mode | No | string | full | The data backup mode. Valid values: full and incremental, which respectively indicate full backup and incremental backup. |
| -c/--log_archive_concurrency | No | int | N/A | The total number of worker threads for log archiving. |
| -b/--binding | No | string | Optional | The priority mode of archiving and business. Valid values: Optional and Mandatory. If this option is not specified, the default value is Optional. |
| -i/--piece_switch_interval | No | string | N/A | The period for switching pieces. Valid value: [1d, 7d]. |
| -e/--encryption | No | string | N/A | The password of the backup set after backup. If this option is specified, the password must be entered when restoring the backup set, and the password cannot be deleted. |
| -l/--archive_lag_target | No | string | N/A | The lag of log archiving. If you want to modify this parameter, make sure that the backup destination for log archiving has been configured. |
| -D/--delete_policy | No | string | default | The cleanup strategy. If this option is specified, the tenant will trigger automatic cleanup every hour. At present, only the value default is supported, which indicates that automatic cleanup applies only to the backup specified by -u/--backup_base_uri. |
| -r/--delete_recovery_window | No | string | N/A | The time window for restoring backup data. The value must contain a time unit. For more information, see Parameters related to backup cleanup. |
| -s/--ha_low_thread_score | No | int | N/A | The number of worker threads for low-priority tasks such as backup and backup cleanup. Value range: [0, 100]. |
| -P/--plus_archive | No | N/A | N/A | Specifies whether to back up archived logs during data backup. No value needs to be specified. If this option is added, a complete dataset containing archived logs is generated in the final backup directory. |