# IPC: RestoreCommand

> Waiting for restore_command to complete
---

<div class="event-kicker">PostgreSQL wait event dossier</div>
<div class="event-identity">
  <span>Class<strong>IPC</strong></span>
  <span>Event<strong><code>RestoreCommand</code></strong></span>
  <span>Versions<strong>PG 15-18</strong></span>
  <span>Evidence<strong>2 source location(s)</strong></span>
</div>

## Official description {#official-description}

Waiting for restore_command to complete

| PG 13 | PG 14 | PG 15 | PG 16 | PG 17 | PG 18 |
| :---: | :---: | :---: | :---: | :---: | :---: |
| — | — | ✓ | ✓ | ✓ | ✓ |

## Trigger mechanism {#mechanism}

`WAIT_EVENT_RESTORE_COMMAND` at `src/backend/access/transam/xlogarchive.c:162` is the grep-verified reporting path. The public identity/resource is mapped at `src/backend/utils/activity/wait_event_names.txt:156`. The instrumented operation is: Waiting for restore_command to complete. The RestoreCommand path has reached a process-coordination point and sleeps until a peer, worker, barrier, queue, or replication phase signals progress.

## Normal or trouble? {#normal-vs-trouble}

- <span class="severity-normal">**Normal:**</span> Brief rendezvous is normal when every participant continues to advance.
- <span class="severity-watch">**Investigate:**</span> Investigate when the same phase persists across three samples, the expected peer is absent or blocked, or a queue and its dependants stop moving.

## Diagnostic SQL {#diagnostic-sql}

```sql {title="Sessions waiting on IPC/RestoreCommand"}
SELECT pid, backend_type, usename, datname, application_name,
       state, now() - query_start AS query_age,
       now() - xact_start AS xact_age,
       wait_event_type, wait_event,
       pg_blocking_pids(pid) AS blocking_pids,
       left(query, 160) AS query
FROM pg_stat_activity
WHERE wait_event_type = 'IPC'
  AND wait_event = 'RestoreCommand'
ORDER BY query_age DESC NULLS LAST;
```

```sql {title="Current IPC cohort"}
SELECT wait_event, count(*) AS waiting_sessions,
       count(*) FILTER (WHERE state = 'active') AS active_waiters,
       max(now() - query_start) AS oldest_query
FROM pg_stat_activity
WHERE wait_event_type = 'IPC'
GROUP BY wait_event
ORDER BY waiting_sessions DESC, wait_event;
```

```sql {title="Lock and relation context for these sessions"}
SELECT a.pid, l.locktype, l.mode, l.granted, l.fastpath,
       d.datname, n.nspname, c.relname,
       l.page, l.tuple, l.virtualxid, l.transactionid,
       l.classid, l.objid, l.objsubid
FROM pg_stat_activity AS a
LEFT JOIN pg_locks AS l ON l.pid = a.pid
LEFT JOIN pg_database AS d ON d.oid = l.database
LEFT JOIN pg_class AS c
  ON c.oid = l.relation
 AND l.database = (
       SELECT oid FROM pg_database WHERE datname = current_database()
     )
LEFT JOIN pg_namespace AS n ON n.oid = c.relnamespace
WHERE a.wait_event_type = 'IPC'
  AND a.wait_event = 'RestoreCommand'
ORDER BY a.pid, l.granted, l.locktype, l.mode;
```

## Response {#response}

1. Identify the peer or phase named by the event.
2. Inspect that participant's wait, error, and progress state.
3. Repair the stalled participant or upstream dependency instead of treating the waiter as the root cause.

## Source evidence {#source}

- [PostgreSQL 18.6 · src/backend/access/transam/xlogarchive.c:162](https://github.com/postgres/postgres/blob/REL_18_6/src/backend/access/transam/xlogarchive.c#L162) — `WAIT_EVENT_RESTORE_COMMAND`
- [PostgreSQL 18.6 · src/backend/utils/activity/wait_event_names.txt:156](https://github.com/postgres/postgres/blob/REL_18_6/src/backend/utils/activity/wait_event_names.txt#L156) — `RESTORE_COMMAND`

## Related controls and signals {#related}

- **GUCs:** None directly.
- **Metrics:** [[metric:waiting_sessions]](/metric/waiting-sessions/) · [[metric:wait_event_share]](/metric/wait-event-share/)