pg_uuidv7：在Postgres中使用新的v7 UUID

一个小型Postgres扩展，用于在Postgres中创建有效的版本7 UUID。

这些是常规的Postgres UUID，因此可以用作主键、与字符串相互转换、包含在索引中等：

SELECT uuid_generate_v7();

           uuid_generate_v7           
--------------------------------------
 018570bb-4a7d-7c7e-8df4-6d47afd8c8fc
(1 行)

可以提取这些UUID的时间戳部分：

SELECT uuid_v7_to_timestamptz('018570bb-4a7d-7c7e-8df4-6d47afd8c8fc');
   uuid_v7_to_timestamptz
----------------------------
 2023-01-02 04:26:40.637+00
(1 行)

时间戳可以转换为v7 UUID：

SELECT uuid_timestamptz_to_v7('2023-01-02 04:26:40.637+00');
        uuid_timestamptz_to_v7
--------------------------------------
 018570bb-4a7d-7630-a5c4-89b795024c5d
(1 行)

-- 对于日期范围查询，将第二个参数设置为true以将随机位归零
SELECT uuid_timestamptz_to_v7('2023-01-02 04:26:40.637+00', true);
        uuid_timestamptz_to_v7
--------------------------------------
 018570bb-4a7d-7000-8000-000000000000
(1 行)

uuid_generate_v7()的速度几乎与原生的gen_random_uuid()函数一样快。有关更多详细信息，请参阅基准测试。

背景

版本7 UUID有几个优点。它们包含一个48位的Unix时间戳，精确到毫秒，并且将在遥远的未来（公元10899年）溢出。它们还包含74个随机位，这意味着每秒可以创建数十亿个而不会发生冲突。由于其结构，它们可以全局排序，并且可以在分布式系统中并行创建。

快速开始

[!重要] 以下说明适用于x86_64 Linux。在其他架构上，请按照构建说明进行操作。

1. 下载最新的.tar.gz发布版并将其解压到临时目录
2. 将适合您Postgres版本的pg_uuidv7.so复制到Postgres模块目录
3. 将pg_uuidv7--1.5.sql和pg_uuidv7.control复制到Postgres扩展目录
4. 使用CREATE EXTENSION pg_uuidv7;在数据库中启用扩展

# 安装pg_uuidv7的示例shell脚本
cd "$(mktemp -d)"
curl -LO "https://github.com/fboulnois/pg_uuidv7/releases/download/v1.5.0/{pg_uuidv7.tar.gz,SHA256SUMS}"
tar xf pg_uuidv7.tar.gz
sha256sum -c SHA256SUMS
PG_MAJOR=$(pg_config --version | sed 's/^.* \([0-9]\{1,\}\).*$/\1/')
cp "$PG_MAJOR/pg_uuidv7.so" "$(pg_config --pkglibdir)"
cp pg_uuidv7--1.5.sql pg_uuidv7.control "$(pg_config --sharedir)/extension"
psql -c "CREATE EXTENSION pg_uuidv7;"

构建

本地构建

pg_uuidv7只需要libpq头文件和Postgres扩展工具来构建代码。在Debian上，这些头文件包含在libpq-dev和postgresql-server-dev-all包中。

要构建代码，运行make。要在本地安装扩展，运行make install。

使用Docker构建

提供了一个Dockerfile，可以使用官方Postgres Docker镜像构建代码：

docker build . --tag pg_uuidv7

GitHub上有一个预构建的x86_64版本的镜像：

docker pull ghcr.io/fboulnois/pg_uuidv7:1.5.0

预构建镜像与普通Postgres实例类似，因此需要手动或使用初始化脚本通过CREATE EXTENSION pg_uuidv7;启用扩展。

测试

提供了一个单独的Dockerfile，用于针对特定版本的Postgres构建扩展并运行回归测试：

docker build . --file test/Dockerfile --tag pgxn-test
docker run --rm -it pgxn-test /bin/sh
# 进入容器后
pg-start 16
pg-build-test

贡献

有关更多详细信息，请参阅CONTRIBUTING.md文件。简而言之，请遵循样式指南，同意开发者原创证书，并提交PR。