|
1 | 1 | --- |
2 | 2 | title: influxctl database create |
3 | 3 | description: > |
4 | | - The `influxctl database create` command creates a new database in an InfluxDB |
5 | | - Cloud Dedicated cluster. |
| 4 | + The `influxctl database create` command creates a new database in an |
| 5 | + {{% product-name omit=" Clustered" %}} cluster. |
6 | 6 | menu: |
7 | 7 | influxdb3_cloud_dedicated: |
8 | 8 | parent: influxctl database |
9 | 9 | weight: 301 |
10 | 10 | related: |
11 | 11 | - /influxdb3/cloud-dedicated/admin/custom-partitions/define-custom-partitions/ |
12 | 12 | - /influxdb3/cloud-dedicated/admin/custom-partitions/partition-templates/ |
| 13 | +source: /shared/influxctl/database/create.md |
13 | 14 | --- |
14 | 15 |
|
15 | | -The `influxctl database create` command creates a new database with a specified |
16 | | -retention period in an {{< product-name omit=" Clustered" >}} cluster. |
17 | | - |
18 | | -The retention period defines the maximum age of data retained in the database, |
19 | | -based on the timestamp of the data. |
20 | | -The retention period value is a time duration value made up of a numeric value |
21 | | -plus a duration unit. For example, `30d` means 30 days. |
22 | | -A zero duration retention period is infinite and data will not expire. |
23 | | -The retention period value cannot be negative or contain whitespace. |
24 | | - |
25 | | -{{< flex >}} |
26 | | -{{% flex-content "half" %}} |
27 | | - |
28 | | -##### Valid durations units include |
29 | | - |
30 | | -- **m**: minute |
31 | | -- **h**: hour |
32 | | -- **d**: day |
33 | | -- **w**: week |
34 | | -- **mo**: month |
35 | | -- **y**: year |
36 | | - |
37 | | -{{% /flex-content %}} |
38 | | -{{% flex-content "half" %}} |
39 | | - |
40 | | -##### Example retention period values |
41 | | - |
42 | | -- `0d`: infinite/none |
43 | | -- `3d`: 3 days |
44 | | -- `6w`: 6 weeks |
45 | | -- `1mo`: 1 month (30 days) |
46 | | -- `1y`: 1 year |
47 | | -- `30d30d`: 60 days |
48 | | -- `2.5d`: 60 hours |
49 | | - |
50 | | -{{% /flex-content %}} |
51 | | -{{< /flex >}} |
52 | | - |
53 | | -#### Custom partitioning |
54 | | - |
55 | | -You can override the default partition template (`%Y-%m-%d`) of the database |
56 | | -with the `--template-tag`, `--template-tag-bucket`, and `--template-timeformat` |
57 | | -flags when you create the database. |
58 | | -Provide a time format using [Rust strftime](/influxdb3/cloud-dedicated/admin/custom-partitions/partition-templates/#time-part-templates), partition by specific tag, or partition tag values |
59 | | -into a specified number of "buckets." |
60 | | -Each of these can be used as part of the partition template. |
61 | | -Be sure to follow [partitioning best practices](/influxdb3/cloud-dedicated/admin/custom-partitions/best-practices/). |
62 | | - |
63 | | -> [!Note] |
64 | | -> #### Always provide a time format when using custom partitioning |
65 | | -> |
66 | | -> If defining a custom partition template for your database with any of the |
67 | | -> `--template-*` flags, always include the `--template-timeformat` flag with a |
68 | | -> time format to use in your partition template. |
69 | | -> Otherwise, InfluxDB omits time from the partition template and won't compact partitions. |
70 | | -
|
71 | | -> [!Warning] |
72 | | -> #### Wait before writing to a new database with the same name as a deleted database |
73 | | -> |
74 | | -> After deleting a database from your {{% product-name omit=" Clustered" %}} |
75 | | -> cluster, you can reuse the name to create a new database, but **wait two to |
76 | | -> three minutes** after deleting the previous database before writing to the new |
77 | | -> database to allow write caches to clear. |
78 | | -
|
79 | | -## Usage |
80 | | - |
81 | | -<!--Skip tests for database create and delete: namespaces aren't reusable--> |
82 | | -<!--pytest.mark.skip--> |
83 | | - |
84 | | -```sh |
85 | | -influxctl database create [flags] <DATABASE_NAME> |
86 | | -``` |
87 | | - |
88 | | -## Arguments |
89 | | - |
90 | | -| Argument | Description | |
91 | | -| :---------------- | :--------------------- | |
92 | | -| **DATABASE_NAME** | InfluxDB database name | |
93 | | - |
94 | | -## Flags |
95 | | - |
96 | | -| Flag | | Description | |
97 | | -| :--- | :---------------------- | :--------------------------------------------------------------------------------------------------------------------------------------- | |
98 | | -| | `--retention-period` | [Database retention period ](/influxdb3/cloud-dedicated/admin/databases/#retention-periods)(default is `0s`, infinite) | |
99 | | -| | `--max-tables` | [Maximum tables per database](/influxdb3/cloud-dedicated/admin/databases/#table-limit) (default is 500, `0` uses default) | |
100 | | -| | `--max-columns` | [Maximum columns per table](/influxdb3/cloud-dedicated/admin/databases/#column-limit) (default is 250, `0` uses default) | |
101 | | -| | `--template-tag` | Tag to add to partition template (can include multiple of this flag) | |
102 | | -| | `--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) | |
103 | | -| | `--template-timeformat` | Timestamp format for partition template (default is `%Y-%m-%d`) | |
104 | | -| `-h` | `--help` | Output command help | |
105 | | - |
106 | | -{{% caption %}} |
107 | | -_Also see [`influxctl` global flags](/influxdb3/cloud-dedicated/reference/cli/influxctl/#global-flags)._ |
108 | | -{{% /caption %}} |
109 | | - |
110 | | -## Examples |
111 | | - |
112 | | -- [Create a database with an infinite retention period](#create-a-database-with-an-infinite-retention-period) |
113 | | -- [Create a database with a 30-day retention period](#create-a-database-with-a-30-day-retention-period) |
114 | | -- [Create a database with non-default table and column limits](#create-a-database-with-non-default-table-and-column-limits) |
115 | | -- [Create a database with a custom partition template](#create-a-database-with-a-custom-partition-template) |
116 | | - |
117 | | -### Create a database with an infinite retention period |
118 | | - |
119 | | -<!--Skip tests for database create and delete: namespaces aren't reusable--> |
120 | | -<!--pytest.mark.skip--> |
121 | | - |
122 | | -```sh |
123 | | -influxctl database create mydb |
124 | | -``` |
125 | | - |
126 | | -### Create a database with a 30-day retention period |
127 | | - |
128 | | -<!--Skip tests for database create and delete: namespaces aren't reusable--> |
129 | | -<!--pytest.mark.skip--> |
130 | | - |
131 | | -```sh |
132 | | -influxctl database create \ |
133 | | - --retention-period 30d \ |
134 | | - mydb |
135 | | -``` |
136 | | - |
137 | | -### Create a database with non-default table and column limits |
138 | | - |
139 | | -<!--Skip tests for database create and delete: namespaces aren't reusable--> |
140 | | -<!--pytest.mark.skip--> |
141 | | - |
142 | | -```sh |
143 | | -influxctl database create \ |
144 | | - --max-tables 200 \ |
145 | | - --max-columns 150 \ |
146 | | - mydb |
147 | | -``` |
148 | | - |
149 | | -### Create a database with a custom partition template |
150 | | - |
151 | | -The following example creates a new `mydb` database and applies a partition |
152 | | -template that partitions by two tags (`room` and `sensor-type`) and by day using |
153 | | -the time format `%Y-%m-%d`: |
154 | | - |
155 | | -<!--Skip tests for database create and delete: namespaces aren't reusable--> |
156 | | -<!--pytest.mark.skip--> |
157 | | - |
158 | | -```sh |
159 | | -influxctl database create \ |
160 | | - --template-tag room \ |
161 | | - --template-tag sensor-type \ |
162 | | - --template-tag-bucket customerID,1000 \ |
163 | | - --template-timeformat '%Y-%m-%d' \ |
164 | | - mydb |
165 | | -``` |
166 | | - |
167 | | -_For more information about custom partitioning, see |
168 | | -[Manage data partitioning](/influxdb3/cloud-dedicated/admin/custom-partitions/)._ |
169 | | - |
170 | | -{{% expand "View command updates" %}} |
171 | | - |
172 | | -#### v2.7.0 {date="2024-03-26"} |
173 | | - |
174 | | -- Introduce the `--template-tag-bucket` flag to group tag values into buckets |
175 | | - and partition by each tag bucket. |
176 | | - |
177 | | -#### v2.5.0 {date="2024-03-04"} |
178 | | - |
179 | | -- Introduce the `--template-tag` and `--template-timeformat` flags that define |
180 | | - a custom partition template for a database. |
181 | | - |
182 | | -{{% /expand %}} |
| 16 | +<!-- //SOURCE content/shared/influxctl/database/create.md --> |
0 commit comments