Create a database

Use the influxdb3 create database command, the HTTP API, or InfluxDB 3 Explorer to create a database in InfluxDB 3 Enterprise.

• Create a database using the influxdb3 CLI
• Create a database using the HTTP API
• Create a database using InfluxDB 3 Explorer
• Retention period
• Database naming restrictions
• InfluxQL DBRP naming convention
• Database limit

Create a database using the influxdb3 CLI

Use the influxdb3 create database command to create a database. Provide the following:

• Database name (see Database naming restrictions)
• InfluxDB 3 Enterprise admin token
• (Optional) Retention period. If omitted, data doesn’t expire.

# 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

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
• Request body (JSON object):
  • db (string, required): Database name
  • retention_period (string, optional): Retention period. If omitted, data doesn’t expire.

# 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

Response

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

Create a database using InfluxDB 3 Explorer

Use the InfluxDB 3 Explorer web interface to create a database in InfluxDB 3 Enterprise:

1. If you haven’t already, see how to get started with Explorer and connect to your InfluxDB 3 Enterprise server.
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.

• Retention period
• Database naming restrictions
• InfluxQL DBRP naming convention
• 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

For more information about retention periods, see 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

Valid database name examples

mydb
sensor_data
prod-metrics
logs/application
webserver123

Invalid database name examples

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.

InfluxQL DBRP naming convention

In InfluxDB 1.x, data is stored in databases and retention policies. In InfluxDB 3 Enterprise, 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 Enterprise database:

database_name/retention_policy_name

Database naming examples

Database limit

Default maximum number of databases: 100

For more information about InfluxDB 3 Enterprise database, table, and column limits, see Database, table, and column limits.