# 扩展等待事件

> PostgreSQL 扩展如何注册并报告自定义等待名称，以及它们为什么不进入核心大典。
---

PostgreSQL 为扩展代码报告的等待保留了 `Extension` 类型。内置清单中包含通用的 `Extension` 身份；较新版本还提供 API，让扩展注册人类可读的自定义名称。

## 本大典的边界 {#scope}

本站枚举 PostgreSQL 13–18 随核心发布的名称，**不会**试图穷举第三方扩展在运行时创建的名称，因为它取决于已加载二进制，同一版本的不同集群也可能不同。

看到扩展定义的等待时：

1. 记录 `extversion` 与扩展包的精确构建版本。
2. 在 PG17+ 查询本机 `pg_wait_events`；它是该实例已注册名称的权威来源。
3. 在扩展源码中搜索注册调用，以及配对的 `pgstat_report_wait_start()` / `pgstat_report_wait_end()`。
4. 用扩展自身 runbook 判断正常/异常；PostgreSQL 核心描述无法替它给出边界。

```sql {title="已安装扩展与扩展等待"}
SELECT e.extname, e.extversion
FROM pg_extension AS e
ORDER BY e.extname;

SELECT type, name, description
FROM pg_wait_events
WHERE type = 'Extension'
ORDER BY name;
```

> [!NOTE]
> `pg_wait_events` 从 PostgreSQL 17 开始提供。在 PG13–16 上，应从 `pg_stat_activity` 取得等待名称，再直接检查扩展版本与源码。

## 给扩展作者的安全契约 {#author-contract}

在阻塞操作紧前方报告等待，并保证包括错误在内的每条退出路径都会清除状态。名称应足够稳定，能被仪表盘与 runbook 引用；同时说明哪个资源或对端能够推进。没有这种责任契约的自定义名称只是可观测性债务。