pg_uuid_v8
带隐藏时间戳的 PostgreSQL UUID v8 生成器
仓库
ineron/pg_uuid_v8
https://github.com/ineron/pg_uuid_v8
源码
pg_uuid_v8-1.0.0.tar.gz
pg_uuid_v8-1.0.0.tar.gz
概览
| 扩展包名 | 版本 | 分类 | 许可证 | 语言 |
|---|---|---|---|---|
pg_uuid_v8 | 1.0.0 | FUNC | PostgreSQL | C |
| ID | 扩展名 | Bin | Lib | Load | Create | Trust | Reloc | 模式 |
|---|---|---|---|---|---|---|---|---|
| 4530 | pg_uuid_v8 | 否 | 是 | 否 | 是 | 否 | 否 | public |
| 相关扩展 | uuid-ossp pg_uuidv7 sequential_uuids pg_idkit pgx_ulid |
|---|
Pinned to public so uuid operator commutators resolve on PostgreSQL 17 and 18.
版本
| 类型 | 仓库 | 版本 | PG 大版本 | 包名 | 依赖 |
|---|---|---|---|---|---|
| EXT | PIGSTY | 1.0.0 | 1817161514 | pg_uuid_v8 | - |
| RPM | PIGSTY | 1.0.0 | 1817161514 | pg_uuid_v8_$v | - |
| DEB | PIGSTY | 1.0.0 | 1817161514 | postgresql-$v-pg-uuid-v8 | - |
构建
您可以使用 pig build 命令构建 pg_uuid_v8 扩展的 RPM / DEB 包：
pig build pkg pg_uuid_v8 # 构建 RPM / DEB 包
安装
您可以直接安装 pg_uuid_v8 扩展包的预置二进制包，首先确保 PGDG 和 PIGSTY 仓库已经添加并启用：
pig repo add pgsql -u # 添加仓库并更新缓存
使用 pig 或者是 apt/yum/dnf 安装扩展：
pig install pg_uuid_v8; # 当前活跃 PG 版本安装
pig ext install -y pg_uuid_v8 -v 18 # PG 18
pig ext install -y pg_uuid_v8 -v 17 # PG 17
pig ext install -y pg_uuid_v8 -v 16 # PG 16
pig ext install -y pg_uuid_v8 -v 15 # PG 15
pig ext install -y pg_uuid_v8 -v 14 # PG 14
dnf install -y pg_uuid_v8_18 # PG 18
dnf install -y pg_uuid_v8_17 # PG 17
dnf install -y pg_uuid_v8_16 # PG 16
dnf install -y pg_uuid_v8_15 # PG 15
dnf install -y pg_uuid_v8_14 # PG 14
apt install -y postgresql-18-pg-uuid-v8 # PG 18
apt install -y postgresql-17-pg-uuid-v8 # PG 17
apt install -y postgresql-16-pg-uuid-v8 # PG 16
apt install -y postgresql-15-pg-uuid-v8 # PG 15
apt install -y postgresql-14-pg-uuid-v8 # PG 14
创建扩展：
CREATE EXTENSION pg_uuid_v8;
用法
pg_uuid_v8 生成外观类似 UUID v4 的 UUID，同时在其中嵌入加密后的微秒级时间戳，便于提取、排序和范围谓词查询。SQL 文件同时暴露了 uuid_stego_* 名称和 uuid_v8_* 便捷别名。
生成 UUID
CREATE EXTENSION pg_uuid_v8;
SELECT uuid_v8_set_seed('replace-with-a-secret-seed');
SELECT uuid_v8_generate();
等价的底层生成函数是：
SELECT uuid_stego_generate();
插入事件时，可以把它用作默认表达式：
CREATE TABLE events (
id uuid PRIMARY KEY DEFAULT uuid_v8_generate(),
data jsonb,
created_at timestamptz DEFAULT now()
);
提取并查询隐藏时间戳
提取嵌入的时间戳，返回 Unix epoch 以来的微秒数：
SELECT uuid_v8_extract_timestamp(id)
FROM events
ORDER BY uuid_v8_extract_timestamp(id)
LIMIT 10;
README 建议为基于时间的查询创建函数索引：
CREATE INDEX events_uuid_v8_time_idx
ON events USING btree (uuid_v8_extract_timestamp(id));
SELECT *
FROM events
WHERE uuid_v8_extract_timestamp(id)
BETWEEN timestamp_to_stego_time('2026-01-01'::timestamptz)
AND timestamp_to_stego_time(now())
ORDER BY uuid_v8_extract_timestamp(id);
辅助函数可在时间戳和整数时间戳格式之间转换：
SELECT timestamp_to_stego_time(now());
SELECT stego_time_to_timestamp(uuid_v8_extract_timestamp(id))
FROM events;
范围辅助函数与操作符
SQL 定义包含直接的范围辅助函数：
SELECT *
FROM events
WHERE uuid_stego_in_range(
id,
now() - interval '24 hours',
now()
);
它还为 uuid 定义了感知时间戳的比较函数和操作符：
uuid_stego_compare(uuid, uuid)和uuid_v8_compare(uuid, uuid)。uuid_stego_lt、uuid_stego_le、uuid_stego_gt、uuid_stego_ge。- 操作符
<、<=、>和>=会按隐藏时间戳比较 UUID。
Seed 与加密模式
设置并查看 seed：
SELECT uuid_v8_set_seed('replace-with-a-secret-seed');
SELECT uuid_v8_get_seed();
可用加密模式为 XOR、AES128 和 AES256：
SELECT uuid_v8_get_encryption_mode();
SELECT uuid_v8_set_encryption_mode('AES128');
SELECT uuid_v8_set_encryption_mode('XOR');
如需持久化默认值，README 记录了 uuid_v8.encryption_mode GUC：
ALTER SYSTEM SET uuid_v8.encryption_mode = 'AES128';
SELECT pg_reload_conf();
注意事项
- seed 必须保密；解释隐藏时间戳时需要用到它。
- 使用某个 seed 和加密模式生成的 UUID，必须用相同设置解码。
- 基于提取时间戳的函数索引会增加存储和更新开销，但这是高效时间范围谓词的预期路径。
- 本地 Pigsty 元数据将该扩展固定在
publicschema，使 UUID 比较操作符的 commutator 能在 PostgreSQL 17 和 18 上解析；如果在非 Pigsty 构建中使用其他 schema，应显式测试这些操作符。