在Azure Database for PostgreSQL灵活服务器中使用扩展和模块时的注意事项

本文介绍在Azure Database for PostgreSQL灵活服务器中使用某些扩展或模块的特殊注意事项。

扩展的一般注意事项

若要在Azure Database for PostgreSQL灵活服务器中使用扩展，需要：

允许扩展。如果不允许该扩展，则任何尝试执行 CREATE EXTENSION、ALTER EXTENSION、DROP EXTENSION 或 COMMENT ON EXTENSION 的操作都会失败，并出现一条错误，指出所引用的扩展不被允许。
如果扩展部署需要分配和访问共享内存的共享二进制库，并且需要在服务器启动时加载，请按照加载库中提供的说明进行操作。
在要让该扩展部署随其一起分发的 SQL 对象的数据库中，创建扩展。
删除扩展。如果要从数据库中删除该扩展分发的所有 SQL 对象。
更新扩展，将已安装的扩展部署的所有 SQL 项目更新到最新版本。
查看已安装的扩展及其相应的版本。

如果在Azure Database for PostgreSQL灵活服务器上执行CREATE EXTENSION或ALTER EXTENSIONDROP EXTENSIONCOMMENT ON EXTENSION命令时出现任何错误，请参阅可能的错误列表，以及每个错误的原因。

模块的通用注意事项

若要在Azure Database for PostgreSQL灵活服务器中使用模块，请根据shared_preload_libraries中所述将其添加到参数中。

无需将模块列入允许列表。这是扩展的专属要求。

具有特定注意事项的扩展

以下列表枚举在Azure Database for PostgreSQL灵活服务器中使用时需要特定注意事项的所有受支持的扩展：

AGE
dblink
pg_buffercache
pg_cron
pg_hint_plan
pg_prewarm
pg_repack
pg_stat_statements
pgcrypto
postgres_fdw
pgstattuple

AGE

Apache AGE 扩展是 Azure Database for PostgreSQL 支持的 PostgreSQL 的图形扩展。它提供图形数据库功能、开放 cypher 查询支持，以及对 PostgreSQL 中存储的图形数据执行复杂查询的功能。 “Apache AGE” 是一个在 Apache 许可证 2.0 下发布的开源项目。

安装 AGE

若要使用 AGE，请确保在计划使用扩展功能的数据库中“允许列表”扩展、“加载其库 ”和“安装扩展”。

dblink

该dblink扩展允许从一台Azure Database for PostgreSQL灵活服务器连接到同一服务器中的另一个或另一个数据库。 Azure Database for PostgreSQL 支持与任何 PostgreSQL 服务器的传入和传出连接。发送服务器需要允许与接收服务器建立出站连接。同样，接收服务器需要允许来自发送服务器的连接。

如果计划使用此扩展，请使用虚拟网络集成部署服务器。默认情况下，虚拟网络集成支持在虚拟网络中的服务器之间建立连接。还可以选择使用虚拟网络网络安全组来自定义访问权限。

pg_buffercache

使用 pg_buffercache 扩展检查 shared_buffers的内容。通过使用此扩展，您可以确定某个特定关系是否已缓存在shared_buffers中。此扩展可帮助你排查与缓存相关的性能问题。

此扩展是 PostgreSQL 的核心安装的一部分，易于安装。

CREATE EXTENSION pg_buffercache;

pg_cron（这是一个用于PostgreSQL的任务调度扩展名）

pg_cron 扩展是一个简单的、基于 cron 的 PostgreSQL 作业计划程序，作为扩展在数据库内运行。 pg_cron 扩展可在 PostgreSQL 数据库中运行计划性维护任务。例如，你可以定期运行表清空作业或旧数据移除作业。

pg_cron 扩展可以并行运行多个作业，但是一次最多只能运行一个作业实例。如果第二次运行应在第一次运行完成之前开始，则第二次运行将排队，并在第一次运行完成后立即开始。这样可以确保作业完全按计划的次数运行，并且不会与自身并发运行。

