docs-v2/content/shared/influxdb3-cli/create/database.md

The influxdb3 create database command creates a new database in your {{< product-name >}} instance.

Provide a database name and, optionally, specify connection settings and authentication credentials using flags or environment variables.

Usage

influxdb3 create database [OPTIONS] <DATABASE_NAME>

Arguments

• DATABASE_NAME: The name of the database to create. Valid database names are alphanumeric and start with a letter or number. Dashes (-) and underscores (_) are allowed.

You can also set the database name using the INFLUXDB3_DATABASE_NAME environment variable.

Options

Option		Description
-H	--host	Host URL of the running {{< product-name >}} server (default is http://127.0.0.1:8181)
	--retention-period	Database retention period (duration value, for example: 30d, 24h, 1h)
	--token	Authentication token
	--tls-ca	Path to a custom TLS certificate authority (for testing or self-signed certificates)
-h	--help	Print help information
	--help-all	Print detailed help information

Option environment variables

You can use the following environment variables instead of providing CLI options directly:

Environment Variable	Option
INFLUXDB3_HOST_URL	--host
INFLUXDB3_AUTH_TOKEN	--token

Examples

The following examples show how to create a database.

In your commands replace the following:

• {{% code-placeholder-key %}}DATABASE_NAME{{% /code-placeholder-key %}}: Database name
• {{% code-placeholder-key %}}AUTH_TOKEN{{% /code-placeholder-key %}}: Authentication token

{{% code-placeholders "DATABASE_NAME|AUTH_TOKEN" %}}

Create a database (default)

Creates a database using settings from environment variables and defaults.

influxdb3 create database DATABASE_NAME

Create a database with an authentication token

Creates a database using the specified arguments. Flags override their associated environment variables.

influxdb3 create database --token AUTH_TOKEN DATABASE_NAME

Create a database with a retention period

Creates a database with a 30-day retention period. Data older than 30 days will not be queryable.

influxdb3 create database --retention-period 30d DATABASE_NAME

Create a database with infinite retention

Creates a database with no retention period (data never expires).

influxdb3 create database --retention-period none DATABASE_NAME

Create a database with a 90-day retention period

Creates a database with a 90-day retention period using an authentication token.

influxdb3 create database \
  --retention-period 90d \
  --token AUTH_TOKEN \
  DATABASE_NAME

Create a database with a 1-year retention period

Creates a database with a 1-year retention period.

influxdb3 create database --retention-period 1y DATABASE_NAME

Create a database with a combined duration

Creates a database with a retention period of 30 days and 12 hours.

influxdb3 create database --retention-period 30d12h DATABASE_NAME

{{% /code-placeholders %}}

Retention period duration formats

Retention periods are specified as duration values using a numeric value plus a duration unit.

Valid duration units

Unit	Description
h	hour
d	day
w	week
mo	month (30 days)
y	year (365 days)

[!Note]

• Minimum for data retention: The practical minimum retention period is 1 hour (1h). Setting 0<unit> (for example, 0d) marks all data for immediate deletion.
• Unsupported units: Minute (m) and second (s) units are not supported.

Example duration values

• 1h - 1 hour
• 24h - 24 hours
• 7d - 7 days
• 4w - 4 weeks
• 30d - 30 days
• 1mo - 1 month (30 days)
• 90d - 90 days
• 1y - 1 year (365 days)
• none - infinite (data never expires)

You can combine units: 30d12h (30.5 days), 1y6mo (545 days)

For complete details about retention periods, see Data retention in {{< product-name >}}.