buffer-manager

Manage PostgreSQL shared-buffer pin/unpin lifecycle and clock-sweep replacement.

Updated Jun 1, 2026
One-click install
npx skills add https://github.com/matejformanek/postgres-claude --skill buffer-manager
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: buffer-manager
Source: https://github.com/matejformanek/postgres-claude/tree/main/.claude/skills/buffer-manager
Command: npx skills add https://github.com/matejformanek/postgres-claude --skill buffer-manager

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This skill resolves ambiguity regarding PostgreSQL's shared-memory page cache, preventing common errors like buffer refcount leaks, incorrect locking order, and inefficient buffer access strategy implementation.

Core Features & Use Cases

  • Internals Guidance: Provides authoritative documentation on BufferDesc state bits, clock-sweep replacement, and pin/unpin discipline.
  • Patch Support: Offers structured checklists for adding new BufferAccessStrategy rings or debugging buffer-related warnings.
  • Use Case: When investigating a buffer leak warning or implementing a custom bulk-read strategy, this skill provides the exact file-level context and safety requirements needed to modify bufmgr.c correctly.

Quick Start

Use the buffer-manager skill to analyze the current pin-unpin discipline and identify potential leaks in the provided source code.

Frequently Asked Questions about buffer-manager

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

FAQPage Schema
How does the PostgreSQL buffer manager handle pin and unpin operations?

The PostgreSQL buffer manager enforces strict pin and unpin discipline through BufferDesc state bits and atomic state transitions, preventing buffer refcount leaks by ensuring pages are safely held in shared memory during access.

What is clock-sweep replacement in PostgreSQL shared buffers?

Clock-sweep replacement is PostgreSQL's buffer eviction algorithm that cycles through the shared buffer pool, selecting unpinned buffers for reuse to maintain efficient memory utilization without discarding frequently accessed pages.

How do I debug a buffer refcount leak warning in bufmgr.c?

Debug a buffer refcount leak warning by analyzing the pin and unpin lifecycle in your source code, checking LWLock acquisition order, and verifying atomic state transitions against the safety checklists provided for bufmgr.c modifications.

How to implement a custom BufferAccessStrategy for bulk reads in PostgreSQL?

Implement a custom BufferAccessStrategy by adding new ring buffers to the storage layer, following structured patch checklists to ensure correct shared-memory page cache access and prevent inefficient buffer eviction during bulk operations.

Do I need deep knowledge of LWLocks to modify PostgreSQL storage layer functionality?

Yes, modifying PostgreSQL storage layer functionality requires deep knowledge of LWLocks, BufferDesc state bits, and atomic state transitions to ensure memory safety and correct locking order when extending shared-buffer operations.

Why am I getting incorrect locking order errors with PostgreSQL shared-memory page cache?

Incorrect locking order errors occur when shared-memory page cache operations acquire LWLocks in the wrong sequence, which can be resolved by reviewing atomic state transitions and pin and unpin discipline requirements.