CREATE SEQUENCE

CREATE SEQUENCE 语句用于在 TiDB 中创建序列对象。序列是一种与表、视图对象平级的数据库对象，用于生成自定义的序列化 ID。

语法图

1. CreateSequenceStmt ::=
2. 'CREATE' 'SEQUENCE' IfNotExists TableName CreateSequenceOptionListOpt CreateTableOptionListOpt

4. IfNotExists ::=
5. ('IF' 'NOT' 'EXISTS')?

7. TableName ::=
8. Identifier ('.' Identifier)?

10. CreateSequenceOptionListOpt ::=
11. SequenceOption*

13. SequenceOptionList ::=
14. SequenceOption

16. SequenceOption ::=
17. ( 'INCREMENT' ( '='? | 'BY' ) | 'START' ( '='? | 'WITH' ) | ( 'MINVALUE' | 'MAXVALUE' | 'CACHE' ) '='? ) SignedNum
18. |   'NOMINVALUE'
19. |   'NO' ( 'MINVALUE' | 'MAXVALUE' | 'CACHE' | 'CYCLE' )
20. |   'NOMAXVALUE'
21. |   'NOCACHE'
22. |   'CYCLE'
23. |   'NOCYCLE'

语法说明

1. CREATE [TEMPORARY] SEQUENCE [IF NOT EXISTS] sequence_name
2. [ INCREMENT [ BY | = ] increment ]
3. [ MINVALUE [=] minvalue | NO MINVALUE | NOMINVALUE ]
4. [ MAXVALUE [=] maxvalue | NO MAXVALUE | NOMAXVALUE ]
5. [ START [ WITH | = ] start ]
6. [ CACHE [=] cache | NOCACHE | NO CACHE]
7. [ CYCLE | NOCYCLE | NO CYCLE]
8. [table_options]

参数说明

SEQUENCE 函数

主要通过表达式函数来操纵序列的使用。

• NEXTVAL 或 NEXT VALUE FOR

本质上都是 nextval() 函数，获取序列对象的下一个有效值，其参数为序列的 identifier。 - LASTVAL

lastval() 函数，用于获取本会话上一个使用过的值。如果没有值，则为 NULL，其参数为序列的 identifier。 - SETVAL

setval() 函数，用于设置序列的增长。其第一参数为序列的 identifier，第二个参数为 num。

注意：

在 TiDB 序列的实现中，SETVAL 函数并不能改变序列增长的初始步调或循环步调。在 SETVAL 之后只会返回符合步调规律的下一个有效的序列值。

示例

• 创建一个默认参数的序列对象。

1. CREATE SEQUENCE seq;

1. Query OK, 0 rows affected (0.06 sec) - 使用 nextval() 函数获取序列对象的下一个值。

1. SELECT nextval(seq);

1. +--------------+ 2. | nextval(seq) | 3. +--------------+ 4. | 1 | 5. +--------------+ 6. 1 row in set (0.02 sec) - 使用 lastval() 函数获取本会话上一次调用序列对象所产生的值。

1. SELECT lastval(seq);

1. +--------------+ 2. | lastval(seq) | 3. +--------------+ 4. | 1 | 5. +--------------+ 6. 1 row in set (0.02 sec) - 使用 setval() 函数设置序列对象当前值的位置。

1. SELECT setval(seq, 10);

1. +-----------------+ 2. | setval(seq, 10) | 3. +-----------------+ 4. | 10 | 5. +-----------------+ 6. 1 row in set (0.01 sec) - 也可使用 next value for 语法获取序列的下一个值。

1. SELECT next value for seq;

1. +--------------------+ 2. | next value for seq | 3. +--------------------+ 4. | 11 | 5. +--------------------+ 6. 1 row in set (0.00 sec) - 创建一个默认自定义参数的序列对象。

1. CREATE SEQUENCE seq2 start 3 increment 2 minvalue 1 maxvalue 10 cache 3;

1. Query OK, 0 rows affected (0.01 sec) - 当本会话还未使用过序列对象时，lastval() 函数返回 NULL 值。

1. SELECT lastval(seq2);

1. +---------------+ 2. | lastval(seq2) | 3. +---------------+ 4. | NULL | 5. +---------------+ 6. 1 row in set (0.01 sec) - 序列对象 nextval() 的第一个有效值为 start 值。

1. SELECT nextval(seq2);

1. +---------------+ 2. | nextval(seq2) | 3. +---------------+ 4. | 3 | 5. +---------------+ 6. 1 row in set (0.00 sec) - 使用 setval() 虽然可以改变序列对象当前值的位置，但是无法改变下一个值的等差规律。

1. SELECT setval(seq2, 6);

1. +-----------------+ 2. | setval(seq2, 6) | 3. +-----------------+ 4. | 6 | 5. +-----------------+ 6. 1 row in set (0.00 sec) - 使用 nextval() 下一个值获取时，会遵循序列定义的等差规律。

1. SELECT next value for seq2;

1. +---------------------+ 2. | next value for seq2 | 3. +---------------------+ 4. | 7 | 5. +---------------------+ 6. 1 row in set (0.00 sec) - 可以将序列的下一个值作为列的默认值来使用。

1. CREATE TABLE t(a int default next value for seq2);

1. Query OK, 0 rows affected (0.02 sec) - 下列示例中，因为没有指定值，会直接获取 seq2 的默认值来使用。

1. INSERT into t values();

1. Query OK, 1 row affected (0.00 sec)

1. SELECT * from t;

1. +------+ 2. | a | 3. +------+ 4. | 9 | 5. +------+ 6. 1 row in set (0.00 sec) - 下列示例中，因为没有指定值，会直接获取 seq2 的默认值来使用。由于 seq2 的下一个值超过了上述示例 (CREATE SEQUENCE seq2 start 3 increment 2 minvalue 1 maxvalue 10 cache 3;) 的定义范围，所以会显示报错。

1. INSERT into t values();

1. ERROR 4135 (HY000): Sequence 'test.seq2' has run out

MySQL 兼容性

该语句是 TiDB 的扩展，序列的实现借鉴自 MariaDB。

除了 SETVAL 函数外，其他函数的“步调 (progressions)” 与 MariaDB 一致。这里的步调是指，序列中的数在定义之后会产生一定的等差关系。SETVAL 虽然可以将序列的当前值进行移动设置，但是后续出现的值仍会遵循原有的等差关系。

示例如下：

1. 1, 3, 5, ...            // 序列遵循起始为 1、步长为 2 的等差关系。
2. select setval(seq, 6)   // 设置序列的当前值为 6。
3. 7, 9, 11, ...           // 后续产生值仍会遵循这个等差关系。

在 CYCLE 模式下，序列的起始值第一轮为 start，后续轮次将会是 MinValue (increment > 0) 或 MaxValue (increment < 0)。

另请参阅

• DROP SEQUENCE
• SHOW CREATE SEQUENCE