165 lines
5.4 KiB
Markdown
165 lines
5.4 KiB
Markdown
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
|
|
|
|
<!--pytest.mark.skip-->
|
|
|
|
```bash
|
|
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](/influxdb3/version/reference/glossary/#retention-period) ([duration](/influxdb3/version/reference/glossary/#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.
|
|
|
|
<!--pytest.mark.skip-->
|
|
|
|
```bash
|
|
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.
|
|
|
|
<!--pytest.mark.skip-->
|
|
|
|
```bash
|
|
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.
|
|
|
|
<!--pytest.mark.skip-->
|
|
|
|
```bash
|
|
influxdb3 create database --retention-period 30d DATABASE_NAME
|
|
```
|
|
|
|
### Create a database with infinite retention
|
|
|
|
Creates a database with no retention period (data never expires).
|
|
|
|
<!--pytest.mark.skip-->
|
|
|
|
```bash
|
|
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.
|
|
|
|
<!--pytest.mark.skip-->
|
|
|
|
```bash
|
|
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.
|
|
|
|
<!--pytest.mark.skip-->
|
|
|
|
```bash
|
|
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.
|
|
|
|
<!--pytest.mark.skip-->
|
|
|
|
```bash
|
|
influxdb3 create database --retention-period 30d12h DATABASE_NAME
|
|
```
|
|
|
|
{{% /code-placeholders %}}
|
|
|
|
## Retention period duration formats
|
|
|
|
Retention periods are specified as [duration](/influxdb3/version/reference/glossary/#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 >}}](/influxdb3/version/reference/internals/data-retention/).
|