physical-replication

Manage and debug PostgreSQL physical streaming replication with walsender and walreceiver states.

Updated Jun 1, 2026

Search Tags:#database #postgresql #streaming #replication #internals #walsender #walreceiver

Ready to run

npx skills add https://github.com/matejformanek/postgres-claude --skill physical-replication

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: physical-replication
Source: https://github.com/matejformanek/postgres-claude/tree/main/.claude/skills/physical-replication
Command: npx skills add https://github.com/matejformanek/postgres-claude --skill physical-replication

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This skill resolves the complexity of managing and debugging PostgreSQL physical streaming replication, preventing common pitfalls like replication lag, slot bloat, and synchronization stalls.

Core Features & Use Cases

State Machine Analysis: Provides deep insight into walsender and walreceiver state transitions.
Replication Diagnostics: Offers authoritative guidance on interpreting pg_stat_replication and pg_stat_wal_receiver metrics.
Use Case: When a standby is falling behind or a synchronous commit is blocking, use this skill to identify the bottleneck in the walsender state or the synchronous standby configuration.

Quick Start

Use the physical-replication skill to diagnose the current state of the walsender and identify why the standby is not receiving WAL updates.

Frequently Asked Questions about physical-replication

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I diagnose PostgreSQL streaming replication lag using pg_stat_replication?▼

Diagnose PostgreSQL streaming replication lag by interpreting pg_stat_replication and pg_stat_wal_receiver metrics to identify walsender state machine bottlenecks. This skill provides authoritative guidance on mapping these metrics to internal state transitions to pinpoint synchronization stalls.

Why does my PostgreSQL synchronous commit block standby replication?▼

Synchronous commit blocks PostgreSQL standby replication when the walsender state or synchronous standby configuration stalls. Analyze the walsender state machine transitions and verify your synchronous standby settings to resolve the bottleneck preventing WAL updates.

How does physical replication slot bloat occur in PostgreSQL?▼

Physical replication slot bloat occurs in PostgreSQL when a standby falls behind and WAL files accumulate. Use this skill to manage physical replication slots and debug WAL replay mechanics to prevent synchronization stalls and storage bloat.

How do I resolve hot standby conflicts during PostgreSQL WAL replay?▼

Resolve hot standby conflicts during PostgreSQL WAL replay by tuning replay mechanics and analyzing walreceiver state transitions. This skill guides conflict resolution for high-availability cluster configurations to ensure standby synchronization.

What do I need to configure PostgreSQL high-availability streaming replication?▼

Configuring PostgreSQL high-availability streaming replication requires deep knowledge of the replication protocol, walsender and walreceiver mechanics, and synchronous commit tuning. This skill applies internal state machine analysis to manage cluster configuration effectively.

Best way to debug a walsender state machine stall in PostgreSQL?▼

Debug a walsender state machine stall in PostgreSQL by analyzing internal state transitions and checking pg_stat_replication metrics. This skill offers state machine analysis to identify why the standby is not receiving WAL updates during streaming replication.