docs: clarify AUTO_RANDOM_BASE usage and explicit insert behavior

[alastori]

First-time contributors' checklist

What is changed, added or deleted? (Required)

Close issue: #20732

This PR updates the "Clear the auto-increment ID cache" section in auto-random.md to address confusion reported in the issue above. Specifically, the changes:

• Clarify that ALTER TABLE ... AUTO_RANDOM_BASE without the FORCE keyword does not actually change the value, despite the warning message.
• Emphasize that the FORCE keyword is mandatory to modify AUTO_RANDOM_BASE.
• Explicitly state that attempting to set AUTO_RANDOM_BASE to 0, even with FORCE, will result in an error.
• Clarify that a non-zero positive integer must be used with FORCE.
• Improve the explanation of how explicit inserts can potentially collide with the internal auto-incrementing part of AUTO_RANDOM IDs, potentially leading to duplicate key errors.
• Split a longer paragraph into smaller ones for better readability.

Which TiDB version(s) do your changes apply to? (Required)

Tips for choosing the affected version(s):

By default, CHOOSE MASTER ONLY so your changes will be applied to the next TiDB major or minor releases. If your PR involves a product feature behavior change or a compatibility change, CHOOSE THE AFFECTED RELEASE BRANCH(ES) AND MASTER.

For details, see tips for choosing the affected versions.

• master (the latest development version)
• v9.0 (TiDB 9.0 versions)
• v8.5 (TiDB 8.5 versions)
• v8.4 (TiDB 8.4 versions)
• v8.3 (TiDB 8.3 versions)
• v8.1 (TiDB 8.1 versions)
• v7.5 (TiDB 7.5 versions)
• v7.1 (TiDB 7.1 versions)
• v6.5 (TiDB 6.5 versions)
• v6.1 (TiDB 6.1 versions)
• v5.4 (TiDB 5.4 versions)

What is the related PR or file link(s)?

• Closes need to clarify the example in AUTO_RANDOM #20732
• File modified: auto-random.md

Do your changes match any of the following descriptions?

• Delete files
• Change aliases
• Need modification after applied to another branch
• Might cause conflicts after applied to another branch

[gemini-code-assist]

Warning

You have reached your daily quota limit. As a reminder, free tier users are limited to 5 requests per day. Please wait up to 24 hours and I will start processing your requests again!

[alastori]

@Frank945946

[alastori]

To confirm the behavior described in the documentation updates, I ran the following tests on a local TiDB instance:

1. Create Table:

CREATE TABLE t (a BIGINT PRIMARY KEY AUTO_RANDOM, b VARCHAR(255));

Query OK, 0 rows affected, 1 warning (0.07 sec)

2. Attempt AUTO_RANDOM_BASE=0 without FORCE:

ALTER TABLE t AUTO_RANDOM_BASE=0;
SHOW WARNINGS;

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

(Confirms the command completes with a warning but doesn't reset to 0.)

3. Attempt FORCE AUTO_RANDOM_BASE=0:

ALTER TABLE t FORCE AUTO_RANDOM_BASE=0;

ERROR 1467 (HY000): Cannot force rebase the next global ID to '0'

(Confirms forcing the base to 0 results in an error.)

4. Attempt FORCE AUTO_RANDOM_BASE = 1000 (non-zero):

ALTER TABLE t FORCE AUTO_RANDOM_BASE = 1000;

Query OK, 0 rows affected (0.04 sec)

(Confirms forcing the base to a non-zero value succeeds.)

5. Insert data after forcing base to 1000:

INSERT INTO t (b) VALUES ('test1'), ('test2');
SELECT * FROM t WHERE b LIKE 'test%';

Query OK, 2 rows affected (0.01 sec)
Records: 2  Duplicates: 0  Warnings: 0

+---------------------+-------+
| a                   | b     |
+---------------------+-------+
| 4899916394579100648 | test1 | -- Auto-increment part is 1000
| 4899916394579100649 | test2 | -- Auto-increment part is 1001
+---------------------+-------+
2 rows in set (0.00 sec)

(Confirms the auto-increment part starts from the forced base value.)

These results align with the behavior described in the updated documentation.

[tangenta]

If you try to alter AUTO_RANDOM_BASE without the FORCE keyword,

the value WILL not change even if the warning is reported. We should suggest ignoring the warning instead of using FORCE (see my comment above)

[alastori]

@tangenta I appreciate this critical correction. I've updated the documentation to clearly state that when using AUTO_RANDOM_BASE=0 without the FORCE keyword, "the value will change and you can safely ignore this warning." This is an important distinction that users need to know.
The warning message itself (Can't reset AUTO_INCREMENT to 0 without FORCE option, using XXX instead) is a bit misleading since it mentions AUTO_INCREMENT instead of AUTO_RANDOM and suggests the change isn't happening when it actually is. Would updating this warning message be something to consider for a future release?

[alastori]

Suggestion just in case you are considering updating the warning message: "AUTO_RANDOM_BASE has been updated to XXX. You specified '0' which triggered automatic rebasing to prevent ID collisions."

[tangenta]

pingcap/tidb#60616

[ti-chi-bot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please ask for approval from hfxsd, ensuring that each of them provides their approval before proceeding. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[qiancai]

Rest LGTM

[qiancai]

Suggested change

The collision happens as follows: 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 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).

The collision happens as follows: 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).

[qiancai]

Suggested change

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

[qiancai]

Suggested change

	This approach is less convenient because 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.

[qiancai]

Suggested change

	> You must use a non-zero positive integer value when using `FORCE`.
	> When using `FORCE`, you must specify a non-zero positive integer.

[ti-chi-bot]

[LGTM Timeline notifier]

Timeline:

• 2025-04-16 14:16:53.768255521 +0000 UTC m=+2870707.452491617: ☑️ agreed by tangenta.
• 2025-04-24 11:35:24.601156518 +0000 UTC m=+528268.412946900: ☑️ agreed by qiancai.