PGXN v2/架构

介绍

本文档概述了构建扩展分发、发现和打包工具和服务的项目，以推动Postgres扩展生态系统的增长、可访问性和实用性。它以整个Postgres社区为受众，定义了要提供的服务和运行这些服务的架构，以及指导项目规划和决策的战略愿景。

以战略思考和务实规划为目标，本文件描述了前者，以实现后者。因此，它必然是高级别的；细节、范围和规划将在更多以项目为中心的文件中浮出水面。

请记住，这份文件概述了一项雄心勃勃的长期战略。如果你认为这里有太多，我们过度思考和设计了系统，请放心，项目执行将从根本上是渐进和务实的。本文件是项目的指南，随着开发的进行和新的问题的出现，本文件可能会发生变化。

本项目的总体理念是：

• 分布式、松散配对的独立服务体系结构
• Metadata forforward以支持新颖、意外的服务
• 可供任何人使用的广泛可用性
• 全面的索引将成为所有公共可用扩展的go-to
• 首先设计，但可以灵活地定期调整
• 可行时并行构建
• 支持解耦或轻耦合交互，以实现高度并行开发
• 可用性和可用性：对扩展开发人员、服务设计人员和扩展用户来说，使用服务和工具应该尽可能简单明了，并且明显有用

当前体系结构

图1：当前架构

截至2024年初，PostgreSQL扩展分发生态系统的高级状态图。除了从PGXN公司或发布到的公共存储库和某些发布管道PGXN公司和数据库开发人员。例外情况是大旅行箱POC自动从PGXN中提取新版本。

如今的扩展生态系统由各种本地松散连接的服务组成，每个服务都旨在解决特定问题。其中包括：

• PGXN公司，旨在成为查找所有扩展并下载其源代码的综合源代码。不幸的是，它索引了大约三分之一的已知扩展，其中许多扩展多年来都没有更新。
• PostgreSQL社区打包注册中心，apt.postgresql.org网站和yum.postgresql.org网站每个扩展都包含一个子集，由社区志愿者管理，他们手动编写打包规范文件的脚本，这些规范文件从各种来源下载源代码，包括PGXN公司和源代码存储库，如github.
• 数据库开发人员、可信语言扩展的开放源代码注册中心，或特尔s、 哪些开发人员通过CLI发布。此注册表与任何其他服务都没有已知的连接，尽管公共存储库可能使用发布管道来发布TLE。
• 各种其他二进制封装程序，尤其是大旅行箱和pgxman公司项目。与社区注册中心一样，这些打包器包含可用扩展的一个子集，目前是手动维护的，并为操作系统、体系结构和Postgres版本的短列表提供二进制文件。主干路线图反映了一种雄心壮志，即成为更广泛平台上所有扩展的二进制包的默认源。为此，它实现了一个概念验证，在PGXN上自动打包新的扩展版本。

这些系统的出现几乎没有相互参考，也没有全面了解整个扩展生态系统，也没有系统地看待它们在该系统中的作用。每种方法都巧妙地解决了它要解决的问题，在功能上有一些重叠，特别是元数据管理的类似（如果不兼容）方法。

挑战

由于诚信努力的这种分散化和不协调的多样性，Postgres扩展生态系统仍然受到不足的关注，长期成功面临着许多挑战。其中包括：

• 扩展很难找到和发现。没有一个全面、规范的家可以找到并了解所有公开可用的扩展。
• 扩展仍然记录不足，难以理解。除了少数例外，大多数都附带了一个简短的自述文件（如果有意的话），而没有参考文档或教程。
• 扩展的配置和安装具有挑战性。绝大多数使用PGXS系列,制作,配置，或前列腺素受体，所有这些都需要像编译器这样的构建工具。大多数用户不需要或想要编译器，只需要一个简单的命令即可安装所需的二进制文件。唉，二进制注册中心在有限的平台上提供了相当小的扩展范围子集。
• 扩展项目的成熟度可能很难衡量。如果没有一个具有一致、可比较的统计数据、文档和元数据的中央存储库，感兴趣的用户必须寻找扩展的源代码（很难再找到！），并检查诸如存储库星号、提交历史记录和文档质量等启发，所有这些都可能在竞争项目之间产生巨大差异。
• 开发人员工具通常晦涩难懂，难以学习，而且文档记录不足。没有一种资源可以帮助初露头角的扩展开发人员学习工艺，自动化他们的流程，并为更广泛的社区做出贡献。

