---
name: postgres-drop-stale-replication-slot
description: Drop a replication slot that is pinning WAL and filling the disk, after confirming nothing is consuming it.
runbook:
  schema_version: v1
  semver: 1.0.0
  profile: P1
  min_runtime_profile: R2
  domain: databases
  targets:
    - postgres
  trigger: alert
  execution: human-with-agent
  risk: destructive
  blast_radius: service
  duration: 5-30m
  capabilities:
    - cli:psql
  publisher: std
  lang: en
  license: CC-BY-4.0
  inputs:
    slot:
      type: string
      required: true
      description: replication slot name
  steps:
    - id: s1
      kind: check
      title: Confirm the slot is inactive
      tool: cli:psql
      command: psql -tAc "select active from pg_replication_slots where slot_name='{{inputs.slot}}'"
      expect: active is false
      assert:
        exit_code: 0
        stdout_matches: ^f$
      on_fail: escalate:s9
      next: s2
    - id: s2
      kind: action
      title: Drop the replication slot
      risk: destructive
      requires_approval: true
      rollback_ref: s4
      tool: cli:psql
      command: psql -tAc "select pg_drop_replication_slot('{{inputs.slot}}')"
      next: s3
    - id: s3
      kind: check
      title: Confirm WAL is releasing
      tool: cli:psql
      command: psql -tAc "select pg_wal_lsn_diff(pg_current_wal_lsn(),'0/0')"
      expect: pg_wal stops growing
      assert:
        exit_code: 0
      on_fail: s4
      next: end:success
    - id: s4
      kind: action
      title: Recreate the replication slot
      risk: reversible-write
      tool: cli:psql
      command: psql -tAc "select pg_create_physical_replication_slot('{{inputs.slot}}')"
      next: end:aborted
    - id: s9
      kind: escalate
      title: Escalate to the database owner
      to: team:dba
  source:
    url: https://runbooks.directory/r/std/postgres-drop-stale-replication-slot/source.md
    fetched_at: 2026-09-02
    upstream_state: current
---

## When to reach for this

WAL is accumulating and a replication slot with no consumer is pinning it. Confirm the
slot is genuinely inactive first: dropping an active slot breaks the replica using it.

## Notes

This procedure is destructive, and its rollback recreates the slot without recovering the
WAL already released. The gate before the drop is the point at which someone decides that
trade is acceptable.