Skip to content

Commit be6b29d

Browse files
committed
docs: clarify AUTO_RANDOM_BASE usage and explicit insert behavior (#20732)
1 parent b6b8773 commit be6b29d

File tree

1 file changed

+16
-15
lines changed

1 file changed

+16
-15
lines changed

auto-random.md

+16-15
Original file line numberDiff line numberDiff line change
@@ -166,31 +166,32 @@ TiDB implicitly allocates values to `AUTO_RANDOM` columns similarly to `AUTO_INC
166166

167167
## Clear the auto-increment ID cache
168168

169-
Explicitly inserting data into an `AUTO_RANDOM` column behaves the same as with an `AUTO_INCREMENT` column, so you also need to clear the auto-increment ID cache. For more details, see [Clear the auto-increment ID cache](/auto-increment.md#clear-the-auto-increment-id-cache).
169+
When you insert data with explicit values into an `AUTO_RANDOM` column, it works similarly to an `AUTO_INCREMENT` column regarding potential ID collisions. If explicit inserts happen to use ID values that conflict with the internal counter TiDB uses for automatic generation, this can lead to errors.
170170

171-
You can run the `ALTER TABLE` statement to set `AUTO_RANDOM_BASE=0` to clear the auto-increment ID cache on all TiDB nodes in the cluster. For example:
171+
Here's how the collision can happen: each `AUTO_RANDOM` ID contains an auto-incrementing part alongside random bits. TiDB uses an internal counter for this auto-incrementing part. If you explicitly insert an ID where this part matches the counter's next value, TiDB might later try to generate the same ID automatically, leading to a duplicate key error.
172172

173-
```sql
174-
ALTER TABLE t AUTO_RANDOM_BASE=0;
175-
```
173+
Although `AUTO_RANDOM` doesn't keep track of a single specific "next ID" like `AUTO_INCREMENT` does, frequent explicit inserts that cause such conflicts might still require you to adjust the starting point (`AUTO_RANDOM_BASE`) for the auto-incrementing part of future automatically generated IDs to avoid these potential errors.
176174

177-
```
178-
Query OK, 0 rows affected, 1 warning (0.52 sec)
179-
```
175+
To change the base value (`AUTO_RANDOM_BASE`) used for the auto-increment part of future ID generations on an existing table, you must use the `FORCE` keyword.
176+
177+
> **Note:**
178+
>
179+
> * If you try to alter `AUTO_RANDOM_BASE` without the `FORCE` keyword, the value will not change. The command completes, but the base value stays unchanged. A subsequent `SHOW WARNINGS` reveals the specific warning `Can't reset AUTO_INCREMENT to 0 without FORCE option, using 1 instead`.
180+
> * You cannot set `AUTO_RANDOM_BASE` to `0`, even with the `FORCE` keyword. Attempting this results in an error `Cannot force rebase the next global ID to '0'`.
181+
> * You must use a non-zero positive integer value when using `FORCE`.
182+
183+
To set a new base value (for example, `1000`) for the auto-increment part of future implicitly generated IDs for table `t`, use the following statement:
180184

181185
```sql
182-
SHOW WARNINGS;
186+
ALTER TABLE t FORCE AUTO_RANDOM_BASE = 1000;
183187
```
184188

185189
```
186-
+---------+------+-------------------------------------------------------------------------+
187-
| Level | Code | Message |
188-
+---------+------+-------------------------------------------------------------------------+
189-
| Warning | 1105 | Can't reset AUTO_INCREMENT to 0 without FORCE option, using 101 instead |
190-
+---------+------+-------------------------------------------------------------------------+
191-
1 row in set (0.00 sec)
190+
Query OK, 0 rows affected (0.XX sec)
192191
```
193192

193+
This command modifies the starting point for the auto-increment bits used in subsequent `AUTO_RANDOM` value generations across all TiDB nodes. It does not affect already allocated IDs.
194+
194195
## Restrictions
195196

196197
Pay attention to the following restrictions when you use `AUTO_RANDOM`:

0 commit comments

Comments
 (0)