How to create an InfluxDB 3 Core database

Creating an InfluxDB 3 Core database gives a workload a logical storage boundary before applications, agents, or scripts write time series data. Use a separate database when data needs its own retention policy, query boundary, or migration target.

The influxdb3 CLI sends database administration requests to a running Core server, normally at http://127.0.0.1:8181 unless another host is configured. Database creation requires an admin token, and a retention period can only be chosen when the database is created in Core.

A neutral factory_metrics database with a 30-day retention period keeps the sample commands tied to one disposable workload. A successful query confirms the database exists, accepts writes, and returns data through the same authenticated CLI session.

1. Set the admin token for the current terminal session.

   $ export INFLUXDB3_AUTH_TOKEN='AUTH_TOKEN'

   Use an InfluxDB 3 Core admin token. Do not paste a real token into shared transcripts, screenshots, or shell history.

2. Create the database with the retention period chosen for this workload.

   $ influxdb3 create database --token "$INFLUXDB3_AUTH_TOKEN" --retention-period 30d factory_metrics
   Database "factory_metrics" created successfully

   Omit --retention-period or set it to none when data should not expire. In InfluxDB 3 Core, a database retention period cannot be changed after creation.

3. List databases to confirm the new name is in the catalog.

   $ influxdb3 show databases --token "$INFLUXDB3_AUTH_TOKEN"
   +-----------------+
   | iox::database   |
   +-----------------+
   | _internal       |
   | factory_metrics |
   +-----------------+

   Database names are case-sensitive, must be 64 characters or fewer, and may use letters, numbers, underscores, dashes, and forward slashes. InfluxDB 3 Core supports up to five databases.

4. Write one test point to the new database.

   $ influxdb3 write --token "$INFLUXDB3_AUTH_TOKEN" --database factory_metrics 'temperature,site=plant-1 value=22.4'
   901ms: 1 request (1.11 requests/sec), 1 lines (1 lines/s), 35B (38B/s)

   The first write creates the temperature table and uses the site tag as part of the table's primary key.

5. Query the test point from the new database.

   $ influxdb3 query --token "$INFLUXDB3_AUTH_TOKEN" --database factory_metrics 'SELECT site, value FROM temperature'
   +---------+-------+
   | site    | value |
   +---------+-------+
   | plant-1 | 22.4  |
   +---------+-------+