auto_increment: improve description of monotonic (pingcap#6911)

auto-increment.md

@@ -129,11 +129,56 @@ Records: 3  Duplicates: 0  Warnings: 0
 3 rows in set (0.00 sec)
 ```
 
+Monotonicity is not the same guarantee as consecutive. Consider the following example:
+
+{{< copyable "sql" >}}
+
+```sql
+CREATE TABLE t (id INT NOT NULL PRIMARY KEY auto_increment, a VARCHAR(10), cnt INT NOT NULL DEFAULT 1, UNIQUE KEY (a));
+INSERT INTO t (a) VALUES ('A'), ('B');
+SELECT * FROM t;
+INSERT INTO t (a) VALUES ('A'), ('C') ON DUPLICATE KEY UPDATE cnt = cnt + 1;
+SELECT * FROM t;
+```
+
+```sql
+Query OK, 0 rows affected (0.00 sec)
+
+Query OK, 2 rows affected (0.00 sec)
+Records: 2  Duplicates: 0  Warnings: 0
+
++----+------+-----+
+| id | a    | cnt |
++----+------+-----+
+|  1 | A    |   1 |
+|  2 | B    |   1 |
++----+------+-----+
+2 rows in set (0.00 sec)
+
+Query OK, 3 rows affected (0.00 sec)
+Records: 2  Duplicates: 1  Warnings: 0
+
++----+------+-----+
+| id | a    | cnt |
++----+------+-----+
+|  1 | A    |   2 |
+|  2 | B    |   1 |
+|  4 | C    |   1 |
++----+------+-----+
+3 rows in set (0.00 sec)
+```
+
+In this example, the `AUTO_INCREMENT` value of `3` is allocated for the `INSERT` of the key `A` in `INSERT INTO t (a) VALUES ('A'), ('C') ON DUPLICATE KEY UPDATE cnt = cnt + 1;` but never used because this `INSERT` statement contains a duplicate key `A`. This leads to a gap where the sequence is non-consecutive. This behavior is considered legal, even though it differs from MySQL. MySQL will also have gaps in the sequence in other scenarios such as transactions being aborted and rolled back.
+
+## AUTO_ID_CACHE
+
 The `AUTO_INCREMENT` sequence might appear to _jump_ dramatically if an `INSERT` operation is performed against a different TiDB server. This is caused by the fact that each server has its own cache of `AUTO_INCREMENT` values:
 
 {{< copyable "sql" >}}
 
 ```sql
+CREATE TABLE t (a int PRIMARY KEY AUTO_INCREMENT, b timestamp NOT NULL DEFAULT NOW());
+INSERT INTO t (a) VALUES (NULL), (NULL), (NULL);
 INSERT INTO t (a) VALUES (NULL);
 SELECT * FROM t;
 ```