未来体系结构

图2：未来架构

构成拟议未来扩展分发体系结构的六个逻辑服务的高级图。这个根注册表位于中心，为其他服务提供API以供其自己的用例使用。这些服务的可信实例通过互动服务，以加强和丰富服务，更好地通知和取悦用户。

为了应对其中的许多挑战，明年该项目将建立一个由交互服务、客户端和工具组成的分布式体系结构，以推动未来扩展生态系统的增长和可访问性。

该体系结构由六个核心系统组成，每个系统都是其“拥有”的定义良好的功能单元。这些逻辑模型定义了它们如何交互的准则，而不一定是物理实体或网络图。本文档描述了下面的每一个，定义了它与其他系统以及预期构成服务的组件进行互操作的上下文。

根注册表

基础服务构成根注册表，其目标是成为公共可用扩展的综合记录系统。开发人员将向注册表发布扩展源代码，并通过其API（使用CLI（命令行界面）)或Web用户体验.

API将为注册表提供所有功能，允许客户端搜索、读取文档、下载和安装扩展、检查有关其他注册表对象（用户、分类等）的数据，以及查看或单击以读取其他统计信息和报告。

能力

• 存储层
  • 根镜像
  • 数据库
• 身份验证API
  • 注册
  • 身份验证
  • 账户管理
  • 用户管理
  • API身份验证
  • 授权（访问控制）
• 发布API
  • 发布
  • 验证
  • 所有权/权限
• 索引服务
  • 单据生成
  • 搜索索引
  • 其他索引（例如，Atom feed）
• 信息API
  • 元数据
  • 下载
  • 搜索
  • 文件
  • 配置文件（扩展、用户、分类）
  • 统计和报告（通过互动)

上下文

根注册表提供了核心功能来启用下面定义的服务。简言之：

• 这个网络用户体验服务在根注册表上提供了一个可供人访问的交互层
• 这个顾客依赖于根注册表进行扩展下载和元数据，包括二进制包信息，并可用于发布新的扩展
• 这个包装服务依赖根注册表获取源代码，并依赖交互获取新版本的通知
• 这个互动服务通过以下方式通知注册的下游服务新版本网钩s、 并提供用于提交包链接和统计和报告
• 这个统计和报告服务提供附加服务以增强扩展的价值，可以从根注册表下载源和元数据，并通过交互将数据提交回显示在网络用户体验

网络用户体验

图3：Web用户体验

的高级图网络用户体验服务与其他服务的上下文。Web UX服务在根注册表，它提供了所有的功能。它的客户端是互联网上基于网络的设备。

web服务为用户提供了使用所有根注册表API的UX。它在根注册表上作为一个设计精美的交互层发挥作用，提供了所有功能。它的客户端是互联网上基于网络的设备。

作为互动将其他API、数据和功能添加到根注册表中，web UX将更新以显示它们。

Web UX服务不一定是唯一的UX服务。作为根注册表API上的纯粹显示层，它为用户交互设置了标准，但其他人可能会构建自己的UX客户端，例如本地桌面或移动应用程序。

能力

• 搜索扩展和其他实体
• 浏览分类
• 阅读文档
• 浏览源代码
• 下载源代码
• 浏览和查看用户配置文件
• 列出最新版本
• 链接到下游二进制打包服务
• 显示第三方元数据（统计、徽章、链接等）
• 用户注册和身份验证
• 扩展管理（权限、所有权）
• API令牌管理（针对用户）和管理（针对监督）
• 用户管理和其他管理任务

上下文