确保为 shared_preload_libraries 设置的值包含 pg_cron。此扩展不支持执行 CREATE EXTENSION 后加载库。如果扩展未添加到 shared_preload_libraries，或者添加扩展后未重启服务器，则任何尝试运行 CREATE EXTENSION 的行为都会导致错误，其文本显示 pg_cron can only be loaded via shared_preload_libraries，其提示是 Add pg_cron to the shared_preload_libraries configuration variable in postgresql.conf。

若要使用 pg_cron，请确保在服务器启动时加载其共享库，将其加入允许列表，并且将其安装在想要使用它创建的 SQL 项目与其功能进行交互的任何数据库中。

示例

在星期六凌晨 3:30 (GMT) 删除旧数据。

SELECT cron.schedule('30 3 * * 6', $$DELETE FROM events WHERE event_time < now() - interval '1 week'$$);

每天上午 10:00 (GMT) 在默认数据库 postgres 中运行清空作业。
```
SELECT cron.schedule('0 10 * * *', 'VACUUM');
```

取消 pg_cron 中计划的所有任务。

SELECT cron.unschedule(jobid) FROM cron.job;

查看当前使用 pg_cron 计划的所有作业。
```
SELECT * FROM cron.job;
```
每天上午 10:00 (GMT) 在 test cron 角色帐户下的数据库 azure_pg_admin 中运行清空作业。
```
SELECT cron.schedule_in_database('VACUUM',' 0 10 * * * ', 'VACUUM', 'testcron',null,TRUE);
```

pg_hint_plan

通过 pg_hint_plan 扩展，可以在 SQL 注释中使用“提示”来调整 PostgreSQL 执行计划，例如：

/*+ SeqScan(a) */

该 pg_hint_plan 扩展会在给定目标 SQL 语句的特殊窗体的注释中读取提示短语。该特定格式以字符序列 /*+ 开头，并以 */ 结尾。提示短语由提示名称和以下参数组成，用括号括起来，用空格分隔。用于可读性的新行可以分隔每个提示短语。

示例：

/*+
 HashJoin(a b)
 SeqScan(a)
 */
    SELECT *
    FROM pgbench_branches b
    JOIN pgbench_accounts an ON b.bid = a.bid
    ORDER BY a.aid;

前面的示例会使规划器使用对表 seqscan 执行 a 的结果，以 b 的方式将其与表 hashjoin 组合。

若要使用 pg_hint_plan 扩展，请确保将该扩展加入允许列表、加载其库，并在计划使用该扩展功能的数据库中安装该扩展。

pg_prewarm

pg_prewarm 扩展可将关系数据加载到缓存中。在预热缓存时，查询在重启后首次运行时具有更好的响应时间。 PostgreSQL 的 autoprewarm 功能目前在 Azure 数据库中不可用。

pg_repack

初次使用 pg_repack 扩展的用户通常会问以下问题：pg_repack 是扩展，还是像 psql 或 pg_dump 那样的客户端可执行文件？

pg_repack 实际上两者都是。 pg_repack/lib 具有扩展的代码，包括它创建的架构和 SQL 项目，以及实现其中几个函数的代码的 C 库。

另一方面，pg_repack/bin 具有客户端应用程序的代码，该应用程序知道如何与扩展中实现的可编程性元素进行交互。此客户端应用程序旨在减轻与服务器端扩展所呈现的不同界面进行交互的复杂性。它为用户提供了一些更易于理解的命令行选项。如果没有在其所指向的数据库上创建的扩展，客户端应用程序就毫无用处。服务器端扩展本身功能完全正常，但它要求用户了解复杂的交互模式。该模式包括执行查询以检索用作扩展实现的函数的输入的数据，等等。

针对架构 repack 的权限被拒

目前，由于扩展授予重新打包架构的权限，因此只能支持从上下文pg_repack中运行azure_pg_admin的功能。

