PGXN
- 不要与 PGXS 混淆
本文档概述了 PGXN（PostgreSQL 扩展网络，以前称为“PGAN”）创建的规范。PGXN 的目的是为开源 PostgreSQL 扩展库提供一个集中式存储库和分发系统。在它的第一个迭代中，它将由四个基本部分组成
- 上传服务器。用户将能够创建登录名并上传扩展分发版。
- 一个可通过
rsync访问的扩展分发版和元数据的目录。 - 一个用于搜索扩展版本和阅读扩展文档的网站。
- 一个用于下载、测试和安装扩展的命令行客户端。
本文档概述了 PGXN 首次迭代的结构细节。
上传服务器
上传服务器的模型包括 PAUSE 和 JAUSE。界面将非常简单：一个登录网站（upload.pgxn.org），如果可能，使用现有的 postgresql.org 登录信息。从那里，用户可以将发布包上传到网站，并添加或删除发布管理员。
一旦一个包被上传，它就被认为是发布的，并且它的名称被注册到上传用户。上传服务器将把它的元数据添加到它的数据库，并将包和更新的元数据添加到可通过 rsync 访问的目录。
扩展在整个 PGXN 中是唯一的。如果用户“theory”上传了一个名为“pgTAP”的扩展，除非“theory”通过上传服务器将他们添加为发布管理员，否则其他用户将无法上传具有该名称的扩展。
上传服务器将提供一个 Web UI 用于轻松扩展发布，但也将提供一个完整的 Web API，以便发布管理可以被脚本化。
分发布局
分发版可以作为 Gzip、Bzip2 或 Zip 压缩的包上传到上传服务器。上传服务器将解压缩它，验证它的内容，并用 Zip 压缩重新打包成以 .pgz 结尾的文件。分发包需要在其根目录中有一个名为 META.json 的文件。所有其他文件和目录都是可选的，但可能需要在搜索网站或命令行客户端上增加功能。
PGXN 元数据
META.json 是一个 JSON 格式的文档，包含有关分发的元数据，遵循 CPAN 元数据规范，该规范的优势在于它是在过去十年中开发的。此元数据文件描述了扩展及其依赖项。虽然 CPAN 元数据规范支持的大多数或所有结构都将得到支持，但在最小情况下，所需的键将是
name：扩展的名称。这在 PGXN 上的所有扩展中必须是唯一的。名称“PostgreSQL”、“Postgres”、“pgsql”和“psql”将被保留。version：扩展的发布版本。这在扩展的所有版本中必须是唯一的，并且必须是数字的。license：扩展分发的许可证或许可证，定义为一组预定义字符串、URL 或标识许可证名称和 URL 的结构之一。
其他键可能需要在命令行客户端或搜索网站中添加功能。
其他内容
所有其他文件都是可选的，或者可以放置在对构建有意义的任何地方。但是，搜索网站和命令行客户端会有一些额外的组织期望。请注意，这些是建议，但将使安装扩展或在搜索网站上获得更高的可见度变得更容易。
Makefile：这是 PostgreSQL 扩展的标准 PGXS 构建系统。请参阅 contrib 模块以获取示例。t/或test/或tests/或sql/：扩展的测试套件。命令行客户端将始终查找并运行测试。如果文件在sql/中，并且还有一个expected/目录，那么测试被认为是pg_regress测试。否则，它们将被认为是 pgTAP 测试。README或README.$extension_name：可以包含任何您喜欢的内容，但建议它包含对扩展的高级介绍，作者尝试在尽可能简洁的情况下说服读者扩展有多么棒。还可以包含安装说明，或者它们可以放在单独的INSTALL文件中（当有第三方依赖项需要满足时，这可能更有用）。LICENSE：扩展和分发中的所有其他内容在什么条款下分发？Changes或ChangeLog：让用户了解最新的更改。doc或docs或documentation：扩展的文档。可以包含任意数量的文件。搜索网站会将它们转换为 HTML 以在网站上显示。它将支持的格式必须由文件名扩展名指示。最初，我们将努力支持 GitHub 支持的格式和文件名后缀。生成的 HTML 文件中<title>标记的内容将用于创建指向文档文件的链接。
PGXN 目录
整个 PGXN 目录将可通过 rsync 进行镜像。这将允许任何人出于更广泛分发或私人使用目的创建 PGXN 的镜像。镜像主机可以注册为官方镜像，在这种情况下，它们的镜像将被包含在 PGXN 数据库中，并在 PGXN 网站上列出。
搜索网站
PGXN 的主要网站将包含有关 PGXN 上所有分发版的信息，包括相关元数据。它还将包含有关注册的 PGXN 用户的信息，包括每个用户发布的扩展列表。此外，分发版中包含的任何文档都将被格式化为网站上的单个 HTML 文件。最重要的是，网站的所有内容都将被索引和搜索。此功能将以 search.cpan.org 和 OpenJSAN 为模型。
网站的首要目标是允许访问者搜索可能满足其特定需求的扩展，并在下载之前阅读文档。搜索引擎将突出显示模块的名称、摘要和关键字，并将次要重要性赋予每个模块文档的全部内容。
该网站将每小时从上传服务器更新，并将包含上传到 PGXN 的最近版本的提要。这将使人们能够轻松地在其新闻阅读器中关注 PostgreSQL 扩展社区的新发展，以及将发布信息集成到其他网站（例如 PostgreSQL 主网站上的一个框）。
该网站的第二个目标是突出显示 PostgreSQL 扩展作为一种社区资源，使人们能够通过 Google 搜索等轻松找到扩展。当博主和出版物使用指向特定扩展的文档的直接链接时，搜索排名只会提高，将包含在 PGXN 中的扩展暴露给更广泛的可见度。这种模式通过 search.cpan.org 为 Perl 社区取得了极大的成功，并且可以同样有效地突出显示 PostgreSQL 的可扩展性和扩展的可用性。
PGXN 客户端
PGXN 客户端将是一个以 CPAN 和 cpanminus 客户端为模型的命令行客户端。本质上，它将提供一个接口来轻松下载、构建、测试和安装 PGXN 分发版。它将用 Perl 编写，以最大限度地利用现有 CPAN 客户端提供的优势。
对于初始实现，PGXN 客户端将假设扩展可以使用 PGXS 构建，并使用
make USE_PGXS=1 make USE_PGXS=1 install make USE_PGXS=1 installcheck
如果分发版中没有 expected 目录，PGXN 客户端将不会运行 make installcheck，而是假设所有测试都是 pgTAP 测试，并相应地运行它们。这将降低编写测试的门槛，因为测试编写者不必像 pg_regress 所需的那样维护预期的输出文件。
PGXN 客户端不会对如何构建和安装扩展做出任何其他假设，将其留给 PostgreSQL 内核。只要 PGXS 驱动的 make 在给定平台上有效，客户端就会支持它。
PGXN 客户端可以通过配置文件以及在运行时进行配置。配置将包括（除其他设置外）
- 要使用的镜像
- 要使用的构建命令（例如，
gmake） - 要使用的安装命令（例如，
sudo make） - 缓存数据的位置（PGXN 索引、下载、构建等）
pg_config的位置
在第一次运行时，它将尽力进行自我配置，以便用户可以立即开始下载和构建扩展，而无需太多麻烦。
对 PostgreSQL 的影响
PGXN 的设计使得可以使用 PostgreSQL 本身提供的现有基础设施创建和发布扩展。它对 如何构建或改进扩展 没有意见，更专注于分发、文档、社区曝光和易于安装。无论在这方面做出什么决定，PGXN 基础设施都将根据需要进行更新，以充分利用它。
基于 PGXN 构建
一旦 PGXN 的初始实现完成并部署，我们就可以开始构建其他工具来提高它对社区和用户的价值。这些包括 PostgreSQL 内核中的工具，以便更容易创建、测试和安装扩展分发版，以及协助评估扩展的工具。
将此部分视为第二阶段项目的构想。以下是一些示例
- 新的 PGXS 目标为了使扩展创建和发布管理更简单，可以向 PostgreSQL 内核贡献一些新的 PGXS 功能。这些功能可能包括支持扩展的新 make 目标
make distmeta：从Makefile中变量的内容生成META.json文件。make test：构建一个新的数据库集群，并在未保留的端口上启动 PostgreSQL（包括make创建的任何 DSO），然后运行扩展的测试套件。make dist：创建一个准备好在 PGXN 上发布的分发包。make distcheck：类似于make dist，但它不会创建包，而是创建一个分发目录，然后运行make test。一项功能性更改可能会简化指定要安装扩展的模式，例如：psql --set INSTALLSCHEMA=extensions extesion.sql
- PGXN 评级与 CPAN 评级 类似，用户可以对单个 PGXN 扩展进行评论和评分。
- PGXN 测试人员。与 CPAN 测试人员 类似，志愿者可以设置沙箱测试环境，定期运行测试并将结果报告到中央数据库。这将允许进行持续测试，以确保扩展在各种平台和 PostgreSQL 版本上正常工作。此类结果将有助于维护人员使其扩展在受支持的环境中继续工作，并帮助用户评估扩展维护的程度。
常见问题解答
- PGXN 上允许发布什么？开源 PostgreSQL 扩展发布包。当前的 contrib 扩展是此类包内容的模型。遵循 CPAN 示例，“任何形式的商业软件，即使是共享/内疚/捐赠软件，都不会被允许……任何其他政策都可能遭到挑剔，甚至可能面临法律挑战。”
- 什么是“扩展”？扩展是向 PostgreSQL 本身添加功能的软件。例如，数据类型（CITEXT、PERIOD）、实用程序（newsysviews、pgTAP）和过程语言（PL/Ruby、PL/R）等。有关详细信息，请参阅 扩展 SQL。扩展 *不是* 在 PostgreSQL 之上运行的软件（Bricolage、Drupal）。
- PGXN 上 *不允许* 发布什么？非包文件（即不是 tarballs、bzip-balls 或 zip 档案的文件）、闭源分发以及没有许可证的分发。
- 谁可以在 PGXN 上发布？任何注册用户。
- 谁可以注册 PGXN？任何申请的人。这些注册将由志愿者批准，但如果可以使用现有的社区注册，则会优先考虑。
- 会有审批流程吗？简短回答：没有，因为 PGXN 需要 KISS。较长的回答：没有。再次遵循 CPAN 示例，PGXN “将保持一个开放和免费的论坛，作者决定上传什么。任何进一步的选择都属于不同的论坛。” 这是因为“PGXN 的首要目标 是便于提交代码并重新分发。易用性和质量控制不是 [它] 试图解决的主要问题。” 坦率地说，对发布进行审核是其他社区无法复制 CPAN 成功的一个重要原因。
- 这与 pgFoundry 有什么不同？pgFoundry 用于项目托管，包括 SCM、问题跟踪、邮件列表、Web 托管以及对与 PostgreSQL 相关的任何项目的镜像下载支持。PGXN 将用于扩展分发和镜像、简化下载和安装、文档和元数据以及搜索和报告。与 pgFoundry 唯一的共同点是上传发布包。除此之外，它们服务于截然不同的目的（项目管理与分发和曝光）。
- 我们是否需要等到 核心中的扩展？不用。contrib 扩展所展示的构建扩展的当前支持适用于大多数平台。随着核心扩展支持的改进，PGXN 客户端将更新以利用新功能。这些改进预计会使 PGXN 更成功，但现在开始并不需要这些改进。
- 但是，您是否需要先确定命名方案？这可能是理想的，但就目前而言，只需为给定的扩展要求一个唯一的名称就足够了。一旦核心支持正式扩展，其命名方案将被 PGXN 采用。
- 这是否需要更改 PGXS？不用。随着对 PGXS 的更改，PGXN 将利用这些更改，但启动 PGXN 不需要任何更改。
- PGXN 如何简化区分垃圾和可行扩展？第一步将是搜索网站，该网站将允许用户找到与他们相关的扩展并阅读其文档。正如 Robert Haas 所说，这“通常 [足够] 区分好东西和垃圾”。随着更多具有竞争功能和功能的扩展在 PGXN 上发布，添加评级功能和专门的测试也将使评估竞争选项变得更容易。
- Windows 怎么办？PGXN 客户端将始终遵循 PostgreSQL 核心安装扩展的领导。如果对 Windows 上安装扩展的支持有所改进，以至于不再需要编译器，PGXN 客户端将根据需要进行修改以利用它。这不仅适用于 Windows，还适用于核心安装程序（或任何未来的社区支持安装程序）在 *任何* 平台上运行的能力。
- 它将具有什么样的安全保障？每个发布包都将附带一个相应的 SHA1 哈希，PGXN 客户端将在安装扩展之前验证该哈希。