Web UX服务依赖于根注册表的API来提供所有功能(图3). 虽然网站应该设计精美、吸引人、信息丰富、使用有趣，但它不应该提供自己的业务逻辑。

PGXN公司为根注册表提供了很多灵感。将其视为组合pgxn.org网站和经理.pgxn.org到单个站点。PGXN公司其本身将演变为承担此处定义的根注册表的责任，或被修改为与根注册表无缝接口，这样PGXN上的新版本也将进入根注册表。

互动

图4：相互作用

的高级图互动服务与其他服务的上下文。这个根存储库将事件发布到互动服务，然后将它们转发给注册的、受信任的包装和统计和报告通过webhooks提供服务。这些服务还可以将信息提交回互动服务，包括打包链接、聚合统计信息以及其他链接和徽章。

下游包装商也可以订阅互动事件来触发它们自己的生成。

这个根注册表将事件发布到事件流服务，事件流服务将把事件发送到网钩用于注册和批准的客户服务，特别是包装和统计和报告同时，可写API将允许受信任的、经过身份验证的客户端向注册表提交额外的元数据、打包信息、报告结果和统计信息。

交互服务的设计需要一个详细的治理规范，以确定哪些服务将被信任，它们必须满足什么标准，以及行为准则和审查节奏，以确定是否应该撤销访问。从技术上讲，它还需要一个健壮且可审计的身份验证和授权系统，以确保实施访问控制，而且管理起来很简单，即授予或撤销访问。

能力

• 事件流
  • 社交发布
  • Webhook（网钩）秒
• 编写API
  • 统计信息（下载、回购统计信息）
  • 报告（测试结果、安装结果、安全扫描）
  • 包装

上下文

交互服务作为根注册表，管理事件流并编写API以服务受信任的包装和统计和报告服务。它使用该数据更新由根注册表管理和发布的适当扩展元数据，通过网络用户体验，以更好地通知用户并取悦用户。

顾客

客户是架构（architecture）的一个关键组成部分，其目的是提供能力以授权：

• 希望查找、安装和报告扩展及其对系统的依赖性的用户
• 需要构建新项目、管理扩展元数据、在多个平台和Postgres版本上构建源代码并运行测试以及发布新版本的开发人员
• 可能依赖其广泛的构建管道和依赖关系管理功能来简化打包自动化的打包者
• CI/CD自动化

目标是构建一个强大、直观的客户端，该客户端可以轻松安装在大量操作系统和平台上（例如，单个交叉编译的Go或Rust二进制文件），并具有可识别和使用广泛配置矩阵的架构，包括：

• 操作系统：Linux、macOS、*BSD、Windows等。
• 体系结构：amd64型,臂64,i386型等。
• 处理能力：CPU、GPU、，avx512等。
• PostgreSQL版本：9.1--17
• 包装商：apt.postgresql.org网站,yum.postgresql.org网站,大旅行箱,数据库开发人员,pgxman公司等。
• 构建管道：PGXS系列,前列腺素受体,配置,制作,克马克等。
• 扩展类型：SQL扩展,背景工作者、应用程序、，可加载模块等。

目标是让客户端成为在大多数平台上开发和安装扩展的默认选择，以便与大多数PostgreSQL发行版一起使用。

能力

• 用户SDK
  • 列出扩展名
  • 搜索扩展名
  • 确定环境（Postgres版本、操作系统、体系结构）
  • 获取配置的适当二进制包
  • 解决并安装所有扩展、系统和库依赖项
  • 安装（或重新安装）软件包
  • 从源代码生成所有支持的管道
  • 验证是否已安装扩展
  • 确认安装成功
  • 创建扩展等。在一个或多个数据库中
  • 使用私有注册表和根注册表
  • 报告已安装扩展及其状态（已使用/未使用、过期）
• 开发人员SDK
  • 初始化项目
  • 管理元数据
  • 为所有支持的管道构建和安装
  • 在不同的Postgres版本上运行测试
  • 捆绑和发布
  • 发布到专用注册表
