CREATE TENANT|V4.3.5| docs|Distributed Database

CREATE TENANT

Last Updated：2026-01-09 09:04:26 Updated

Purpose

The CREATE TENANT statement is used to create a user tenant. OceanBase Database only supports the creation of user tenants. The system tenant is automatically created when the cluster is created. The Meta tenant is an internally managed tenant of OceanBase Database. Each time a user tenant is created, a corresponding Meta tenant is also created, and the lifecycle of the Meta tenant is consistent with that of the user tenant.

By default, the tenant role of a tenant created using the CREATE TENANT statement is PRIMARY.

Limitations and considerations

OceanBase Database supports two types of tenants: MySQL compatible mode and Oracle compatible mode. When you create a tenant, you must specify the type of the tenant. After a tenant is created, you cannot change its type.
When you create a tenant, you must assign a resource pool to the tenant. Before you create a tenant, you must plan the resources and create a resource pool. For more information about how to create a resource pool, see Create a tenant.
For more information about the limitations on cloning a tenant, see Clone a tenant.

Privilege requirements

Only the root user of the sys tenant (root@sys) can create a tenant. Other tenants do not support tenant creation.

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. It can be up to 63 bytes in length, and can contain only uppercase and lowercase letters, digits, and underscores. It must start with a letter or an underscore and cannot be a keyword of OceanBase Database.
IF NOT EXISTS	If the specified tenant name already exists and you do not specify `IF NOT EXISTS`, an error is returned.
LOCALITY	The distribution of replicas among zones. The following replica types are supported in the current version: Full-featured replica: named FULL, abbreviated as F. For more information, see Full-featured replica. Read-only replica: named READONLY, abbreviated as R. For more information, see Read-only replica. Columnstore replica: named COLUMNSTORE, abbreviated as C. For more information, see Columnstore replica. Example: `LOCALITY = 'F@z1,F@z2,F@z3'`, `LOCALITY = 'F@z1,R@z2,C@z3'`, or `LOCALITY = 'F@z1,R@z2,COLUMNSTORE@z3'`
PRIMARY_ZONE	The primary zone of the tenant. The value can be `RANDOM` or the name of a zone. `RANDOM`: specifies that the primary zone of the tenant is randomly selected from all zones where the tenant is located. This means that all zones where the tenant is located have the same priority. zone_name: specifies the primary zone of the tenant as a specific zone. If you do not specify the PRIMARY_ZONE parameter when you create a tenant, the default value is `RANDOM`.
RESOURCE_POOL_LIST	The list of resource pools allocated to the tenant. This parameter is required when you create a tenant. If multiple resource pools are specified, the `UNIT_NUM` parameter must be the same for all resource pools. Notice The `ZONE_LIST` parameter of different resource pools of the same tenant must not overlap.
ENABLE_ARBITRATION_SERVICE	Specifies whether to enable the arbitration service for the tenant. The default value is `False`. If the arbitration service is enabled in the cluster, you can enable the arbitration service for the tenant after the tenant is created. For more information, see Enable the arbitration service for a tenant.
CHARACTER SET \| CHARSET	The character set of the tenant. For more information, see Character set (MySQL mode) and Character set (Oracle mode).
COLLATE	The collation of the tenant. For more information, see Collation (MySQL mode). Note When you create a tenant in Oracle mode, you cannot specify the collation of the tenant. If you specify the collation, the syntax does not return an error, but the setting is overridden by the default collation corresponding to the character set.
READ ONLY \| READ WRITE	Specifies whether the tenant is read-only or read-write. The default value is read-write.
set_sys_var	The value of a system variable at the tenant level. For more information about `var_name`, see var_name.
COMMENT	The comment. This parameter is optional.
clone_tenant_clause	The clause for cloning a tenant.
new_tenant_name	The name of the new cloned tenant.
source_tenant_name	The name of the source tenant, which is the name of the tenant to be cloned.
resource_pool_name	The name of the resource pool. When you clone a tenant, the system automatically creates a resource pool for the new tenant based on the resource distribution of the source tenant.
unit_config	The unit specification of the resource pool of the new cloned tenant.

var_name

The following table lists the common values of var_name:

ob_compatibility_mode: specifies the compatibility mode of the tenant (MySQL or Oracle mode). This parameter can be specified only when the tenant is created. If this parameter is not specified, the default compatibility mode is MySQL.
ob_tcp_invited_nodes: specifies the IP address whitelist for connecting to the tenant. This parameter specifies the IP addresses of the clients that can connect to the tenant. In the example, % indicates that all clients can log in. If this parameter is not specified, the default value is to allow only the IP address of the local host to log in.
lower_case_table_names: specifies whether to enable case-sensitive table names. This parameter can be specified only when the tenant is created. If this parameter is not specified, the default value is to enable case-sensitive table names. This parameter is effective only in MySQL mode.
ob_compatibility_control: specifies the behavior of features that have conflicting behaviors in MySQL-compatible mode. The valid values are MYSQL5.7 and MYSQL8.0, which indicate whether to keep the behavior consistent with MySQL 5.7 or MySQL 8.0. This parameter can be specified only when the tenant is created. If this parameter is not specified, the default value is MYSQL5.7.

Examples

Create a MySQL-compatible tenant named test_tenant with the primary zone zone1;zone2,zone3, resource pool pool1, and character set utf8mb4. Allow all client IPs to connect to the database.
```
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 a MySQL-compatible tenant named tenant_c with the locality F@zone1,F@zone2,C@zone3, primary zone zone1;zone2,zone3, resource pool pool1, and character set utf8mb4. Allow all client IPs to connect to the database.

Notice

After you create a tenant that contains columnstore replicas, you must deploy ODP and configure it to route connections to the columnstore replicas. For more information, see Columnstore replicas.
```
obclient [oceanbase]> CREATE TENANT tenant_c LOCALITY = 'F@zone1,F@zone2,C@zone3', primary_zone='zone1;zone2,zone3', RESOURCE_POOL_LIST=('pool1') SET ob_tcp_invited_nodes = '%';
```

Create an Oracle-compatible tenant named tenant1 with the primary zone zone1 and resource pool pool1. Allow all client IPs to connect to the database.

obclient [oceanbase]>  CREATE TENANT tenant1 PRIMARY_ZONE='zone1', RESOURCE_POOL_LIST=('pool1') SET ob_compatibility_mode='oracle',  ob_tcp_invited_nodes='%';

Clone a tenant named clone_mysql001 from the standby tenant mysql001. Specify the resource pool name as clone_mysql001_resource_pool and the resource unit as unit001.

Notice

Log archiving must be enabled for the source tenant before you can clone it. You cannot disable log archiving for the source tenant during the execution of the tenant clone statement. For more information about log archiving, see Overview of log archiving

CREATE TENANT clone_mysql001 FROM mysql001
      WITH
      RESOURCE_POOL = clone_mysql001_resource_pool,
      UNIT = unit001;

When you execute a tenant clone statement in the sys tenant, the statement generates a clone task. You can view the execution status of the clone task by querying the DBA_OB_CLONE_PROGRESS and DBA_OB_CLONE_HISTORY views.

Here is an example:

obclient [(none)]> SELECT * FROM oceanbase.DBA_OB_CLONE_HISTORY WHERE CLONE_TENANT_NAME = 'clone_mysql001'\G

The 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.

CREATE TENANT

Purpose

Limitations and considerations

Privilege requirements

Syntax

Parameters

Notice

Note

var_name

Examples

Notice

Notice

References