---
title: Create a database
description: Use the influxdb3 CLI, HTTP API, or InfluxDB 3 Explorer to create a new database in InfluxDB 3 Core.
url: https://docs.influxdata.com/influxdb3/core/admin/databases/create/
estimated_tokens: 2599
product: InfluxDB 3 Core
version: core
publisher: InfluxData
canonical: https://docs.influxdata.com/influxdb3/core/admin/databases/create/
date: '2026-04-20T11:26:19-05:00'
lastmod: '2026-04-20T11:26:19-05:00'
---

Use the [`influxdb3 create database` command](/influxdb3/core/reference/cli/influxdb3/create/database/),
the [HTTP API](/influxdb3/core/api/v3/), or [InfluxDB 3 Explorer](/influxdb3/explorer/)to create a database in InfluxDB 3 Core.

* [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)
* [Create a database using InfluxDB 3 Explorer](#create-a-database-using-influxdb-3-explorer)
* [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/core/reference/cli/influxdb3/create/database/)to create a database. Provide the following:

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

* InfluxDB 3 Core [admin token](/influxdb3/core/admin/tokens/admin)

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

#### Retention periods are immutable in Core

In InfluxDB 3 Core, retention periods can only be set when creating a database
and cannot be changed afterward. If you need to change a retention period, you must
create a new database with the desired retention period and migrate your data.

```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/core/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 localhost:8181/api/v3/configure/database
```

Include the following in your request:

* **Headers**:

  * `Content-Type: application/json`
  * `Authorization: Bearer` with your [admin token](/influxdb3/core/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.

#### Retention periods are immutable in Core

In InfluxDB 3 Core, retention periods can only be set when creating a database
and cannot be changed afterward. If you need to change a retention period, you must
create a new database with the desired retention period and migrate your data.

```bash
# Create a database with a 30-day retention period
curl --request POST "localhost:8181/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 "localhost:8181/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 "localhost:8181/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/core/admin/tokens/)

### Response

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

## Create a database using InfluxDB 3 Explorer

> [!Caution]
> Currently, you can’t set a retention period when creating a database in Explorer.
> To create a database with a retention period, see one of the following:
> * [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)

* [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 periods are immutable in Core

After creating a database in InfluxDB 3 Core, you cannot change its retention period.

Use the [InfluxDB 3 Explorer](/influxdb3/explorer/) web interface to create a database in InfluxDB 3 Core:

1. If you haven’t already, see how to [get started with Explorer and connect to your InfluxDB 3 Core server](/influxdb3/explorer/get-started/).
2. In Explorer, click **Manage Databases** in the left navigation.
3. Click **+ Create New**.
4. Enter a database name.
5. Click **Create Database**.

For more information, see [Manage databases with InfluxDB 3 Explorer](/influxdb3/explorer/manage-databases/).

* [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/core/reference/internals/data-retention/).

#### Retention periods are immutable in Core

In InfluxDB 3 Core, retention periods can only be set when creating a database
and cannot be changed afterward. If you need to change a retention period, you must
create a new database with the desired retention period and migrate your data.

For mutable retention periods and table-level retention, consider upgrading to[InfluxDB 3 Enterprise](/influxdb3/enterprise/).

## 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 Core 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/core/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 Core, 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 Core 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

**Maximum number of databases**: 5

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

#### Related

* [influxdb3 create database](/influxdb3/core/reference/cli/influxdb3/create/database/)
* [Create database API](/influxdb3/core/api/database/#operation/PostConfigureDatabase)
* [Naming restrictions and conventions](/influxdb3/core/reference/naming-restrictions/)
* [Data retention in InfluxDB 3 Core](/influxdb3/core/reference/internals/data-retention/)
* [Manage databases with InfluxDB 3 Explorer](/influxdb3/explorer/manage-databases/)
| 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 |