## 简介与适用场景 UUID（通用唯一标识符）是一种 128 位的标识符，用于在分布式系统中以极高的概率保证唯一性。然而，传统的 UUID（如 v4）是完全随机的，当将其作为数据库主键时，会导致索引插入性能不佳，因为新插入的数据会随机分布在索引的各个叶子节点上，造成索引碎片和频繁的页面分裂。 pg_uuidv7 插件引入了 UUID v7 标准的实现。UUID v7 的核心特点是**时间有序性**。它将高精度的 Unix 时间戳嵌入到 UUID 的高位字节中，而低位字节则由随机数填充以确保唯一性。这种设计带来了显著的优势： * **提升索引性能**：由于新生成的 ID 在时间上是连续的，因此它们在 B\-tree 索引中的物理位置也是相邻的。这大大提高了索引的局部性（locality），减少了随机 I/O，使得主键索引的插入性能接近于自增整数（SERIAL 或 BIGSERIAL）。 * **全局唯一性**：保留了 UUID 的核心优点，适合在分布式系统或需要合并来自不同数据源记录的场景中使用，避免了自增 ID 可能带来的冲突问题。 * **可排序性**：可以直接按 ID 排序，等同于按创建时间排序。 pg_uuidv7 是现代应用中替代自增整数或随机 UUID 作为主键的理想选择。 ## 注意事项 * **时间信息暴露**：UUID v7 中包含了生成时的时间戳信息，虽然精度很高，但这属于明确的设计特性，在某些对创建时间敏感的场景下需要注意。 * **时间戳精度**：根据官方标准，UUID v7 嵌入的时间戳精度为毫秒级。 ## 创建与删除插件 ### 创建插件执行以下 SQL 命令来创建 pg_uuidv7 插件。 ```SQL CREATE EXTENSION pg_uuidv7; SELECT * FROM pg_extension WHERE extname = 'pg_uuidv7'; ``` ### 删除插件如果不再需要，可以执行以下命令来卸载插件。 ```Bash DROP EXTENSION pg_uuidv7; ``` ## 基础使用 pg_uuidv7 提供了一系列函数用于生成和解析 UUID v7。 |**函数** |**功能说明** |**用法** | |---|---|---| |uuid_generate_v7() |生成一个标准的 UUID v7 值。这是最常用的函数，通常用作表主键的默认值。 |```SQL|\ | | |-- 生成单个 |\ | | |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。|```SQL|\ | | |SELECT uuid_timestamp_to_v7('2023-01-01 00:00:00'::timestamp);|\ | | |```|\ | | | | |uuid_timestamptz_to_v7(tstz) |将一个 timestamptz 类型的时间转换为一个 UUID v7 值。当第二个参数为 true 时，生成起始值，随机数部分为0，默认 false。 |```SQL|\ | | |SELECT uuid_timestamptz_to_v7(NOW() - INTERVAL '1 hour', true);|\ | | |```|\ | | | | |uuid_v7_to_timestamp(uuid)|从一个 UUID v7 值中提取其包含的 timestamp 时间。 |```SQL|\ | | |SELECT uuid_v7_to_timestamp('01856ad8-a4c8-72f6-bae3-30453a7eeed5');|\ | | |```|\ | | | | |uuid_v7_to_timestamptz(uuid)|从一个 UUID v7 值中提取其包含的 timestamptz 时间。 |```SQL|\ | | |SELECT uuid_v7_to_timestamptz('019b3541-5fa6-7a85-ad96-1ca1de8a39d5');|\ | | |```|\ | | | | ## 简介与适用场景 UUID（通用唯一标识符）是一种 128 位的标识符，用于在分布式系统中以极高的概率保证唯一性。然而，传统的 UUID（如 v4）是完全随机的，当将其作为数据库主键时，会导致索引插入性能不佳，因为新插入的数据会随机分布在索引的各个叶子节点上，造成索引碎片和频繁的页面分裂。 pg_uuidv7 插件引入了 UUID v7 标准的实现。UUID v7 的核心特点是**时间有序性**。它将高精度的 Unix 时间戳嵌入到 UUID 的高位字节中，而低位字节则由随机数填充以确保唯一性。这种设计带来了显著的优势： * **提升索引性能**：由于新生成的 ID 在时间上是连续的，因此它们在 B\-tree 索引中的物理位置也是相邻的。这大大提高了索引的局部性（locality），减少了随机 I/O，使得主键索引的插入性能接近于自增整数（SERIAL 或 BIGSERIAL）。 * **全局唯一性**：保留了 UUID 的核心优点，适合在分布式系统或需要合并来自不同数据源记录的场景中使用，避免了自增 ID 可能带来的冲突问题。 * **可排序性**：可以直接按 ID 排序，等同于按创建时间排序。 pg_uuidv7 是现代应用中替代自增整数或随机 UUID 作为主键的理想选择。 ## 注意事项 * **时间信息暴露**：UUID v7 中包含了生成时的时间戳信息，虽然精度很高，但这属于明确的设计特性，在某些对创建时间敏感的场景下需要注意。 * **时间戳精度**：根据官方标准，UUID v7 嵌入的时间戳精度为毫秒级。 ## 创建与删除插件 ### 创建插件执行以下 SQL 命令来创建 pg_uuidv7 插件。 ```SQL CREATE EXTENSION pg_uuidv7; SELECT * FROM pg_extension WHERE extname = 'pg_uuidv7'; ``` ### 删除插件如果不再需要，可以执行以下命令来卸载插件。 ```Bash DROP EXTENSION pg_uuidv7; ``` ## 基础使用 pg_uuidv7 提供了一系列函数用于生成和解析 UUID v7。 |**函数** |**功能说明** |**用法** | |---|---|---| |uuid_generate_v7() |生成一个标准的 UUID v7 值。这是最常用的函数，通常用作表主键的默认值。 |```SQL|\ | | |-- 生成单个 |\ | | |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。|```SQL|\ | | |SELECT uuid_timestamp_to_v7('2023-01-01 00:00:00'::timestamp);|\ | | |```|\ | | | | |uuid_timestamptz_to_v7(tstz) |将一个 timestamptz 类型的时间转换为一个 UUID v7 值。当第二个参数为 true 时，生成起始值，随机数部分为0，默认 false。 |```SQL|\ | | |SELECT uuid_timestamptz_to_v7(NOW() - INTERVAL '1 hour', true);|\ | | |```|\ | | | | |uuid_v7_to_timestamp(uuid)|从一个 UUID v7 值中提取其包含的 timestamp 时间。 |```SQL|\ | | |SELECT uuid_v7_to_timestamp('01856ad8-a4c8-72f6-bae3-30453a7eeed5');|\ | | |```|\ | | | | |uuid_v7_to_timestamptz(uuid)|从一个 UUID v7 值中提取其包含的 timestamptz 时间。 |```SQL|\ | | |SELECT uuid_v7_to_timestamptz('019b3541-5fa6-7a85-ad96-1ca1de8a39d5');|\ | | |```|\ | | | |

云数据库 PostgreSQL 版