Purpose
You can create a user tenant by using the CREATE TENANT statement. OceanBase Database allows you create only a user tenant. The sys tenant is automatically created when a cluster is created. A meta tenant is a self-managed tenant in OceanBase Database, and is created each time a user tenant is created. The lifecycle of a meta tenant is consistent with that of the corresponding user tenant.
By default, the role of a tenant created by using the CREATE TENANT statement is PRIMARY.
Limitations and considerations
OceanBase Database supports two tenant modes: MySQL and Oracle. When you create a tenant, you must specify the tenant mode. The tenant mode cannot be changed after the tenant is created.
When you create a tenant, you need to allocate a resource pool to the tenant. Therefore, you need to plan resources in advance and create resource pools. For more information about how to create a resource pool, see Create a tenant.
For more information about limitations on tenant cloning, see Clone a tenant.
Required privileges
Only the root user of the sys tenant (root@sys) can create a tenant.
Syntax
The syntax for creating a tenant is as follows:
CREATE TENANT { {[IF NOT EXISTS] tenant_name [tenant_option_list] [set_sys_var]} | {clone_tenant_clause} };
tenant_option_list:
tenant_option [, tenant_option...]
tenant_option:
LOCALITY [=] 'locality_description'
| PRIMARY_ZONE [=] primary_zone_name
| RESOURCE_POOL_LIST [=] (pool_name [, pool_name...])
| ENABLE_ARBITRATION_SERVICE [=] {True | False}
| {CHARACTER SET | CHARSET} [=] charset_name
| COLLATE [=] collation_name
| {READ ONLY | READ WRITE}
| COMMENT [=] 'string'
set_sys_var:
{SET | SET VARIABLES | VARIABLES} var_name {TO | =} var_value [,var_name {TO | =} var_value...]
clone_tenant_clause:
new_tenant_name FROM source_tenant_name WITH
RESOURCE_POOL [=] resource_pool_name,
UNIT [=] unit_config
Parameters
| Parameter | Description |
|---|---|
| tenant_name | The name of the tenant. The name cannot exceed 63 bytes and can contain only letters, digits, and underscores (). It must start with a letter or underscore (), and cannot contain any OceanBase Database keywords. |
| IF NOT EXISTS | If the tenant name already exists and IF NOT EXISTS is not specified, an error is returned. |
| LOCALITY | The distribution of replicas across zones. For example, F@z1,F@z2,F@z3 indicates that z1, z2, and z3 are full-featured replicas. |
| PRIMARY_ZONE | The primary zone of the tenant. Valid values:
If you do not specify the primary zone when you create the tenant, RANDOM is used by default. |
| RESOURCE_POOL_LIST | The list of resource pools allocated to the tenant. You must specify this parameter when you create a tenant. If you specify multiple resource pools, the UNIT_NUM settings must be consistent among these resource pools.
NoticeThe zones of resource pools allocated to the same tenant must not overlap. |
| ENABLE_ARBITRATION_SERVICE | Specifies whether to enable the arbitration service for the tenant. If you do not specify this parameter, False is used by default. If the arbitration service is deployed for the cluster and you do not enable the arbitration service when you create the tenant, you can enable the service after the tenant is created. For more information, see Enable the arbitration service for a tenant. |
| CHARACTER SET | CHARSET | The tenant-level character set. For more information about character sets, see Character sets (MySQL mode) and Character sets (Oracle mode). |
| COLLATE | The tenant-level collation. For more information about collations, see Collations (MySQL mode) and Collations (Oracle mode). |
| READ ONLY | READ WRITE | The read-only or read/write attribute of the tenant. If you do not specify this parameter, read/write is used by default. |
| set_sys_var | The tenant-level system variables. The system variables are described as follows:
|
| COMMENT | The comment. This parameter is optional. |
| clone_tenant_clause | The clause for cloning the tenant. |
| new_tenant_name | The name of the new tenant. |
| source_tenant_name | The name of the source tenant. |
| resource_pool_name | The name of the resource pool. When you clone a tenant, a resource pool is automatically created for the new tenant based on the resource distribution of the source tenant. |
| unit_config | The resource unit specifications of the resource pool for the new tenant. |
Examples
Create a MySQL tenant named
test_tenantwith the primary zonezone1;zone2,zone3, resource poolpool1, and character setutf8mb4. Specify that all client IP addresses can connect to the tenant.obclient [oceanbase]> CREATE TENANT IF NOT EXISTS test_tenant PRIMARY_ZONE='zone1;zone2,zone3', RESOURCE_POOL_LIST=('pool1'), CHARSET='utf8mb4' SET ob_tcp_invited_nodes TO '%';Create an Oracle tenant named
tenant1with the primary zonezone1and resource poolpool1. Specify that all client IP addresses can connect to the tenant.obclient [oceanbase]> CREATE TENANT tenant1 PRIMARY_ZONE='zone1', RESOURCE_POOL_LIST=('pool1') SET ob_compatibility_mode='oracle', ob_tcp_invited_nodes='%';Clone the
mysql001tenant and name the new tenant asclone_mysql001. Specify the resource pool nameclone_mysql001_resource_pooland the resource unit nameunit001for the new tenant.Notice
You must enable log archiving on the source tenant to clone the tenant. During the execution of the tenant cloning statement, you cannot disable log archiving for the source tenant. For more information about log archiving, see Overview.
CREATE TENANT clone_mysql001 FROM mysql001 WITH RESOURCE_POOL = clone_mysql001_resource_pool, UNIT = unit001;When you execute a tenant cloning statement in the sys tenant, a corresponding clone task is generated. You can view the execution status of the clone task in the
DBA_OB_CLONE_PROGRESSandDBA_OB_CLONE_HISTORYviews.Here is an example:
obclient [(none)]> SELECT * FROM oceanbase.DBA_OB_CLONE_HISTORY WHERE CLONE_TENANT_NAME = 'clone_mysql001'\GThe return result is as follows:
*************************** 1. row *************************** CLONE_JOB_ID: 1706248530701634201 TRACE_ID: YB42AC1E87C9-00060F1AD6DF0264-0-0 SOURCE_TENANT_ID: 1002 SOURCE_TENANT_NAME: mysql001 CLONE_TENANT_ID: 1012 CLONE_TENANT_NAME: clone_mysql001 TENANT_SNAPSHOT_ID: 1706248530759745885 TENANT_SNAPSHOT_NAME: _inner_snapshot$1706248530759740679 RESOURCE_POOL_ID: 1006 RESOURCE_POOL_NAME: clone_mysql001_resource_pool UNIT_CONFIG_NAME: unit001 RESTORE_SCN: 1706248531829799503 STATUS: CLONE_SYS_SUCCESS CLONE_JOB_TYPE: FORK CLONE_START_TIME: 2024-01-26 13:55:30.705699 CLONE_FINISHED_TIME: 2024-01-26 13:56:00.141434 RET_CODE: 0 ERROR_MESSAGE: NULL 1 row in set
For more information about the fields in the views, see DBA_OB_CLONE_PROGRESS and DBA_OB_CLONE_HISTORY.