This topic describes the tenant commands in obshell, which are used to create and manage tenants. Before you use these commands, make sure that the OceanBase cluster has been initialized. You can specify the -h/--help option in the commands for more information about the options. If an error occurs during task execution, you can specify the -v/--verbose option to view the detailed execution process.
obshell tenant create
You can use this command to create a business tenant.
${home_path}/bin/obshell tenant create <tenant_name> [-z] [-u] [--unit_num] [--replica_type] [--primary_zone] [--charset] [--collation] [--info] [--read_only]
[--parameters] [--variables] [--whitelist] [--scenario] [--root_password]
# example
# Create a tenant named t1, which has a full-featured replica in each zone of the cluster and uses the resource pool s1.
/home/admin/oceanbase/bin/obshell tenant create t1 -u s1
home_path is the installation directory of OceanBase Database. By default, obshell is located in the bin directory of OceanBase Database. tenant_name is the name of the tenant to be created.
For more information about the options, see the following table:
Option |
Required |
Data type |
Default value |
Description |
|---|---|---|---|---|
| -z/--zone | No | string | The zones where the tenant is distributed. If this option is not specified, the tenant is distributed to all zones in the cluster. | |
| -u/--unit | No | string | The resource specifications of the tenant's resource pool.
NoteYou can use the syntax |
|
| --unit_num | No | int | 1 | The number of units of the tenant in the target zone. The value of this parameter must be less than the number of nodes in the target zone. |
| --replica_type | No | string | FULL | The types of the replicas of the tenant in the target zone. Valid values are FULL (full-featured replica) and READONLY (read-only replica).
NoteYou can use the syntax |
| --primary_zone | No | string | RANDOM | The primary zone of the tenant, which indicates the priority of zones that provide read/write services to the tenant. For example, primary_zone ='zone1;zone2,zone3' means that the tenant is primarily served by zone1. The priority of zone1 is higher than that of zone2 and zone3, which have the same priority. |
| --scenario | No | string | The load type of the tenant. Valid values are as follows:
NoteThis option is supported only in OceanBase clusters of version 4.3.0 or later. |
|
| --variables | No | string | The system variables of the tenant. The variables are in the format of max_connections=1000,ob_query_time=1000000. |
|
| --parameters | No | string | The configuration parameters of the tenant. The parameters are in the format of backup_data_file_size=2G,arbitration_timeout=10s. |
|
| --whitelist | No | string | The access allowlist of the tenant. | |
| --root_password | No | string | The password of the root user of the tenant. | |
| --read_only | No | Specifies whether the tenant is read-only. | ||
| --charset | No | string | The character set of the tenant. | |
| --collate | No | string | The collation sequence of the tenant. | |
| --info | No | string | The information about the tenant. |
obshell tenant drop
You can use this command to drop a specified tenant.
${home_path}/bin/obshell tenant drop <tenant_name> [--recycle] [-y]
# example
/home/admin/oceanbase/bin/obshell tenant drop t1
home_path is the installation directory of OceanBase Database, and obshell is located in the bin directory of OceanBase Database. tenant_name is the name of the tenant to be dropped.
The options are described as follows:
Option |
Required |
Data type |
Default value |
Description |
|---|---|---|---|---|
| --recycle | No | None | None | This option does not require a value. When it is specified, the deleted tenant will be moved to the recycle bin. |
| -y/--yes | No | None | None | This option is used to control whether to disable the confirmation prompt. It does not require a value. |
obshell tenant modify
You can use this command to modify the primary zone and whitelist of a tenant.
${home_path}/bin/obshell tenant modify <tenant_name> [--primary_zone] [--whitelist] [--password] [--old_password] [--new_password]
# example
/home/admin/oceanbase/bin/obshell tenant modify t1 --primary_zone RANDOM --whitelist '%'
home_path is the installation directory of OceanBase Database. By default, obshell is located in the bin directory of OceanBase Database installation directory. tenant_name is the name of the tenant to be modified.
The options are described as follows:
Option |
Required |
Data type |
Default value |
Description |
|---|---|---|---|---|
| --primary_zone | No | string | None | The primary zone specifies the priority of the zone that provides read/write services for the tenant. For example, primary_zone ='zone1;zone2,zone3' indicates that the tenant is preferentially provided with read/write services by zone1, with zone1 having a higher priority than zone2 and zone3, and zone2 and zone3 being at the same priority. |
| --whitelist | No | string | None | The access whitelist of the tenant. |
| --password | No | None | Specifies whether to interactively change the password of the root user. This option does not require a value.
NoteThis option is mutually exclusive with |
|
| --old_password | No | string | None | The current password of the root user. This option is required when you want to change the password of the root user. |
| --new_password | No | string | None | The new password of the root user. This option is required when you want to change the password. |
obshell tenant lock
You can use this command to lock a tenant. A locked tenant cannot be accessed by users.
${home_path}/bin/obshell tenant lock <tenant_name>
# example
/home/admin/oceanbase/bin/obshell tenant lock t1
home_path is the installation directory of OceanBase Database, and obshell is located in the bin directory of OceanBase Database installation directory by default. tenant_name is the name of the tenant to be locked.
obshell tenant unlock
You can use this command to unlock a tenant.
${home_path}/bin/obshell tenant unlock <tenant_name>
# example
/home/admin/oceanbase/bin/obshell tenant unlock t1
home_path is the installation directory of OceanBase Database, and obshell is located in the bin directory of OceanBase Database's installation directory by default. tenant_name is the name of the tenant to unlock.
obshell tenant rename
You can use this command to rename a tenant.
${home_path}/bin/obshell tenant rename <tenant_name> <new_name>
# example
/home/admin/oceanbase/bin/obshell tenant rename t1 t2
home_path is the installation directory of OceanBase Database, and obshell is located in the bin directory of OceanBase Database's installation directory by default. tenant_name is the name of the tenant to be renamed, and new_name is the new name of the tenant after the rename.
obshell tenant replica
You can use the commands in this topic to manage replicas of a tenant.
obshell tenant replica add
You can use this command to batch add tenant replicas.
${home_path}/bin/obshell tenant replica add <tenant_name> -z [-u] [--replica_type]
# example
/home/admin/oceanbase/bin/obshell tenant replica add t1 -z zone4,zone5 -u s1
home_path is the installation directory of OceanBase Database. By default, obshell is located in the bin directory of OceanBase Database. tenant_name is the name of the tenant for which you want to add replicas.
The options are described as follows:
Option |
Required |
Data type |
Default value |
Description |
|---|---|---|---|---|
| -z/--zone | Yes | string | None | Specify the Zone where the newly added replicas are distributed, separated by commas (,). |
| -u/--unit | No | string | None | The resource specification used by the tenant resource pool.
NoteYou can separately specify the resource specification for a particular Zone using a format like |
| --replica_type | No | string | None | The replica type of the tenant on the target Zone can be configured as FULL (fully functional replica) or READONLY (read-only replica).
NoteYou can specify the replica type for a specific Zone individually using a format like |
obshell tenant replica delete
You can use this command to batch delete tenant replicas.
${home_path}/bin/obshell tenant replica delete <tenant_name> -z
# example
/home/admin/oceanbase/bin/obshell tenant replica delete t1 -z zone3
home_path is the installation directory of OceanBase Database. By default, obshell is located in the bin directory of OceanBase Database. tenant_name is the name of the tenant from which you want to delete replicas.
You must specify the -z or --zone option to indicate the zones where the replicas to be deleted are distributed. Multiple zones are separated with commas (,).
obshell tenant replica modify
The command is used to batch modify the attributes of replicas.
${home_path}/bin/obshell tenant replica modify <tenant_name> [-z] [-u] [--unit_num] [--replica_type]
# example
/home/admin/oceanbase/bin/obshell tenant replica modify t1 --unit s2 --unit_num 2
home_path is the installation directory of OceanBase Database. By default, obshell is located in the bin directory of OceanBase Database. tenant_name is the name of the tenant whose replica attributes are to be modified.
The options are described as follows:
Option |
Required |
Type |
Default value |
Description |
|---|---|---|---|---|
| -z/--zone | No | string | None | Specify the Zone where the modified replicas are distributed, multiple Zones are separated by English commas (,). If not specified, it defaults to modifying replicas on all Zones. |
| -u/--unit | No | string | None | The resource specification used by the tenant resource pool.
NoteYou can separately specify the resource specification for a particular Zone using a method like |
| --unit_num | No | string | None | The number of units for the tenant in the target Zone, which must be less than the number of nodes in the target Zone. |
| --replica_type | No | string | None | The replica type of the tenant on the target Zone can be configured as FULL (fully functional replica) or READONLY (read-only replica).
NoteYou can separately specify the replica type for a particular Zone using a format like |
obshell tenant parameter
You can use this command group to manage tenant parameters.
obshell tenant parameter set
You can use this command to set tenant parameters.
${home_path}/bin/obshell tenant parameter set <tenant_name> <name=value>
# example
/home/admin/oceanbase/bin/obshell tenant parameter set t1 cpu_quota_concurrency=10,_rowsets_enabled=true
home_path is the installation directory of OceanBase Database. obshell is located in the bin directory of OceanBase Database by default; tenant_name is the name of the tenant for which the parameters are to be set; parameters are in the <name=value> format, and multiple parameters are separated with commas (,).
In the example above, t1 is the name of the tenant for which the parameters are to be set, and cpu_quota_concurrency=10,_rowsets_enabled=true are the parameters of t1.
obshell tenant parameter show
You can use this command to query tenant parameters. The query supports fuzzy matching.
${home_path}/bin/obshell tenant parameter show <tenant_name> <parameter>
# example
/home/admin/oceanbase/bin/obshell tenant parameter show t1 cpu_quota_concurrency
home_path is the installation directory of OceanBase Database. obshell is located in the bin directory of OceanBase Database by default; tenant_name is the name of the tenant for which the parameters are to be queried; parameter is the name of the parameter to be queried. It supports fuzzy matching.
obshell tenant variable
You can use this command group to manage tenant variables.
obshell tenant variable set
You can use this command to set global tenant variables.
${home_path}/bin/obshell tenant variable set <tenant_name> <name=value>
# example
/home/admin/oceanbase/bin/obshell tenant variable set t1 max_connections=10000,recyclebin=true
home_path is the installation directory of OceanBase Database. obshell is located in the bin directory of OceanBase Database's installation directory by default. tenant_name is the name of the tenant whose system variable you want to set. System variables are specified in the <name=value> format. If you specify multiple system variables, separate them with commas (,).
obshell tenant variable show
You can use this command to query tenant variables. The query supports fuzzy matching.
${home_path}/bin/obshell tenant variable show <tenant_name> <variable>
# example
/home/admin/oceanbase/bin/obshell tenant variable show t1 max_connections
home_path is the installation directory of OceanBase Database. obshell is located in the bin directory of OceanBase Database's installation directory by default. tenant_name is the name of the tenant whose system variable you want to query. variable is the name of the system variable. It supports fuzzy matching.
obshell tenant show
You can use this command to query the information about a tenant.
${home_path}/bin/obshell tenant show [tenant_name] [-d]
# example
/home/admin/oceanbase/bin/obshell tenant show t1
home_path is the installation directory of OceanBase Database, and obshell is located in the bin directory of OceanBase Database. You need to specify the tenant_name parameter with the name of the tenant whose information you want to query. If you do not specify this parameter, information about all tenants in the cluster will be displayed.
You can use the -d/--show_detail option to control whether to display the details of the tenant. This option does not require a value.
obshell tenant backup
You can use this command to set backup-related configurations for a tenant and perform a backup.
${home_path}/bin/obshell tenant backup <tenant_name> [flags]
# example
/home/admin/oceanbase/bin/obshell tenant backup t1 -d /path/to/backup/data --backup_mode incremental --encryption MySecretPassword
home_path is the installation directory of OceanBase Database, and obshell is located in the bin directory of OceanBase Database. tenant_name is the name of the tenant to be backed up.
The options are described as follows:
Option |
Required |
Type |
Default value |
Description |
|---|---|---|---|---|
| -d/--data_backup_uri | No | string | None | The destination for backing up the data of the tenant. If the destination is not specified, the previously specified destination is used. If no destination is specified previously, the default value is an empty string. |
| -a/--archive_log_uri | No | string | None | The destination for archiving the logs of the tenant. If the destination is not specified, the previously specified destination is used. If no destination is specified previously, the default value is an empty string. |
| -m/--backup_mode | No | string | full | The data backup mode. Valid values: full and incremental. These values indicate full backup (full) and incremental backup (incremental), respectively. |
| -c/--log_archive_concurrency | No | int | None | The total number of worker threads for log archiving. |
| -b/--binding | No | string | Optional | The priority mode for binding log archiving and business operations. Valid values: Optional (business operations take precedence) and Mandatory (log archiving takes precedence). If this option is not specified, the default value Optional takes effect. |
| -i/--piece_switch_interval | No | string | None | The cycle for switching pieces. The value range is [1d, 7d]. |
| -e/--encryption | No | string | None | The password for the backup set after the backup is completed. If this option is specified, you must enter the password when restoring the backup set, and the password cannot be deleted. |
| -l/--archive_lag_target | No | string | None | The latency period for log archiving. Before you modify this parameter, make sure that the destination for log archiving is configured. |
| -D/--delete_policy | No | string | default | The cleanup strategy. A tenant with a cleanup strategy will trigger an automatic cleanup every hour. Currently, only the value default is supported. It indicates that automatic cleanup is limited to the backup data in -d/--data_backup_uri and -a/--archive_log_uri. |
| -r/--delete_recovery_window | No | string | None | The time window for restoring backup data. The value format is [number][time unit]. For example, 7d indicates seven days. For more information, see Overview of backup-related parameters. |
| -s/--ha_low_thread_score | No | int | None | The current number of worker threads for medium- and low-priority tasks such as backup and cleanup. The value range is [0, 100]. |
| -P/--plus_archive | No | None | None | Specifies whether to back up archive logs together with data during a backup. This option does not require a value. If this option is added, a complete dataset containing the archive logs will be generated in the final backup directory. |
obshell tenant restore
You can use this command to restore a backup file to a specified tenant.
${home_path}/bin/obshell tenant restore <tenant_name> [flags]
# example
/home/admin/oceanbase/bin/obshell tenant restore mytenant --timestamp "2021-01-01T00:00:00.000+08:00" -z "zone1,zone2,zone3" -d '/path/to/backup/data' -a '/path/to/backup/clog' -u unit1
home_path is the installation directory of OceanBase Database. By default, obshell is located in the bin directory of OceanBase Database. tenant_name is the name of the tenant to restore the backup file to.
The options are described as follows:
Option |
Required |
Type |
Default value |
Description |
|---|---|---|---|---|
| -d/--data_backup_uri | Yes | string | None | Data backup path of the source tenant. |
| -z/--zone | No | string | None | The Zone distribution of the tenant. If not specified, it defaults to all Zones in the cluster. |
| --unit_num | No | int | 1 | The number of units of the tenant in the target zone. The value must be less than the number of nodes in the target zone. |
| -u/--unit | No | string | None | The resource specification used by the tenant resource pool.
NoteYou can separately specify the resource specification for a particular Zone using a format like |
| --replica_type | No | string | FULL | The replica type of the tenant in the target zone. Valid values: FULL (full-featured replica) and READONLY (read-only replica).
NoteYou can specify the replica type for a specific zone in the format of |
| --primary_zone | No | string | RANDOM | The primary zone of the tenant, which indicates the priority of zones providing read/write services to the tenant. For example, primary_zone ='zone1;zone2,zone3' indicates that the tenant is primarily served by zone1, and zone1 has a higher priority than zone2 and zone3. zone2 and zone3 are at the same priority. |
| -T/--timestamp | No | string | None | Restore to the specified timestamp. Must be in the format "2006-01-02T15:04:05.000Z07:00". |
| -S/--scn | No | int | None | Restore to the specified SCN. |
| -a/--archive_log_uri | No | string | ${data_backup_uri} | The log archive URI of the source tenant. If not specified, the value of -d/--data_backup_uri is used. |
| -s/--ha_high_thread_score | No | int | None | Used to set the current number of working threads for high availability high-priority threads. The value range is [0,100]. |
| -c/--concurrency | No | int | None | Specifies the concurrency level for data recovery. If not specified, it defaults to the MAX_CPU number allocated to the tenant. |
| -D/--decryption | No | string | None | Set the recovery password for the backup. The recovery password for the backup needs to be set only in scenarios where a password was added during data backup. |
| -k/--kms_encrypt_info | No | string | None | Set encryption information. If not encrypted or the original key management service can be accessed during recovery, this does not need to be set. |