你可能会注意到，如果某个表的所有者并非 azure_pg_admin，但尝试运行 pg_repack，则会收到以下错误：

NOTICE: Setting up workers.conns
ERROR: pg_repack failed with error: ERROR:  permission denied for schema repack
LINE 1: select repack.version(), repack.version_sql()

若要避免此错误，请从上下文pg_repack中运行 azure_pg_admin 。

pg_stat_statements

pg_stat_statements 扩展为您提供对数据库中所有查询的视图功能。此信息对于了解生产系统上的查询工作负载性能非常有用。

pg_stat_statements 扩展已在每个 Azure Database for PostgreSQL 灵活服务器的 shared_preload_libraries 中预加载，用于跟踪 SQL 语句执行统计信息。

出于安全原因，您必须将 pg_stat_statements 扩展加入允许列表，并使用 CREATE EXTENSION 命令安装它。

pg_stat_statements.track 设置，它可以控制扩展跟踪哪些语句，默认为 top，这意味着跟踪所有由客户端直接发布的语句。另外两个跟踪级别为 none 和 all。可以将此设置配置为参数。

扩展提供的查询执行信息 pg_stat_statements 与服务器性能之间存在权衡，因为它记录每个 SQL 语句。如果未主动使用 pg_stat_statements 扩展，请设置为 pg_stat_statements.tracknone。某些第三方监视服务可能依赖 pg_stat_statements 来提供查询性能见解，因此，请确认这是否适合你。

pgcrypto

Azure Database for PostgreSQL通过 pgcrypto PostgreSQL 扩展支持应用程序级列级加密。 pgcrypto 扩展使应用程序能够使用基础 OpenSSL 库提供的加密算法显式调用 PostgreSQL SQL 语句中的加密函数来加密或哈希列值。

从 Azure Linux 3.0 开始，OS 使用 OpenSSL 3.0，后者将多个较旧和较弱的加密算法和低级别 API 移到默认未加载的单独旧提供程序中。此更改鼓励使用新式、更安全的加密算法和高级 OpenSSL EVP（信封）API。

因此，在运行 Azure Linux 3.0 的 Azure Database for PostgreSQL 服务器上，OpenSSL 3.0 归类为遗留的加密算法默认无法供 pgcrypto 使用。

弃用的加密算法

以下旧加密算法位于 OpenSSL 3.0 旧提供程序中，默认情况下在运行 Azure Linux 3.0 的 Azure Database for PostgreSQL 服务器上不可用。早期平台版本可能允许 pgcrypto 使用这些算法，但Azure Linux 3.0 不再支持它们。

对称加密算法（密码）

Blowfish（BF-CBC）
CAST
DES（单个 DES;而不是 3DES）
想法
RC2
RC4
RC5
种子

消息摘要和哈希算法

MD2
MD4
MDC2
RIPEMD-160
SHA-1（已弃用数字签名，但仍可能允许针对特定 HMAC 方案，具体取决于配置）
惠而浦

Azure Database for PostgreSQL升级到 Azure Linux 3.0 是正在进行的平台改进的一部分。依赖 pgcrypto 的应用程序应确保在执行应用程序级列级加密时使用新式支持的加密算法。

postgres_fdw

该postgres_fdw扩展使你能够从一台Azure Database for PostgreSQL灵活服务器连接到另一台服务器或同一服务器中的另一个数据库。 Azure Database for PostgreSQL 支持与任何 PostgreSQL 服务器的传入和传出连接。发送服务器需要允许与接收服务器建立出站连接。同样，接收服务器需要允许来自发送服务器的连接。

pgstattuple

在 Postgres 11 到 13 版本中，当你使用 pgstattuple 扩展尝试获取保存在 pg_toast 架构中的对象的元组统计信息时，会收到“架构 pg_toast 的权限被拒绝”错误。

针对架构 pg_toast 的权限被拒

