This topic describes how to create a tenant by using the API.
Call description
Interface constraints
obshell Server performs security verification on this API. For details, see API hybrid encryption.
Request path
POST /api/v1/tenant
Request parameters
| Parameter | Type | Required | Example value | Description |
|---|---|---|---|---|
| name | string | Yes | t1 | Name of the tenant to create. |
| zone_list | []ZoneParam | Yes | See ZoneParam structure below. | Resource specifications and replica distribution for the tenant. |
| mode | string | No | MYSQL | Tenant type. Only MYSQL is supported. |
| primary_zone | string | No | RANDOM | Primary zone of the tenant; priority of the zone that provides read/write service. |
| whitelist | string | No | % | Access whitelist for the tenant. |
| root_password | string | No | 123456 | Root user password for the tenant. |
| scenario | string | No | kv | Workload type for the tenant. Valid values:
NoteSupported only when the OceanBase cluster is V4.3.0 or later. |
| variables | map[string]interface{} | No | { "max_connections": 1000, "ob_query_timeout": 10000000 } |
System variables for the tenant. |
| parameters | map[string]interface{} | No | { "backup_data_file_size": "2G", "arbitration_timeout": "10s" } |
Configuration items for the tenant. |
| charset | string | No | — | Character set for the tenant. |
| collation | string | No | — | Collation for the tenant. |
| read_only | bool | No | false | Whether the tenant is read-only. |
| comment | string | No | — | Comment or description for the tenant. |
| import_script | bool | No | false | Whether to import timezone and spatial metadata into the sys tenant. Default: false.
NoteSupported from obshell V4.2.4.2. |
The ZoneParam structure:
| Parameter | Type | Required | Example value | Description |
|---|---|---|---|---|
| name | string | Yes | zone1 | Zone name. |
| replica_type | string | No | FULL | Replica type in this zone: FULL (full-featured) or READONLY (read-only). Default: FULL. |
| unit_config_name | string | Yes | s1 | Resource specification for the tenant resource pool in this zone. |
| unit_num | int | Yes | 1 | Number of units for the tenant in this zone. |
Return result
| Parameter | Type | Description |
|---|---|---|
| successful | bool | Whether the request succeeded. |
| timestamp | time.Time | Time when the server completed the request. |
| duration | int | Time (ms) the server took to process the request. |
| status | int | HTTP status code. |
| traceId | string | Trace ID of the request. |
| data | DagDetailDTO | Asynchronous task information. See DagDetailDTO structure below. |
| error | ApiError | Error (if any):
|
The DagDetailDTO structure:
| Parameter | Type | Description |
|---|---|---|
| id | string | DAG common ID. |
| dag_id | int | DAG ID (primary key in OceanBase). |
| name | string | DAG name. |
| stage | int | Current execution stage of the DAG. |
| max_stage | int | Total number of stages. |
| state | string | Execution state. |
| operator | string | Execution operation type. |
| start_time | time.Time | Start time. |
| end_time | time.Time | End time. |
| additional_data | map[string]any | Additional DAG data. |
| nodes | []NodeDetailDTO | All nodes in the DAG. See Get node details. |
Examples
Request example
POST 10.10.10.1:2886/api/v1/tenant
{
"name": "t1",
"zone_list": [
{
"name": "zone1",
"unit_config_name": "s1",
"unit_num": 1
},
{
"name": "zone2",
"unit_config_name": "s1",
"unit_num": 1
},
{
"name": "zone3",
"unit_config_name": "s1",
"unit_num": 1
}
],
"mode": "MYSQL",
"read_only": false
}
Response example
{
"successful": true,
"timestamp": "2024-10-12T17:35:23.85443063+08:00",
"duration": 64,
"status": 200,
"traceId": "42ee97601d3de292",
"data": {
"id": "18",
"dag_id": 8,
"name": "Create tenant t1",
"stage": 1,
"max_stage": 3,
"state": "READY",
"operator": "RUN",
"start_time": "0001-01-01T00:00:00Z",
"end_time": "0001-01-01T00:00:00Z",
"additional_data": null,
"nodes": null
}
}
Related topics
You can also call this API via SDKs:
- obshell-sdk-python: Create a tenant
- obshell-sdk-go: Create a tenant