文档中心

AI 原生 BaaS 平台 Supabase 版

插件

时间有序的全局唯一标识符（pg_uuidv7）

简介与适用场景

UUID（通用唯一标识符）是一种 128 位的标识符，用于在分布式系统中以极高的概率保证唯一性。然而，传统的 UUID（如 v4）是完全随机的，当将其作为数据库主键时，会导致索引插入性能不佳，因为新插入的数据会随机分布在索引的各个叶子节点上，造成索引碎片和频繁的页面分裂。

pg_uuidv7 插件引入了 UUID v7 标准的实现。UUID v7 的核心特点是时间有序性。它将高精度的 Unix 时间戳嵌入到 UUID 的高位字节中，而低位字节则由随机数填充以确保唯一性。这种设计带来了显著的优势：

提升索引性能：由于新生成的 ID 在时间上是连续的，因此它们在 B-tree 索引中的物理位置也是相邻的。这大大提高了索引的局部性（locality），减少了随机 I/O，使得主键索引的插入性能接近于自增整数（SERIAL 或 BIGSERIAL）。

pg_uuidv7 是现代应用中替代自增整数或随机 UUID 作为主键的理想选择。

注意事项

创建与删除插件

创建插件

执行以下 SQL 命令来创建 pg_uuidv7 插件。

删除插件

如果不再需要，可以执行以下命令来卸载插件。

基础使用

pg_uuidv7 提供了一系列函数用于生成和解析 UUID v7。

函数	功能说明	用法
uuid_generate_v7()	生成一个标准的 UUID v7 值。这是最常用的函数，通常用作表主键的默认值。	-- 生成单个 SELECT uuid_generate_v7(); -- 结合默认值使用 CREATE TABLE events ( id UUID PRIMARY KEY DEFAULT uuid_generate_v7(), event_data JSONB ); INSERT INTO events (event_data) VALUES ('{"type": "login"}');
uuid_timestamp_to_v7(ts)	将一个 timestamp 类型的时间转换为一个 UUID v7 值。当第二个参数为 true 时，生成起始值，随机数部分为0，默认 false。	SELECT uuid_timestamp_to_v7('2023-01-01 00:00:00'::timestamp);
uuid_timestamptz_to_v7(tstz)	将一个 timestamptz 类型的时间转换为一个 UUID v7 值。当第二个参数为 true 时，生成起始值，随机数部分为0，默认 false。	SELECT uuid_timestamptz_to_v7(NOW() - INTERVAL '1 hour', true);
uuid_v7_to_timestamp(uuid)	从一个 UUID v7 值中提取其包含的 timestamp 时间。	SELECT uuid_v7_to_timestamp('01856ad8-a4c8-72f6-bae3-30453a7eeed5');
uuid_v7_to_timestamptz(uuid)	从一个 UUID v7 值中提取其包含的 timestamptz 时间。	SELECT uuid_v7_to_timestamptz('019b3541-5fa6-7a85-ad96-1ca1de8a39d5');

最近更新时间：2026.02.27 20:56:03

这个页面对您有帮助吗？

有用

无用