# Extension wait events

> How PostgreSQL extensions register and report custom wait-event names, and why they are outside the core catalogue.
---

PostgreSQL reserves the `Extension` wait-event type for waits reported by extension code. The built-in inventory contains the generic `Extension` identity, while newer releases also expose APIs that let extensions register human-readable custom names.

## Boundary of this atlas {#scope}

This site inventories the core names shipped by PostgreSQL 13–18. It does **not** attempt to enumerate names created at runtime by third-party extensions because that set depends on the loaded binaries and can differ between clusters.

When you see an extension-defined wait:

1. Record `extversion` and the exact extension package build.
2. Query the local `pg_wait_events` view on PG17+; it is the authority for names registered in that instance.
3. Search the extension source for its registration call and matching `pgstat_report_wait_start()` / `pgstat_report_wait_end()` pair.
4. Use the extension's runbook for normal/trouble boundaries; the PostgreSQL core description cannot supply them.

```sql {title="Installed extensions and extension waits"}
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` exists in PostgreSQL 17 and later. On PG13–16, identify the wait name from `pg_stat_activity` and inspect the extension version/source directly.

## Safety contract for extension authors {#author-contract}

Report the wait immediately before the blocking operation and clear it on every exit path, including errors. Keep the name stable enough for dashboards and runbooks, and document which resource or peer can make progress. A custom name without that ownership contract is observability debt.