使用扩展时的注意事项

2025-07-02

本文介绍在 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 EXTENSION、DROP EXTENSION 或 COMMENT ON EXTENSION 命令时出现任何错误，请参阅可能的错误列表，以及每个错误的原因。

具有特定注意事项的扩展

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

dblink
pg_buffercache
pg_cron
pg_hint_plan
pg_prewarm
pg_repack
pg_stat_statements
postgres_fdw
pgstattuple

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 灵活服务器的自动预热功能当前在 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()

为了防止出现该错误，请在azure_pg_admin的上下文中运行 pg_repack。

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。此设置可作为服务器参数配置。

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

postgres_fdw

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

pgstattuple

在使用 pgstattuple 扩展尝试从 PostgreSQL 11 至 13 版本中存储于 pg_toast 架构中的对象获取元组统计信息时，将收到“架构 pg_toast 权限被拒绝”错误。

针对架构 pg_toast 的权限被拒

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

在 PostgreSQL 16 中，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、dblink、orafce、postgres_fdw 和 timescaledb。

通过