---
title: Create a database
description: Use the influxdb3 CLI or HTTP API to create a new database in InfluxDB 3 Cloud.
url: https://docs.influxdata.com/influxdb3/cloud/admin/databases/create/
estimated_tokens: 1948
product: InfluxDB 3 Cloud
version: cloud
publisher: InfluxData
canonical: https://docs.influxdata.com/influxdb3/cloud/admin/databases/create/
date: '2026-07-16T15:18:32-05:00'
lastmod: '2026-07-16T15:18:32-05:00'
---

Use the [`influxdb3 create database` command](/influxdb3/cloud/reference/cli/influxdb3/create/database/),
the [HTTP API](/influxdb3/cloud/api/v3/)

to create a database in InfluxDB 3 Cloud.

* [Create a database using the influxdb3 CLI](#create-a-database-using-the-influxdb3-cli)

* [Create a database using the HTTP API](#create-a-database-using-the-http-api)

* [Retention period](#retention-period)

* [Database naming restrictions](#database-naming-restrictions)

* [InfluxQL DBRP naming convention](#influxql-dbrp-naming-convention)

* [Database limit](#database-limit)

## Create a database using the influxdb3 CLI

Use the [`influxdb3 create database` command](/influxdb3/cloud/reference/cli/influxdb3/create/database/)to create a database. Provide the following:

* Database name *(see [Database naming restrictions](#database-naming-restrictions))*

* InfluxDB 3 Cloud [admin token](/influxdb3/cloud/admin/tokens/admin)

* *(Optional)* [Retention period](#retention-period). If omitted, data doesn’t expire.

```sh
# Create a database with a 30-day retention period
influxdb3 create database --retention-period 30d DATABASE_NAME

# Create a database with a 90-day retention period using authentication
influxdb3 create database \
  --retention-period 90d \
  --token AUTH_TOKEN \
  DATABASE_NAME

# Create a database with infinite retention (default)
influxdb3 create database DATABASE_NAME
```

Replace the following:

* `DATABASE_NAME`: the name of the database to create
* `AUTH_TOKEN`: your [admin token](/influxdb3/cloud/admin/tokens/)

## Create a database using the HTTP API

To create a database using the HTTP API, send a `POST` request to the `/api/v3/configure/database` endpoint:

```
POST https://instance-id.enterprise.influxdb.io/api/v3/configure/database
```

Include the following in your request:

* **Headers**:

  * `Content-Type: application/json`
  * `Authorization: Bearer` with your [admin token](/influxdb3/cloud/admin/tokens/)

* **Request body** (JSON object):

  * `db` *(string, required)*: Database name
  * `retention_period` *(string, optional)*: [Retention period](#retention-period). If omitted, data doesn’t expire.

```bash
# Create a database with a 30-day retention period
curl --request POST "https://instance-id.enterprise.influxdb.io/api/v3/configure/database" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer AUTH_TOKEN" \
  --data '{
    "db": "DATABASE_NAME",
    "retention_period": "30d"
  }'

# Create a database with a 90-day retention period
curl --request POST "https://instance-id.enterprise.influxdb.io/api/v3/configure/database" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer AUTH_TOKEN" \
  --data '{
    "db": "DATABASE_NAME",
    "retention_period": "90d"
  }'

# Create a database with infinite retention (default)
curl --request POST "https://instance-id.enterprise.influxdb.io/api/v3/configure/database" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer AUTH_TOKEN" \
  --data '{
    "db": "DATABASE_NAME"
  }'
```

Replace the following:

* `DATABASE_NAME`: the name of the database to create
* `AUTH_TOKEN`: your [admin token](/influxdb3/cloud/admin/tokens/)

### Response

A successful request returns HTTP status `200` with the database configuration.

* [Retention period](#retention-period)
* [Database naming restrictions](#database-naming-restrictions)
* [InfluxQL DBRP naming convention](#influxql-dbrp-naming-convention)
* [Database limit](#database-limit)

## Retention period

By default, data does not expire. When creating a database, set a *retention period* to automatically delete expired data and optimize storage.

### Retention period syntax

The retention period value is a time duration value made up of a numeric value
plus a duration unit.
For example, `30d` means 30 days.
The retention period value cannot be negative or contain whitespace.

#### Valid durations units include

* **m**: minute
* **h**: hour
* **d**: day
* **w**: week
* **mo**: month
* **y**: year

#### Retention period constraints

* **Minimum for data retention**: The practical minimum retention period is 1 hour (`1h`).
* **Zero-duration periods**: Setting a retention period to `0<unit>` (for example,`0d` or `0h`) is allowed but marks all data for immediate deletion at query time.*This differs from InfluxDB 1.x and 2.x where `0d` meant infinite retention.*
* **Infinite retention**: Use `none` to set an infinite retention period.

For more information about retention periods, see [Data retention](/influxdb3/cloud/reference/internals/data-retention/).

## Database naming restrictions

Database names must adhere to the following naming restrictions:

* **Length**: Maximum 64 characters
* **Allowed characters**: Alphanumeric characters (a-z, A-Z, 0-9), underscore (`_`), dash (`-`), and forward-slash (`/`)
* **Prohibited characters**: Cannot contain whitespace, punctuation, or other special characters
* **Starting character**: Should start with a letter or number and should not start with underscore (`_`)
* **Case sensitivity**: Database names are case-sensitive

#### Underscore prefix reserved for system use

Names starting with an underscore (`_`) may be reserved for InfluxDB system use.
While InfluxDB 3 Cloud might not explicitly reject these names, using them risks
conflicts with current or future system features and may result in
unexpected behavior or data loss.

### Valid database name examples

```text
mydb
sensor_data
prod-metrics
logs/application
webserver123
```

### Invalid database name examples

```text
my database        # Contains whitespace
sensor.data        # Contains period
app@server         # Contains special character
_internal          # Starts with underscore (reserved)
very_long_database_name_that_exceeds_sixty_four_character_limit  # Too long
```

For comprehensive information about naming restrictions for all InfluxDB identifiers,
see [Naming restrictions and conventions](/influxdb3/cloud/reference/naming-restrictions/).

## InfluxQL DBRP naming convention

In InfluxDB 1.x, data is stored in [databases](/influxdb/v1/concepts/glossary/#database)and [retention policies](/influxdb/v1/concepts/glossary/#retention-policy-rp).
In InfluxDB 3 Cloud, databases and retention policies have been merged into*databases*, where databases have a retention period, but retention policies
are no longer part of the data model.
Because InfluxQL uses the 1.x data model, a database must be mapped to a v1
database and retention policy (DBRP) to be queryable with InfluxQL.

**When naming a database that you want to query with InfluxQL**, use the following
naming convention to automatically map v1 DBRP combinations to an InfluxDB 3 Cloud database:

```text
database_name/retention_policy_name
```

##### Database naming examples

|v1 Database name|v1 Retention Policy name|    New database name    |
|----------------|------------------------|-------------------------|
|       db       |           rp           |          db/rp          |
|    telegraf    |        autogen         |    telegraf/autogen     |
|   webmetrics   |     1w-downsampled     |webmetrics/1w-downsampled|

## Database limit

*For more information about InfluxDB 3 Cloud database, table, and column limits,
see [Database, table, and column limits](/influxdb3/cloud/admin/databases/#database-table-and-column-limits).*

#### Related

* [Create database API](/influxdb3/cloud/api/database/#operation/PostConfigureDatabase)
| v1 Database name | v1 Retention Policy name | New database name |
| --- | --- | --- |
| v1 Database name | v1 Retention Policy name | New database name |
| db | rp | db/rp |
| telegraf | autogen | telegraf/autogen |
| webmetrics | 1w-downsampled | webmetrics/1w-downsampled |