Skip to content

Fix auto random user scenario #20733

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .github/workflows/bot.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ on:

jobs:
pr_reminder:
if: github.repository == 'pingcap/docs'
runs-on: ubuntu-latest
steps:
- name: Run PR reminder
Expand Down
1 change: 1 addition & 0 deletions .github/workflows/link.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@ on:

jobs:
linkChecker:
if: github.repository == 'pingcap/docs'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
Expand Down
31 changes: 16 additions & 15 deletions auto-random.md
Original file line number Diff line number Diff line change
Expand Up @@ -166,31 +166,32 @@

## Clear the auto-increment ID cache

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).
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 you insert many explicit values, you might accidentally use an ID value that TiDB would have generated automatically later, which can lead to errors.

Check warning on line 169 in auto-random.md

View workflow job for this annotation

GitHub Actions / vale

[vale] reported by reviewdog 🐶 [PingCAP.Ambiguous] Consider using a clearer word than 'many' because it may cause confusion. Raw Output: {"message": "[PingCAP.Ambiguous] Consider using a clearer word than 'many' because it may cause confusion.", "location": {"path": "auto-random.md", "range": {"start": {"line": 169, "column": 171}}}, "severity": "INFO"}

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:
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.

```sql
ALTER TABLE t AUTO_RANDOM_BASE=0;
```
Although `AUTO_RANDOM` doesn't keep track of a single specific "next ID" like `AUTO_INCREMENT` does, inserting many explicit values 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.

Check warning on line 173 in auto-random.md

View workflow job for this annotation

GitHub Actions / vale

[vale] reported by reviewdog 🐶 [PingCAP.Ambiguous] Consider using a clearer word than 'many' because it may cause confusion. Raw Output: {"message": "[PingCAP.Ambiguous] Consider using a clearer word than 'many' because it may cause confusion.", "location": {"path": "auto-random.md", "range": {"start": {"line": 173, "column": 112}}}, "severity": "INFO"}

```
Query OK, 0 rows affected, 1 warning (0.52 sec)
```
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.

> **Note:**
>
> * If you try to alter `AUTO_RANDOM_BASE` without the `FORCE` keyword, the value will not change. You will only see a warning message like `Can't reset AUTO_INCREMENT to 0 without FORCE option, using XXX instead`, but the base value stays unchanged.
> * You cannot set `AUTO_RANDOM_BASE` to `0`, even with the `FORCE` keyword. If you try this (`ALTER TABLE t FORCE AUTO_RANDOM_BASE=0;`), you will get an error.
> * You must use a non-zero positive integer value when using `FORCE`.

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:

```sql
SHOW WARNINGS;
ALTER TABLE t FORCE AUTO_RANDOM_BASE = 1000;
```

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

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.

## Restrictions

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