From f3264ebfe50231972bb4b9646137b6e8d4df53e2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dani=C3=ABl=20van=20Eeden?= Date: Thu, 29 Feb 2024 15:18:14 +0100 Subject: [PATCH] Add docs for ALTER SEQUENCE --- .../sql-statement-alter-sequence.md | 211 ++++++++++++++++++ .../sql-statement-create-sequence.md | 1 + sql-statements/sql-statement-drop-sequence.md | 1 + .../sql-statement-show-create-sequence.md | 1 + 4 files changed, 214 insertions(+) create mode 100644 sql-statements/sql-statement-alter-sequence.md diff --git a/sql-statements/sql-statement-alter-sequence.md b/sql-statements/sql-statement-alter-sequence.md new file mode 100644 index 0000000000000..6c950cc9cebc1 --- /dev/null +++ b/sql-statements/sql-statement-alter-sequence.md @@ -0,0 +1,211 @@ +--- +title: ALTER SEQUENCE +summary: An overview of the usage of ALTER SEQUENCE for the TiDB database. +--- + +# ALTER SEQUENCE + +The `ALTER SEQUENCE` statement alters sequence objects in TiDB. The sequence is a database object that is on a par with the table and the `View` object. The sequence is used to generate serialized IDs in a customized way. + +## Synopsis + +```ebnf+diagram +CreateSequenceStmt ::= + 'ALTER' 'SEQUENCE' TableName CreateSequenceOptionListOpt CreateTableOptionListOpt + +TableName ::= + Identifier ('.' Identifier)? + +CreateSequenceOptionListOpt ::= + SequenceOption* + +SequenceOptionList ::= + SequenceOption + +SequenceOption ::= + ( 'INCREMENT' ( '='? | 'BY' ) | 'START' ( '='? | 'WITH' ) | ( 'MINVALUE' | 'MAXVALUE' | 'CACHE' ) '='? ) SignedNum +| 'NOMINVALUE' +| 'NO' ( 'MINVALUE' | 'MAXVALUE' | 'CACHE' | 'CYCLE' ) +| 'NOMAXVALUE' +| 'NOCACHE' +| 'CYCLE' +| 'NOCYCLE' +``` + +## Syntax + +{{< copyable "sql" >}} + +```sql +ALTER SEQUENCE sequence_name + [ INCREMENT [ BY | = ] increment ] + [ MINVALUE [=] minvalue | NO MINVALUE | NOMINVALUE ] + [ MAXVALUE [=] maxvalue | NO MAXVALUE | NOMAXVALUE ] + [ START [ WITH | = ] start ] + [ CACHE [=] cache | NOCACHE | NO CACHE] + [ CYCLE | NOCYCLE | NO CYCLE] + [table_options] +``` + +## Parameters + +|Parameters | Default value | Description | +| :-- | :-- | :--| +| `INCREMENT` | `1` | Specifies the increment of a sequence. Its positive or negative values can control the growth direction of the sequence. | +| `MINVALUE` | `1` or `-9223372036854775807` | Specifies the minimum value of a sequence. When `INCREMENT` > `0`, the default value is `1`. When `INCREMENT` < `0`, the default value is `-9223372036854775807`. | +| `MAXVALUE` | `9223372036854775806` or `-1` | Specifies the maximum value of a sequence. When `INCREMENT` > `0`, the default value is `9223372036854775806`. When `INCREMENT` < `0`, the default value is `-1`. | +| `START` | `MINVALUE` or `MAXVALUE`| Specifies the initial value of a sequence. When `INCREMENT` > `0`, the default value is `MINVALUE`. When `INCREMENT` < `0`, the default value is `MAXVALUE`. | +| `CACHE` | `1000` | Specifies the local cache size of a sequence in TiDB. | +| `CYCLE` | `NO CYCLE` | Specifies whether a sequence restarts from the minimum value (or maximum for the descending sequence). When `INCREMENT` > `0`, the default value is `MINVALUE`. When `INCREMENT` < `0`, the default value is `MAXVALUE`. | + +## `SEQUENCE` function + +You can control a sequence through the following expression functions: + ++ `NEXTVAL` or `NEXT VALUE FOR` + + Essentially, both are the `nextval()` function that gets the next valid value of a sequence object. The parameter of the `nextval()` function is the `identifier` of the sequence. + ++ `LASTVAL` + + This function gets the last used value of this session. If the value does not exist, `NULL` is used. The parameter of this function is the `identifier` of the sequence. + ++ `SETVAL` + + This function sets the progression of the current value for a sequence. The first parameter of this function is the `identifier` of the sequence; the second parameter is `num`. + +> **Note:** +> +> In the implementation of a sequence in TiDB, the `SETVAL` function cannot change the initial progression or cycle progression of this sequence. This function only returns the next valid value based on this progression. + +## Examples + +We create a sequence with a name of `s1`. + +```sql +CREATE SEQUENCE s1; +``` + +``` +Query OK, 0 rows affected (0.15 sec) +``` + + +Then we get two values from the sequence + +```sql +SELECT NEXTVAL(s1); +``` + +``` ++-------------+ +| NEXTVAL(s1) | ++-------------+ +| 1 | ++-------------+ +1 row in set (0.01 sec) +``` + +```sql +SELECT NEXTVAL(s1); +``` + +``` ++-------------+ +| NEXTVAL(s1) | ++-------------+ +| 2 | ++-------------+ +1 row in set (0.00 sec) +``` + +Now we change the sequence to increment by two. + +```sql +ALTER SEQUENCE s1 INCREMENT=2; +``` + +``` +Query OK, 0 rows affected (0.18 sec) +``` + +Now we get two new values. + +```sql +SELECT NEXTVAL(s1); +``` + +``` ++-------------+ +| NEXTVAL(s1) | ++-------------+ +| 1001 | ++-------------+ +1 row in set (0.02 sec) +``` + +```sql +SELECT NEXTVAL(s1); +``` + +``` ++-------------+ +| NEXTVAL(s1) | ++-------------+ +| 1003 | ++-------------+ +1 row in set (0.00 sec) +``` + +As you can see in the output the values now increate by two, following the `ALTER SEQUENCE` statement. + +It is also possible to change other properties, for example `MAXVALUE`. + +```sql +CREATE SEQUENCE s2 MAXVALUE=10; +``` + +``` +Query OK, 0 rows affected (0.17 sec) +``` + +```sql +ALTER SEQUENCE s2 MAXVALUE=100; +``` + +``` +Query OK, 0 rows affected (0.15 sec) +``` + +``` +SHOW CREATE SEQUENCE s2\G +``` + +``` +*************************** 1. row *************************** + Sequence: s2 +Create Sequence: CREATE SEQUENCE `s2` start with 1 minvalue 1 maxvalue 100 increment by 1 cache 1000 nocycle ENGINE=InnoDB +1 row in set (0.00 sec) +``` + +## MySQL compatibility + +This statement is a TiDB extension. The implementation is modeled on sequences available in MariaDB. + +Except for the `SETVAL` function, all other functions have the same _progressions_ as MariaDB. Here "progression" means that the numbers in a sequence follow a certain arithmetic progression rule defined by the sequence. Although you can use `SETVAL` to set the current value of a sequence, the subsequent values of the sequence still follow the original progression rule. + +For example: + +``` +1, 3, 5, ... // The sequence starts from 1 and increments by 2. +select setval(seq, 6) // Sets the current value of a sequence to 6. +7, 9, 11, ... // Subsequent values still follow the progression rule. +``` + +In the `CYCLE` mode, the initial value of a sequence in the first round is the value of the `START` parameter, and the initial value in the subsequent rounds is the value of `MinValue` (`INCREMENT` > 0) or `MaxValue` (`INCREMENT` < 0). + +## See also + +* [CREATE SEQUENCE](/sql-statements/sql-statement-create-sequence.md) +* [DROP SEQUENCE](/sql-statements/sql-statement-drop-sequence.md) +* [SHOW CREATE SEQUENCE](/sql-statements/sql-statement-show-create-sequence.md) diff --git a/sql-statements/sql-statement-create-sequence.md b/sql-statements/sql-statement-create-sequence.md index 01946a387eaba..c4cd93a164874 100644 --- a/sql-statements/sql-statement-create-sequence.md +++ b/sql-statements/sql-statement-create-sequence.md @@ -314,5 +314,6 @@ In the `CYCLE` mode, the initial value of a sequence in the first round is the v ## See also +* [ALTER SEQUENCE](/sql-statements/sql-statement-alter-sequence.md) * [DROP SEQUENCE](/sql-statements/sql-statement-drop-sequence.md) * [SHOW CREATE SEQUENCE](/sql-statements/sql-statement-show-create-sequence.md) diff --git a/sql-statements/sql-statement-drop-sequence.md b/sql-statements/sql-statement-drop-sequence.md index ca346c168859f..fbc3cdec4f9f3 100644 --- a/sql-statements/sql-statement-drop-sequence.md +++ b/sql-statements/sql-statement-drop-sequence.md @@ -52,4 +52,5 @@ This statement is a TiDB extension. The implementation is modeled on sequences a ## See also * [CREATE SEQUENCE](/sql-statements/sql-statement-create-sequence.md) +* [ALTER SEQUENCE](/sql-statements/sql-statement-alter-sequence.md) * [SHOW CREATE SEQUENCE](/sql-statements/sql-statement-show-create-sequence.md) diff --git a/sql-statements/sql-statement-show-create-sequence.md b/sql-statements/sql-statement-show-create-sequence.md index b8b9b5f69007d..bfdab6ce4affe 100644 --- a/sql-statements/sql-statement-show-create-sequence.md +++ b/sql-statements/sql-statement-show-create-sequence.md @@ -52,4 +52,5 @@ This statement is a TiDB extension. The implementation is modeled on sequences a ## See also * [CREATE SEQUENCE](/sql-statements/sql-statement-create-sequence.md) +* [ALTER SEQUENCE](/sql-statements/sql-statement-alter-sequence.md) * [DROP SEQUENCE](/sql-statements/sql-statement-drop-sequence.md)