• SDK的CLI包装
• 执行CI/CD任务
• 支持尽可能多的操作系统
• 易于分发（每个OS/arch使用单个二进制文件）

上下文

如所示图2和图4，客户端与根注册表这个包装服务，以及潜在的系统和下游包装商。

客户端依赖根注册表的API来发布扩展、搜索扩展以及获取扩展的元数据。基于此元数据，它知道如何：

• 下载、构建和安装扩展及其依赖项
• 确定包装服务提供适当的二进制文件并安装它
• 评估来自下游打包商的可用二进制软件包，并选择最佳的软件包进行安装

这就是为什么客户需要对元数据有深入的了解，这样才能使元数据管理对开发人员来说尽可能简单，并代表用户做出明智的（但容易被推翻的）决策。

每一类元数据都需要大量的设计和开发。对于从源代码构建，客户必须认识到并了解如何使用各种构建管道和依赖关系管理系统。它还需要能够调整每个管道的配置，以便更好地控制扩展安装，例如防止安装某些文件（例如文档）和设置安装位置(PGDATA公司以及报告的各种目录pg_配置:粘合剂,文档目录,图书馆馆长等），尤其是从包装服务。

当使用下游打包程序时，它需要了解它管理的系统，以便能够安装尽可能最好的包及其所有依赖项。可能某种配置可以将其锁定到特定的打包程序，但同时它需要尽可能简单，以便用户轻松地查找、下载和尝试扩展。

有趣的想法

是否可以将CLI SDK用作Postgres扩展，这样就可以做客户端可以做的所有事情，或者至少安装二进制包，但只能通过SQL函数调用。请参见pginstall（pginstall）对于POC。

包装

图5：包装上下文

包装服务上下文的高级图表。这个包装服务依赖于由互动服务了解新版本，并从根注册表来构建二进制文件。对于它构建的每个二进制包，它将事件发布到互动服务。

对于此类事件互动可以为apt、yum、pgxman和trunk等下游打包程序调用webhook。然后，这些服务可以从以下位置下载二进制文件包装并将它们捆绑到特定包装系统的包装中，并将链接发布回互动.

或者，根据数据库开发人员下游打包程序可能会监听新版本的webhook事件（或依赖提要），从根注册表和绑定源中的扩展。他们还可以将链接发布回互动.

打包服务侦听网钩调用或馈送更新以下载、构建和打包各种平台的新版本。理想情况下，它将通过有效使用VM或容器来支持各种操作系统、操作系统版本、Postgres版本和体系结构。它的包只包含要安装的扩展文件，客户端将知道如何将它们安装到给定集群中。

生成的tarball（或zip文件）存储库；请参见二进制分发格式以获得灵感）将作为客户端的默认安装源。然而，其他打包程序可以依赖Packaging服务或Root Registry来构建其包。

可以通过以下方式通知这些下游打包者新的源代码发布或二进制版本互动，可信服务还提交打包链接，以及定期下载统计数据（如果可用）。

此体系结构旨在授权任意数量的实体创建和维护二进制扩展打包存储库。尽管打包服务本身的目标是覆盖90%的现代用例，但我们预计没有一种服务能够满足每个可用操作系统、平台、硬件架构或PostgreSQL版本的需求。

能力

• 用于管理生成节点的体系结构
• Webhook收听新版本
• 排队构建以构建Linux、macOS和Windows、2-3个最新操作系统版本和64位体系结构的节点（VM或容器）
• 支持针对Postgres的多个版本进行构建，至少支持那些仍由核心支持的版本
• 客户端下载源代码、构建二进制文件、组装元数据（包括特定于系统的包和库依赖项）并捆绑到zip文件中
• zip文件的公钥签名
• 将结果发布到互动所以二进制支持可以列在根注册表
• 用于下载的zip文件存储库
• 镜像（rsync？）
• 第三方构建自己的打包注册中心的协议，客户端可以透明地使用这些注册中心
• 下游打包程序要使用的二进制生成事件

我们希望该总体架构将允许任何人创建自己的注册中心，并根据打包服务创建的二进制文件或根注册中心上发布的源文件自动构建包。通过这种方式，扩展的好处可以扩展到更广泛的操作系统、平台和体系结构阵列，而不是可能的。

上下文

打包服务将通过webhook回调从互动服务。

在发布事件中，打包将从根注册表下载源代码，以便在其每个构建节点上进行构建。这些节点还将依赖客户端SDK对构建管道的广泛支持来构建扩展。构建扩展后，它将收集相关文件（控制文件、SQL脚本、动态库文件和文档），以及描述文件和二进制配置（操作系统版本、Postgres版本、体系结构、配置要求（例如。共享预加载库)、系统和库依赖性等）。

