planner-cost-model

Analyze PostgreSQL query planner cost estimation to identify performance bottlenecks.

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

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This skill resolves uncertainty in PostgreSQL query performance by providing an authoritative reference for how the planner estimates costs, helping developers debug suboptimal plan choices and tune database configuration parameters.

Core Features & Use Cases

  • Cost Estimation Analysis: Deep dive into how the planner calculates startup and total costs for various node types like SeqScan, IndexScan, and HashJoin.
  • GUC Tuning: Guidance on adjusting cost-related configuration parameters such as random_page_cost and parallel_setup_cost to align with specific hardware profiles like SSDs or high-memory systems.
  • Plan Debugging: Provides a structured approach to identifying whether a bad plan is caused by incorrect cost function estimates or inaccurate selectivity statistics.

Quick Start

Use the planner-cost-model skill to analyze why the query planner is choosing a sequential scan over an index scan for the current table.

Frequently Asked Questions about planner-cost-model

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

FAQPage Schema
How does the PostgreSQL query planner estimate costs for different scan types?

The PostgreSQL query planner estimates costs by calculating startup and total costs for node types like SeqScan, IndexScan, and HashJoin. This analysis evaluates the internal cost functions defined in the planner's path costsize logic.

Why does PostgreSQL choose a sequential scan instead of an index scan?

PostgreSQL chooses a sequential scan over an index scan when cost function estimates or inaccurate selectivity statistics mislead the planner. Debugging this requires analyzing whether the bad plan stems from incorrect cost estimates or outdated table statistics.

How do I tune PostgreSQL cost parameters like random_page_cost for SSDs?

Tune PostgreSQL cost parameters like random_page_cost and parallel_setup_cost to align with specific hardware profiles such as SSDs. Adjusting these GUC parameters ensures the planner's cost estimations accurately reflect your high-memory system's physical disk access patterns.

What is the impact of parallel execution settings on PostgreSQL query paths?

Parallel execution settings impact PostgreSQL query paths by altering the estimated overhead of parallel worker setup. Modifying parallel_setup_cost within the planner's cost model directly influences whether the optimizer selects parallel execution plans for specific queries.

How to debug a bad PostgreSQL query plan caused by incorrect cost estimates?

Debug a bad PostgreSQL query plan by evaluating the planner's cost estimation logic to identify performance bottlenecks. Use a structured approach to isolate whether suboptimal plan choices originate from inaccurate cost function estimates or flawed selectivity statistics.

Do I need deep knowledge of database internals to optimize PostgreSQL query planning?

Optimizing PostgreSQL query planning requires deep knowledge of database internals, specifically the source code handling cost estimation. Accurate diagnostic guidance for suboptimal plan choices depends on understanding the planner's path costsize logic and related cost-model internals.