From 9de99104341f8154e14681c888cd3b80d4a56dbd Mon Sep 17 00:00:00 2001 From: Airton Lastori Date: Thu, 10 Apr 2025 00:13:09 -0400 Subject: [PATCH 1/5] docs: clarify AUTO_RANDOM_BASE usage and explicit insert behavior (#20732) --- auto-random.md | 31 ++++++++++++++++--------------- 1 file changed, 16 insertions(+), 15 deletions(-) diff --git a/auto-random.md b/auto-random.md index 041e9974c9ae1..852fe81055bf2 100644 --- a/auto-random.md +++ b/auto-random.md @@ -166,31 +166,32 @@ TiDB implicitly allocates values to `AUTO_RANDOM` columns similarly to `AUTO_INC ## 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 explicit inserts happen to use ID values that conflict with the internal counter TiDB uses for automatic generation, this can lead to errors. -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, 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. -``` -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. 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`. +> * 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'`. +> * 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`: From 4ba5aa75c1fc7b3e23b5fc9830d2f46f96510bec Mon Sep 17 00:00:00 2001 From: Airton Lastori Date: Mon, 14 Apr 2025 23:25:40 -0400 Subject: [PATCH 2/5] Update auto-random.md Mention conflicts happen in deployments with multiple TiDB nodes. --- auto-random.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/auto-random.md b/auto-random.md index 852fe81055bf2..ca07a1934aa65 100644 --- a/auto-random.md +++ b/auto-random.md @@ -166,7 +166,7 @@ TiDB implicitly allocates values to `AUTO_RANDOM` columns similarly to `AUTO_INC ## 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 explicit inserts happen to use ID values that conflict with the internal counter TiDB uses for automatic generation, this can lead to errors. +When you insert data with explicit values into an `AUTO_RANDOM` column in a deployment with multiple TiDB server instances, potential ID collisions can occur, similar to an `AUTO_INCREMENT` column. If explicit inserts happen to use ID values that conflict with the internal counter TiDB uses for automatic generation, this can lead to errors. 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. From 9900c854d26b12fd76c33b2a26d60000acb0c4d5 Mon Sep 17 00:00:00 2001 From: Airton Lastori Date: Tue, 15 Apr 2025 00:13:24 -0400 Subject: [PATCH 3/5] Update auto-random.md Adjustments based on the review by @tangenta --- auto-random.md | 32 ++++++++++++++++++++------------ 1 file changed, 20 insertions(+), 12 deletions(-) diff --git a/auto-random.md b/auto-random.md index ca07a1934aa65..f31fc80582af1 100644 --- a/auto-random.md +++ b/auto-random.md @@ -166,31 +166,39 @@ TiDB implicitly allocates values to `AUTO_RANDOM` columns similarly to `AUTO_INC ## Clear the auto-increment ID cache -When you insert data with explicit values into an `AUTO_RANDOM` column in a deployment with multiple TiDB server instances, potential ID collisions can occur, similar to an `AUTO_INCREMENT` column. If explicit inserts happen to use ID values that conflict with the internal counter TiDB uses for automatic generation, this can lead to errors. +When you insert data with explicit values into an `AUTO_RANDOM` column in a deployment with multiple TiDB server instances, potential ID collisions can occur, similar to an `AUTO_INCREMENT` column. If explicit inserts happen to use ID values that conflict with the internal counter TiDB uses for automatic generation, this can lead to errors. -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. +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. See [AUTO_INCREMENT Uniqueness](/auto-increment.md/#uniqueness) for details. -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. +With a single TiDB instance, this issue doesn't occur because the node automatically adjusts its internal counter when processing explicit insertions, preventing any future collisions. In contrast, with multiple TiDB nodes, each node maintains its own cache of IDs, which needs to be cleared to prevent collisions after explicit insertions. To clear these unallocated cached IDs and avoid potential collisions, you have two options: -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. +### Option 1: Automatically rebase (Recommended) + +```sql +ALTER TABLE t AUTO_RANDOM_BASE=0; +``` + +This command will automatically determine an appropriate base value. Although it produces a warning message like `Can't reset AUTO_INCREMENT to 0 without FORCE option, using XXX instead`, the value **will** change and you can safely ignore this warning. > **Note:** > -> * 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`. -> * 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'`. -> * You must use a non-zero positive integer value when using `FORCE`. +> You cannot set `AUTO_RANDOM_BASE` to `0` with the `FORCE` keyword. Attempting this results in an error. + +### Option 2: Manually set a specific base value -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: +If you need to set a specific base value (for example, `1000`), use the `FORCE` keyword: ```sql ALTER TABLE t FORCE AUTO_RANDOM_BASE = 1000; ``` -``` -Query OK, 0 rows affected (0.XX sec) -``` +This approach is less convenient as it requires you to determine an appropriate value yourself. + +> **Note:** +> +> * You must use a non-zero positive integer value when using `FORCE`. -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. +Both commands modify the starting point for the auto-increment bits used in subsequent `AUTO_RANDOM` value generations across all TiDB nodes. They do not affect already allocated IDs. ## Restrictions From 367c2c33aedab80940b7b0df7ad7bd84746d369f Mon Sep 17 00:00:00 2001 From: Airton Lastori Date: Tue, 15 Apr 2025 00:22:54 -0400 Subject: [PATCH 4/5] Update auto-random.md fixing link that had an extra slash "/" --- auto-random.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/auto-random.md b/auto-random.md index f31fc80582af1..8b209c0744b17 100644 --- a/auto-random.md +++ b/auto-random.md @@ -168,7 +168,7 @@ TiDB implicitly allocates values to `AUTO_RANDOM` columns similarly to `AUTO_INC When you insert data with explicit values into an `AUTO_RANDOM` column in a deployment with multiple TiDB server instances, potential ID collisions can occur, similar to an `AUTO_INCREMENT` column. If explicit inserts happen to use ID values that conflict with the internal counter TiDB uses for automatic generation, this can lead to errors. -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. See [AUTO_INCREMENT Uniqueness](/auto-increment.md/#uniqueness) for details. +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. See [AUTO_INCREMENT Uniqueness](/auto-increment.md#uniqueness) for details. With a single TiDB instance, this issue doesn't occur because the node automatically adjusts its internal counter when processing explicit insertions, preventing any future collisions. In contrast, with multiple TiDB nodes, each node maintains its own cache of IDs, which needs to be cleared to prevent collisions after explicit insertions. To clear these unallocated cached IDs and avoid potential collisions, you have two options: From 89585ab43fa9e8af938fd362ca0d92491c4e3993 Mon Sep 17 00:00:00 2001 From: Airton Lastori Date: Fri, 2 May 2025 19:39:01 -0400 Subject: [PATCH 5/5] docs: apply review suggestions for auto-random.md --- auto-random.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/auto-random.md b/auto-random.md index 8b209c0744b17..325a850805863 100644 --- a/auto-random.md +++ b/auto-random.md @@ -168,7 +168,7 @@ TiDB implicitly allocates values to `AUTO_RANDOM` columns similarly to `AUTO_INC When you insert data with explicit values into an `AUTO_RANDOM` column in a deployment with multiple TiDB server instances, potential ID collisions can occur, similar to an `AUTO_INCREMENT` column. If explicit inserts happen to use ID values that conflict with the internal counter TiDB uses for automatic generation, this can lead to errors. -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. See [AUTO_INCREMENT Uniqueness](/auto-increment.md#uniqueness) for details. +Here's how the collision can happen: each `AUTO_RANDOM` ID consists of random bits and an auto-incrementing part. TiDB uses an internal counter for this auto-incrementing part. If you explicitly insert an ID where the auto-incrementing part matches the counter's next value, a duplicate key error might occur when TiDB later attempts to generate the same ID automatically. For more details, see [AUTO_INCREMENT Uniqueness](/auto-increment.md#uniqueness). With a single TiDB instance, this issue doesn't occur because the node automatically adjusts its internal counter when processing explicit insertions, preventing any future collisions. In contrast, with multiple TiDB nodes, each node maintains its own cache of IDs, which needs to be cleared to prevent collisions after explicit insertions. To clear these unallocated cached IDs and avoid potential collisions, you have two options: @@ -178,7 +178,7 @@ With a single TiDB instance, this issue doesn't occur because the node automatic ALTER TABLE t AUTO_RANDOM_BASE=0; ``` -This command will automatically determine an appropriate base value. Although it produces a warning message like `Can't reset AUTO_INCREMENT to 0 without FORCE option, using XXX instead`, the value **will** change and you can safely ignore this warning. +This statement automatically determines an appropriate base value. Although it produces a warning message similar to `Can't reset AUTO_INCREMENT to 0 without FORCE option, using XXX instead`, the base value **will** change and you can safely ignore this warning. > **Note:** > @@ -192,11 +192,11 @@ If you need to set a specific base value (for example, `1000`), use the `FORCE` ALTER TABLE t FORCE AUTO_RANDOM_BASE = 1000; ``` -This approach is less convenient as it requires you to determine an appropriate value yourself. +This approach is less convenient because it requires you to determine an appropriate base value yourself. > **Note:** > -> * You must use a non-zero positive integer value when using `FORCE`. +> * When using `FORCE`, you must specify a non-zero positive integer. Both commands modify the starting point for the auto-increment bits used in subsequent `AUTO_RANDOM` value generations across all TiDB nodes. They do not affect already allocated IDs.