对于这样创建的每个二进制包，它将向互动服务。下游封装程序（例如，pgxman公司,自制软件,巧克力味等等）可以订阅这些事件以从打包服务创建的二进制文件构建它们自己的包。或者他们可能订阅新的发布事件并从源代码构建。

不管怎样，使用扩展的元数据，他们都可以自动构建和注册二进制包。发布包后，受信任的打包客户端可以将指向它们的链接发布回互动服务，它将更新元数据，以便链接显示在扩展的网络用户体验第页。

客户端还可以从这些链接中受益，因为它可以选择最佳可用的软件包来安装在给定的系统上。换句话说，如果要求客户端将扩展安装到基于社区Apt的Postgres集群中，它可以为扩展选择社区Apt包。对于具有不确定源的集群（例如，从源构建），默认情况下将从打包服务安装二进制文件，或者如果用户需要，从根注册表下载的源安装二进制文件。

Trusted Packagers还可以定期向互动服务，它将这些统计信息聚合在扩展元数据中，以便在站点上或由客户端显示。

统计和报告

图6：统计和报告上下文

统计和报告服务上下文的高级图表。这个统计和报告服务依赖于发布通知---webhooks来自互动或来自根注册表---执行新版本的任务。每个Stats and Reporting服务都有自己的功能，可能只是针对新的事件或按常规节奏收集有关扩展的统计信息。可信服务可以通过以下方式发布统计信息、链接、徽章等互动.

Stats and Reporting Services使用扩展进行操作，然后报告结果。受信任的实例可以向互动服务，通过显示网络用户体验和其他客户。

Stats and Reporting故意是一个超级开放的类别，意思是“用扩展做事情的服务”。这些东西可能是什么还未明确。以下是一些想法：

• 通过向社交媒体网站、电子邮件列表、Slack频道等发布新版本的服务。
• 定期报告扩展的存储库统计信息的服务，例如星、问题计数、拉入计数、贡献者数量等。更新这些统计信息以显示在网络用户体验有助于集中评估扩展质量。
• 该服务为每个版本下载扩展，并在各种OS和Postgres版本上对其进行冒烟测试，并在web上构建报告结果的矩阵。它可以提交简单的统计数据（通过/失败/跳过计数）、指示总体结果的徽章以及返回矩阵页面的链接。
• 烟雾测试服务的一个变体，它测试早期版本的升级，报告成功和失败的统计数据，并为更改产生差异。
• 允许用户对扩展进行评级或撰写评论的服务。它可能会提交一个讨论链接以及一些统计数据，如平均评分或评论数。这可以帮助用户评估扩展的质量。
• 下载每个版本的扩展并扫描其安全漏洞的服务。它可能会提交一些基本统计数据（咨询计数、质量徽章）和深入评估的链接。它甚至可以是一种付费服务，向客户收取访问更多信息的费用，或者只提供具有低漏洞扩展的私人注册中心。
• 根据自己的优先级和系统对扩展进行管理和分类的服务。它可能会提交回主要的分类术语，或用户对分类的社会上/下投票。

出于本项目的目的，我们建议实现前两个示例：社交媒体公告服务和源存储库统计聚合器。这两个服务都提供了高水平的质量信号，这对于人们了解新版本、评估开发人员活动以及证明模型并为其他人树立榜样都很重要。