Create database¶

Create a database under the specified Catalog.

HTTP
POST $CLOUDSIGMA_API_BASE/catalog/database/create

Before you call this API¶

Configure the regional API endpoint and authentication, and select the target workspace.

First query the catalog list to obtain the parent catalog ID.

Set the operation-specific values used in the request:

$CATALOG_ID: The parent catalog ID under which the database is to be created.

Request¶

Input examples

Shell
curl -X POST "$CLOUDSIGMA_API_BASE/catalog/database/create" \
  -H "X-API-Key: $CLOUDSIGMA_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "catalog_id": '"$CATALOG_ID"',
    "name": "<DATABASE_NAME>",
    "description": "<DATABASE_DESCRIPTION>"
  }'

Parameter reference

Request body

Parameter	Type	Required	Description
`catalog_id`	integer	Yes	The parent Catalog ID.
`name`	string	Yes	Database name, must be a valid identifier.
`description`	string	No	Database description.

Successful response¶

Returns 200 on success. Save data.id for subsequent operations.

Response example

JSON
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "id": 2
  }
}

Field reference

The response fields are as follows.

Field	Type	Description
`code`	string	`OK` on success.
`msg`	string	`OK` on success.
`data.id`	integer or null	Create a new database ID; if not provided by the server, it is `null`.

Error response¶

Response example

JSON
{
  "code": "ErrAlreadyExists",
  "msg": "数据库名称已存在",
  "data": null
}

Field reference

Common HTTP errors¶

HTTP status code	error code	Common causes	Recommended actions
`400`	`ErrParamInvalid`	The request field is missing, or the name is not a valid identifier.	Check `catalog_id` and `name`.
`403`	`ErrForbidden`	The current identity does not have the permission to create a database in the parent Catalog.	Requesting permission to `database.create`.
`409`	`ErrAlreadyExists`	There is already a database with the same name in the parent Catalog.	Change the name.
`409`	`ErrReadonlySystemCatalog`、`ErrReadonlySystemDatabase`	The parent object is a read-only system object.	Select Writable Catalog.
`500`	`ErrServer`	The server failed to create the database.	Try again later.

Follow-up operations¶

Use data.id Query database details.

Last updated on Sep 15, 2026