Create a database

Use the influxctl database create command to create a database in your InfluxDB cluster.

1. If you haven’t already, download and install the influxctl CLI.

2. Run the influxctl database create command and provide the following:

   • Optional: Database retention period (default is infinite)
   • Optional: Database table (measurement) limit (default is 500)
   • Optional: Database column limit (default is 250)
   • Optional: InfluxDB tags to use in the partition template
   • Optional: InfluxDB tag buckets to use in the partition template
   • Optional: A Rust strftime date and time string that specifies the time format in the partition template and determines the time interval to partition by (default is %Y-%m-%d)
   • Database name (see Database naming restrictions)

   InfluxDB Clustered supports up to 7 total tags or tag buckets in the partition template.

influxctl database create \
  --retention-period 
30d
 \
  --max-tables 
500 \
  --max-columns 250 \
  --template-tag tag1 \
  --template-tag tag2 \
  --template-tag-bucket tag3,100 \
  --template-tag-bucket tag4,300 \
  --template-timeformat '%Y-%m-%d' \
  
DATABASE_NAME

• Retention period syntax
• Database naming restrictions
• InfluxQL DBRP naming convention
• Table and column limits
  • Table limit
  • Column limit
  • Custom partitioning

Retention period syntax

Use the --retention-period flag to define a specific retention period for the database. 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 (0d) retention period is infinite and data won’t expire. The retention period value cannot be negative or contain whitespace.

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

InfluxQL DBRP naming convention

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

database_name/retention_policy_name

Database naming examples

Table and column limits

In InfluxDB Clustered, table (measurement) and column limits can be configured using the --max-tables and --max-columns flags.

Table limit

Default maximum number of tables: 500

Each measurement is represented by a table in a database. Your database’s table limit can be raised beyond the default limit of 500. InfluxData has production examples of clusters with 20,000+ active tables across multiple databases.

Increasing your table limit affects your InfluxDB cluster in the following ways:

Column limit

Default maximum number of columns: 250

Time, fields, and tags are each represented by a column in a table. Increasing your column limit affects your InfluxDB cluster in the following ways:

Custom partitioning

InfluxDB Clustered lets you define a custom partitioning strategy for each database. A partition is a logical grouping of data stored in Apache Parquet format in the InfluxDB 3 storage engine. By default, data is partitioned by day, but, depending on your schema and workload, customizing the partitioning strategy can improve query performance.

Use the --template-tag, --template-tag-bucket, and –template-timeformat` flags to define partition template parts used to generate partition keys for the database. For more information, see Manage data partitioning.