在 Azure Database for PostgreSQL 灵活服务器上使用 PostgreSQL 11 到 13 版本的客户，无法对 pgstattuple 架构中的对象使用 pg_toast 扩展。

在 PostgreSQL 16 和 17 中，pg_read_all_data 角色会自动授予给 azure_pg_admin，从而使 pgstattuple 能够正常运行。在 PostgreSQL 14 和 15 中，客户可以手动授予 pg_read_all_dataazure_pg_admin 角色以实现相同的结果。但是，在 PostgreSQL 11 到 13 中，pg_read_all_data 角色不存在。

客户无法直接授予所需的权限。如果需要运行pgstattuple以访问架构下pg_toast的对象，请继续创建Azure 支持请求。

timescaleDB

timescaleDB 扩展是一个时序数据库，已作为 PostgreSQL 的扩展打包。它提供以时间为导向的分析功能和优化，增强 Postgres 的性能以支持时序数据工作负载。了解有关 TimescaleDB 的更多信息，它是 Timescale, Inc. 的注册商标。Azure Database for PostgreSQL 提供 TimescaleDB Apache-2 版本。

安装 TimescaleDB

若要使用 timescaleDB，请确保将扩展加入允许列表中、加载其库，并且在计划使用其功能的数据库中安装扩展。

现在可以从头开始创建 TimescaleDB hypertable，也可以迁移 PostgreSQL 中的现有时序数据。

有关使用 pg_dump 和 pg_restore 还原时间刻度数据库的详细信息，请参阅时间刻度文档。

使用 timescaledb-backup 还原 Timescale 数据库

在运行 SELECT timescaledb_post_restore() 过程期间，可能会在更新 timescaledb.restoring 标志时出现权限被拒问题。之所以收到此错误是因为 Cloud PaaS 数据库服务中的 ALTER DATABASE 权限有限。在这种情况下，可以使用 timescaledb-backup 工具来备份和还原 Timescale 数据库，以执行替代方法。 Timescaledb-backup 是一种使转储和还原 TimescaleDB 数据库更简单、更不容易出错且性能更高的程序。

为此，请按照以下步骤操作：

安装工具，详细信息见此处。
创建目标Azure Database for PostgreSQL灵活服务器和数据库。
启用 Timescale 扩展。
向 azure_pg_admin 使用的用户授予角色。
运行 ts-restore 以还原数据库。

有关这些实用工具的更多详细信息，请参阅此处。

扩展和主要版本升级

Azure Database for PostgreSQL 提供就地主版本升级功能，只需用户进行简单操作，即可对 Azure Database for PostgreSQL 灵活服务器执行就地升级。在线重大版本升级简化了 Azure Database for PostgreSQL 的升级过程，最大限度减少用户和应用程序在访问服务器时的中断。主版本就地升级不支持特定扩展，并且在升级某些扩展时存在一些限制。

使用就地主要版本更新功能时，并非所有 Azure Database for PostgreSQL 灵活服务器版本都支持扩展 anon、Apache AGE、dblink、orafce、postgres_fdw 和 timescaledb。

具有特定注意事项的模块

以下列表枚举在 Azure Database for PostgreSQL 灵活服务器中使用时需要特定注意事项的所有受支持的模块：

pg_failover_slots

pg_failover_slots

该 pg_failover_slots 模块在启用逻辑复制功能和高可用性功能的服务器上运行时，增强了 Azure Database for PostgreSQL。它有效地解决了在故障转移后不保留逻辑复制槽的标准 PostgreSQL 引擎中的难题。维护这些插槽对于防止在主服务器角色更改期间出现复制暂停或数据不匹配至关重要，确保操作连续性和数据完整性。

该扩展通过管理复制槽所需的传递、清理和同步来简化故障转移过程，从而在服务器角色更改期间实现无缝转换。

可以在其 pg_failover_slots找到有关使用该模块的详细信息和说明。

若要使用该 pg_failover_slots 模块，请确保在服务器启动时加载其库。

Last updated on 2026-07-24