skills.rest
matejformanek
matejformanekCOMMUNITY
Explore all skills by this author →
GitHub

pgstat-framework

Guides implementation of PostgreSQL cumulative-statistics features and debug workflows.

Updated Jun 1, 2026
Search Tags:#debugging#postgresql#backend#observability#statistics#internals
One-click install
npx skills add https://github.com/matejformanek/postgres-claude --skill pgstat-framework
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: pgstat-framework
Source: https://github.com/matejformanek/postgres-claude/tree/main/.claude/skills/pgstat-framework
Command: npx skills add https://github.com/matejformanek/postgres-claude --skill pgstat-framework

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This skill resolves the complexity of navigating PostgreSQL's cumulative statistics framework, helping developers avoid common pitfalls like pending-flush delays and incorrect file selection when debugging or extending observability.

Core Features & Use Cases

  • Observability Guidance: Provides authoritative mapping for cumulative stats, backend progress reporting, and wait events.
  • Patch Support: Offers checklists for adding new stat counters, wait events, or progress-reporting phases.
  • Debugging: Helps diagnose why statistics appear as zero by explaining the pending-to-shared flush cadence and shared-memory architecture.

Quick Start

Use the pgstat-framework skill to guide the implementation of a new custom wait event in the backend.

Frequently Asked Questions about pgstat-framework

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

FAQPage Schema
Why are my PostgreSQL statistics showing as zero in the shared memory?▼

PostgreSQL cumulative statistics show as zero because of the pending-to-shared flush cadence, where counters remain in local memory before flushing to shared memory. This delay is a standard part of the observability subsystem architecture.

How do I add a new custom wait event in PostgreSQL backend?▼

To add a custom wait event in the PostgreSQL backend, follow the patch checklist within the src/backend/utils/activity/ directory, ensuring adherence to PG-15+ shared-memory design patterns and refcount protocols.

What is the best way to implement new stat counters in PostgreSQL's cumulative statistics framework?▼

Implementing new stat counters requires following the PG-15+ shared-memory design patterns and flush cadence requirements within the cumulative-statistics framework. This ensures correct refcount protocols and observability subsystem integration.

Does the PostgreSQL cumulative statistics framework support backend progress reporting?▼

Yes, the PostgreSQL cumulative statistics framework supports backend progress reporting mechanisms. It provides architectural context and authoritative mapping for adding new progress-reporting phases within the observability subsystem.

How does the pending flush cadence affect PostgreSQL observability and debugging?▼

The pending flush cadence affects observability by delaying the synchronization of backend local statistics to shared memory. Understanding this cadence is crucial for diagnosing zero statistics and avoiding incorrect file selection when debugging.

When do I need to use refcount protocols in PostgreSQL statistics development?▼

Refcount protocols are required when developing new stat counters or wait events within the PostgreSQL shared-memory design patterns. They ensure safe memory management and adherence to PG-15+ cumulative-statistics framework standards.

Related Skills

Explore More Software Engineering Skills→
matejformanekmatejformanek

type-cache

Analyze PostgreSQL backend type-info cache internals for invalidation and typmod registry issues.

Community
Advanced
daishimandaishiman
6

debounce-throttle-patterns

Implement debounce and throttle patterns for high-frequency event processing in TypeScript.

Community
Basic
chicanoandres702chicanoandres702

backend-architect

Design scalable backend architectures for microservices and distributed systems.

Community
Advanced
matejformanekmatejformanek

parallel-query

Manage ParallelContext lifecycles and shared memory for PostgreSQL parallel queries.

Community
Advanced