↑↓ 选择↵ 打开⌫ 切换范围完整搜索

PG.CENTER 连接 PostgreSQL 文档、百科与生态知识。由 Pigsty 维护。

支持中的版本: 当前版本 (18) / 17 / 16 / 15 / 14
开发中的版本: 19 / 20devel
已结束支持的版本: 13 / 12 / 11 / 10 / 9.6 / 9.5 / 9.4 / 9.3 / 9.2 / 9.1 / 9.0 / 8.4 / 8.3 / 8.2 / 8.1 / 8.0 / 7.4 / 7.3 / 7.2
开发快照。 PostgreSQL 20devel 尚未正式发布,内容仍可能变化。

9.18. 序列操作函数 #

本节描述用于操作序列对象(也称为序列生成器,或简称序列)的函数。序列对象是使用 CREATE SEQUENCE 创建的特殊单行表。序列对象通常用于为表中的行生成唯一标识符。在表 9.56 中列出的序列函数,提供了简单的、多用户安全的方法,用于从序列对象中获取连续的序列值。

表 9.56. 序列函数

函数

描述

nextval ( regclass ) → bigint

将序列对象推进到下一个值并返回该值。这个操作是原子的:即使多个会话并发地执行 nextval,每个会话也会安全地接收到不同的序列值。如果序列对象是用默认参数创建的,则连续的 nextval 调用将返回以 1 开始的连续值。其他行为可以通过在 CREATE SEQUENCE 命令中使用适当的参数获得。

这个函数需要序列上的 USAGE 或 UPDATE 权限。

setval ( regclass, bigint [, boolean ] ) → bigint

设置序列对象的当前值,并可选地设置其 is_called 标志。双参数形式将序列的 last_value 字段设置为指定的值,并将其 is_called 字段设置为 true,意味着下一个 nextval 将在返回值之前推进序列。currval 将报告的值也设置为指定的值。在三参数形式中,is_called 可以设置为 true 或 false。true 与双参数形式具有相同的效果。如果设置为 false,下一个 nextval 将返回指定的值,序列推进从再下一次调用 nextval 开始。而且,currval 报告的值在这种情况下不会改变。例如:

SELECT setval('myseq', 42);           下一次 nextval 将返回 43
SELECT setval('myseq', 42, true);     同上
SELECT setval('myseq', 42, false);    下一次 nextval 将返回 42

setval 返回的结果就是它的第二个参数的值。

这个函数在序列上需要 UPDATE 权限。

currval ( regclass ) → bigint

返回当前会话中最近一次针对该序列调用 nextval 所获得的值。(如果当前会话从未针对该序列调用过 nextval,则会报错。)由于返回的是会话局部值,无论其他会话是否在当前会话调用之后执行过 nextval,结果都是可预测的。

这个函数需要序列上的 USAGE 或 SELECT 权限。

lastval () → bigint

返回 nextval 在当前会话中最近返回的值。这个函数与 currval 相同,不同之处在于它没有使用序列名作为参数,而是引用当前会话中 nextval 最近应用到的序列。如果在当前会话中还没有调用 nextval,那么调用 lastval 是一个错误。

该函数在最后使用的序列上需要 USAGE 或 SELECT 权限。

pg_get_sequence_data ( regclass ) → record ( last_value bigint, is_called bool, page_lsn pg_lsn )

返回有关序列的信息。last_value 是最后一次写入磁盘的序列值。如果使用了缓存,这个值可能大于从序列中最后一次发出的值。is_called 表示该序列是否已经被使用过。page_lsn 是对应于最近一次修改此序列关系的 WAL 记录的 LSN。如果指定的关系 OID 不存在、该关系不是序列、当前用户没有序列上的 SELECT 权限、该序列是另一会话的临时序列,或者该序列是备库上的不记录 WAL 的序列,此函数将返回由 NULL 值组成的一行。

此函数主要供 pg_dump 和逻辑复制在同步序列时内部使用。


小心

为了避免阻塞从相同序列获取数字的并发事务,nextval 获得的值如果调用事务后续中止,就不会被重新使用。这意味着事务中止或数据库崩溃可能导致分配值序列中的间隙。这也可能发生在没有事务中止的情况下。例如,带有 ON CONFLICT 子句的 INSERT 将计算要插入的元组,包括执行任何必需的 nextval 调用,然后才检测到可能导致其遵循 ON CONFLICT 规则的任何冲突。因此,PostgreSQL 序列对象不能用于获取“无间隙”序列。

同样,setval 函数所做的序列状态更改立即对其他事务可见,并且如果调用事务回滚,则不会被撤消。

如果在包含 nextval 或 setval 调用的事务提交之前,数据库集簇崩溃,那么序列状态更改可能尚未传递到持久存储,因此在集簇重新启动后,无法确定序列是保持其原始状态还是更新状态。对于数据库内部使用序列而言,这是无害的,因为未提交事务的其他影响也不会可见。但是,如果您希望将序列值用于持久性的数据库外部用途,请确保在这样做之前已经提交了 nextval 调用。

序列函数所要操作的序列由 regclass 参数指定,该参数就是序列在 pg_class 系统目录中的 OID。不过,不必手动查找 OID,因为 regclass 数据类型的输入转换器会完成这项工作。详见第 8.19 节。

报告文档问题

阅读 上游文档. 反馈更正前请先核对 当前版本手册.