influxctl database create
The influxctl database create command creates a new database with a specified
retention period in an InfluxDB cluster.
The retention period defines the maximum age of data retained in the database,
based on the timestamp of the data.
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.
A zero duration retention period is infinite and data will not expire.
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
Example retention period values
0d: infinite/none3d: 3 days6w: 6 weeks1mo: 1 month (30 days)1y: 1 year30d30d: 60 days2.5d: 60 hours
Custom partitioning
You can override the default partition template (%Y-%m-%d) of the database
with the --template-tag, --template-tag-bucket, and --template-timeformat
flags when you create the database.
Provide a time format using Rust strftime, partition by specific tag, or partition tag values
into a specified number of “buckets.”
Each of these can be used as part of the partition template.
Be sure to follow partitioning best practices.
Always provide a time format when using custom partitioning
If defining a custom partition template for your database with any of the
--template-* flags, always include the --template-timeformat flag with a
time format to use in your partition template.
Otherwise, InfluxDB omits time from the partition template and won’t compact partitions.
Cannot reuse deleted database names
You cannot reuse the name of a deleted database when creating a new database.
If you try to reuse the name, the API response status code
is 400 and the message field contains the following:
'iox_proxy.app.CreateDatabase failed to create database: \
rpc error: code = AlreadyExists desc = A namespace with the
name `<DATABASE_NAME>` already exists'
Usage
influxctl database create [flags] <DATABASE_NAME>
Arguments
| Argument | Description |
|---|---|
| DATABASE_NAME | InfluxDB database name |
Flags
| Flag | Description | |
|---|---|---|
--retention-period | Database retention period (default is 0s, infinite) | |
--max-tables | Maximum tables per database (default is 500, 0 uses default) | |
--max-columns | Maximum columns per table (default is 250, 0 uses default) | |
--template-tag | Tag to add to partition template (can include multiple of this flag) | |
--template-tag-bucket | Tag and number of buckets to partition tag values into separated by a comma–for example: tag1,100 (can include multiple of this flag) | |
--template-timeformat | Timestamp format for partition template (default is %Y-%m-%d) | |
-h | --help | Output command help |
Also see influxctl global flags.
Examples
- Create a database with an infinite retention period
- Create a database with a 30-day retention period
- Create a database with non-default table and column limits
- Create a database with a custom partition template
Create a database with an infinite retention period
influxctl database create mydb
Create a database with a 30-day retention period
influxctl database create \
--retention-period 30d \
mydb
Create a database with non-default table and column limits
influxctl database create \
--max-tables 200 \
--max-columns 150 \
mydb
Create a database with a custom partition template
The following example creates a new mydb database and applies a partition
template that partitions by two tags (room and sensor-type) and by week using
the time format %Y wk:%W:
influxctl database create \
--template-tag room \
--template-tag sensor-type \
--template-tag-bucket customerID,1000 \
--template-timeformat '%Y wk:%W' \
mydb
For more information about custom partitioning, see Manage data partitioning.
Was this page helpful?
Thank you for your feedback!
Support and feedback
Thank you for being part of our community! We welcome and encourage your feedback and bug reports for InfluxDB and this documentation. To find support, use the following resources:
Customers with an annual or support contract can contact InfluxData Support.