--- title: Databases description: Create and manage databases in an InfluxDB 3 Clustered cluster, including setting retention periods and custom partition templates. url: https://docs.influxdata.com/influxdb3/clustered/api/management-api/databases/ estimated_tokens: 3719 publisher: InfluxData canonical: https://docs.influxdata.com/influxdb3/clustered/api/management-api/databases/ --- [Download Clustered Management API Spec](/openapi/influxdb-clustered-management-api.yml) Create and manage databases in an InfluxDB 3 Clustered cluster, including setting retention periods and custom partition templates. GET`/databases` ### Get all databases for a cluster Example request[Ask AI about this](#) ```sh curl --request GET \ "https://console.influxdata.com/api/v0/databases" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200The cluster databases were successfully retrieved 400Bad Request `code`requiredinteger `message`requiredstring 401Unauthorized `code`requiredinteger `message`requiredstring 403Forbidden `code`requiredinteger `message`requiredstring 404Not Found `code`requiredinteger `message`requiredstring 500Internal Server Error `code`requiredinteger `message`requiredstring POST`/databases` ### Create a database #### Request bodyrequired Content-Type:`application/json` `maxColumnsPerTable`integer \ The maximum number of columns per table for the cluster database Default:`200` `maxTables`integer \ The maximum number of tables for the cluster database Default:`500` `name`requiredstring The name of the cluster database `partitionTemplate`object[] A template for partitioning a cluster database. Each template part is evaluated in sequence, concatinating the final partition key from the output of each part, delimited by the partition key delimiter `|`. For example, using the partition template below: ```json [ { "type": "time", "value": "%Y" }, { "type": "tag", "value": "bananas" }, { "type": "tag", "value": "plátanos" }, { "type": "bucket", "value": { "tagName": "c", "numberOfBuckets": 10 } } ] ``` The following partition keys are derived: * `time=2023-01-01, a=bananas, b=plátanos, c=ananas` -\> `2023|bananas|plátanos|5` * `time=2023-01-01, b=plátanos` -\> `2023|!|plátanos|!` * `time=2023-01-01, another=cat, b=plátanos` -\> `2023|!|plátanos|!` * `time=2023-01-01` -\> `2023|!|!|!` * `time=2023-01-01, a=cat|dog, b=!, c=!` -\> `2023|cat%7Cdog|%21|8` * `time=2023-01-01, a=%50, c=%50` -\> `2023|%2550|!|9` * `time=2023-01-01, a=, c=` -\> `2023|^|!|0` * `time=2023-01-01, a=` -\> `2023|#|!|!` * `time=2023-01-01, c=` -\> `2023|!|!|` When using the default partitioning template (YYYY-MM-DD) there is no encoding necessary, as the derived partition key contains a single part, and no reserved characters. [`TemplatePart::Bucket`] parts by definition will always be within the part length limit and contain no restricted characters so are also not percent-encoded and/or truncated. `retentionPeriod`integer \ The retention period of the cluster database in nanoseconds, if applicable If the retention period is not set or is set to 0, the database will have infinite retention Example request[Ask AI about this](#) ```sh curl --request POST \ "https://console.influxdata.com/api/v0/databases" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "maxColumnsPerTable": 200, "maxTables": 500, "name": "NAME", "partitionTemplate": [ "PARTITIONTEMPLATE" ], "retentionPeriod": 0 }' ``` #### Responses 200The cluster database was successfully created `maxColumnsPerTable`requiredinteger \ The maximum number of columns per table for the cluster database Default:`200` `maxTables`requiredinteger \ The maximum number of tables for the cluster database Default:`500` `name`requiredstring The name of the cluster database `partitionTemplate`object[] A template for partitioning a cluster database. Each template part is evaluated in sequence, concatinating the final partition key from the output of each part, delimited by the partition key delimiter `|`. For example, using the partition template below: ```json [ { "type": "time", "value": "%Y" }, { "type": "tag", "value": "bananas" }, { "type": "tag", "value": "plátanos" }, { "type": "bucket", "value": { "tagName": "c", "numberOfBuckets": 10 } } ] ``` The following partition keys are derived: * `time=2023-01-01, a=bananas, b=plátanos, c=ananas` -\> `2023|bananas|plátanos|5` * `time=2023-01-01, b=plátanos` -\> `2023|!|plátanos|!` * `time=2023-01-01, another=cat, b=plátanos` -\> `2023|!|plátanos|!` * `time=2023-01-01` -\> `2023|!|!|!` * `time=2023-01-01, a=cat|dog, b=!, c=!` -\> `2023|cat%7Cdog|%21|8` * `time=2023-01-01, a=%50, c=%50` -\> `2023|%2550|!|9` * `time=2023-01-01, a=, c=` -\> `2023|^|!|0` * `time=2023-01-01, a=` -\> `2023|#|!|!` * `time=2023-01-01, c=` -\> `2023|!|!|` When using the default partitioning template (YYYY-MM-DD) there is no encoding necessary, as the derived partition key contains a single part, and no reserved characters. [`TemplatePart::Bucket`] parts by definition will always be within the part length limit and contain no restricted characters so are also not percent-encoded and/or truncated. `retentionPeriod`requiredinteger \ The retention period of the cluster database in nanoseconds, if applicable If the retention period is not set or is set to 0, the database will have infinite retention 400Bad Request `code`requiredinteger `message`requiredstring 401Unauthorized `code`requiredinteger `message`requiredstring 403Forbidden `code`requiredinteger `message`requiredstring 404Not Found `code`requiredinteger `message`requiredstring 409Conflict `code`requiredinteger `message`requiredstring 500Internal Server Error `code`requiredinteger `message`requiredstring PUT`/databases/{databaseId}/undelete` ### Undelete a database Restores a previously deleted database. This operation can only be performed on databases that have been soft-deleted and are still within the recovery window. #### Parameters ##### Path parameters `databaseId`requiredstring The ID of the database to undelete Example request[Ask AI about this](#) ```sh curl --request PUT \ "https://console.influxdata.com/api/v0/databases/{databaseId}/undelete" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200The cluster database was successfully undeleted `id`requiredinteger \ The ID of the cluster database `maxColumnsPerTable`requiredinteger \ The maximum number of columns per table for the cluster database Default:`200` `maxTables`requiredinteger \ The maximum number of tables for the cluster database Default:`500` `name`requiredstring The name of the cluster database `partitionTemplate`object[] A template for partitioning a cluster database. Each template part is evaluated in sequence, concatinating the final partition key from the output of each part, delimited by the partition key delimiter `|`. For example, using the partition template below: ```json [ { "type": "time", "value": "%Y" }, { "type": "tag", "value": "bananas" }, { "type": "tag", "value": "plátanos" }, { "type": "bucket", "value": { "tagName": "c", "numberOfBuckets": 10 } } ] ``` The following partition keys are derived: * `time=2023-01-01, a=bananas, b=plátanos, c=ananas` -\> `2023|bananas|plátanos|5` * `time=2023-01-01, b=plátanos` -\> `2023|!|plátanos|!` * `time=2023-01-01, another=cat, b=plátanos` -\> `2023|!|plátanos|!` * `time=2023-01-01` -\> `2023|!|!|!` * `time=2023-01-01, a=cat|dog, b=!, c=!` -\> `2023|cat%7Cdog|%21|8` * `time=2023-01-01, a=%50, c=%50` -\> `2023|%2550|!|9` * `time=2023-01-01, a=, c=` -\> `2023|^|!|0` * `time=2023-01-01, a=` -\> `2023|#|!|!` * `time=2023-01-01, c=` -\> `2023|!|!|` When using the default partitioning template (YYYY-MM-DD) there is no encoding necessary, as the derived partition key contains a single part, and no reserved characters. [`TemplatePart::Bucket`] parts by definition will always be within the part length limit and contain no restricted characters so are also not percent-encoded and/or truncated. `retentionPeriod`integer \ The retention period of the cluster database in nanoseconds, if applicable If the retention period is not set or is set to 0, the database will have infinite retention 400Bad Request `code`requiredinteger `message`requiredstring 401Unauthorized `code`requiredinteger `message`requiredstring 403Forbidden `code`requiredinteger `message`requiredstring 404Not Found `code`requiredinteger `message`requiredstring 500Internal Server Error `code`requiredinteger `message`requiredstring PATCH`/databases/{databaseName}` ### Update a database #### Parameters ##### Path parameters `databaseName`requiredstring The name of the database to update #### Request bodyrequired Content-Type:`application/json` `maxColumnsPerTable`integer \ The maximum number of columns per table for the cluster database Default:`200` `maxTables`integer \ The maximum number of tables for the cluster database Default:`500` `retentionPeriod`integer \ The retention period of the cluster database in nanoseconds, if applicable If the retention period is not set or is set to 0, the database will have infinite retention Example request[Ask AI about this](#) ```sh curl --request PATCH \ "https://console.influxdata.com/api/v0/databases/{databaseName}" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "maxColumnsPerTable": 200, "maxTables": 500, "retentionPeriod": 0 }' ``` #### Responses 200The cluster database was successfully updated. `maxColumnsPerTable`requiredinteger \ The maximum number of columns per table for the cluster database Default:`200` `maxTables`requiredinteger \ The maximum number of tables for the cluster database Default:`500` `name`requiredstring The name of the cluster database `retentionPeriod`requiredinteger \ The retention period of the cluster database in nanoseconds, if applicable If the retention period is not set or is set to 0, the database will have infinite retention 400Bad Request `code`requiredinteger `message`requiredstring 401Unauthorized `code`requiredinteger `message`requiredstring 403Forbidden `code`requiredinteger `message`requiredstring 404Not Found `code`requiredinteger `message`requiredstring 500Internal Server Error `code`requiredinteger `message`requiredstring DELETE`/databases/{databaseName}` ### Delete a database #### Parameters ##### Path parameters `databaseName`requiredstring The name of the database to delete Example request[Ask AI about this](#) ```sh curl --request DELETE \ "https://console.influxdata.com/api/v0/databases/{databaseName}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204No Content 400Bad Request `code`requiredinteger `message`requiredstring 401Unauthorized `code`requiredinteger `message`requiredstring 403Forbidden `code`requiredinteger `message`requiredstring 404Not Found `code`requiredinteger `message`requiredstring 500Internal Server Error `code`requiredinteger `message`requiredstring PUT`/databases/{databaseName}/rename` ### Rename a database Renames an existing database. This operation can only be performed on databases that are currently active. #### Parameters ##### Path parameters `databaseName`requiredstring The name of the database to rename #### Request bodyrequired Content-Type:`application/json` `name`requiredstring The name of the cluster database Example request[Ask AI about this](#) ```sh curl --request PUT \ "https://console.influxdata.com/api/v0/databases/{databaseName}/rename" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "name": "NAME" }' ``` #### Responses 200The cluster database was successfully renamed `id`requiredinteger \ The ID of the cluster database `maxColumnsPerTable`requiredinteger \ The maximum number of columns per table for the cluster database Default:`200` `maxTables`requiredinteger \ The maximum number of tables for the cluster database Default:`500` `name`requiredstring The name of the cluster database `partitionTemplate`object[] A template for partitioning a cluster database. Each template part is evaluated in sequence, concatinating the final partition key from the output of each part, delimited by the partition key delimiter `|`. For example, using the partition template below: ```json [ { "type": "time", "value": "%Y" }, { "type": "tag", "value": "bananas" }, { "type": "tag", "value": "plátanos" }, { "type": "bucket", "value": { "tagName": "c", "numberOfBuckets": 10 } } ] ``` The following partition keys are derived: * `time=2023-01-01, a=bananas, b=plátanos, c=ananas` -\> `2023|bananas|plátanos|5` * `time=2023-01-01, b=plátanos` -\> `2023|!|plátanos|!` * `time=2023-01-01, another=cat, b=plátanos` -\> `2023|!|plátanos|!` * `time=2023-01-01` -\> `2023|!|!|!` * `time=2023-01-01, a=cat|dog, b=!, c=!` -\> `2023|cat%7Cdog|%21|8` * `time=2023-01-01, a=%50, c=%50` -\> `2023|%2550|!|9` * `time=2023-01-01, a=, c=` -\> `2023|^|!|0` * `time=2023-01-01, a=` -\> `2023|#|!|!` * `time=2023-01-01, c=` -\> `2023|!|!|` When using the default partitioning template (YYYY-MM-DD) there is no encoding necessary, as the derived partition key contains a single part, and no reserved characters. [`TemplatePart::Bucket`] parts by definition will always be within the part length limit and contain no restricted characters so are also not percent-encoded and/or truncated. `retentionPeriod`integer \ The retention period of the cluster database in nanoseconds, if applicable If the retention period is not set or is set to 0, the database will have infinite retention 400Bad Request `code`requiredinteger `message`requiredstring 401Unauthorized `code`requiredinteger `message`requiredstring 403Forbidden `code`requiredinteger `message`requiredstring 404Not Found `code`requiredinteger `message`requiredstring 409Conflict `code`requiredinteger `message`requiredstring 500Internal Server Error `code`requiredinteger `message`requiredstring #### Related * [Manage databases](/influxdb3/clustered/admin/databases/) * [Custom partitions](/influxdb3/clustered/admin/custom-partitions/) * [InfluxDB 3 API client libraries](/influxdb3/clustered/reference/client-libraries/v3/)