PostgreSQL Performance & Query Optimization · Lesson

Using pg_stat_statements and pg_buffercache

Leverage powerful extensions like `pg_stat_statements` and `pg_buffercache` for deep performance insights.

Using pg_stat_statements and pg_buffercache is a free PostgreSQL Performance & Query Optimization lesson on CoddyKit — lesson 1 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the PostgreSQL Performance & Query Optimization learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

PostgreSQL Extensions: Power-Ups

PostgreSQL is incredibly powerful, and its functionality can be extended even further using extensions.

Extensions are modules that add new functions, data types, operators, and more to your database. They're like plugins that enhance your database's capabilities without modifying its core code.

In this lesson, we'll explore two crucial extensions for performance monitoring: pg_stat_statements and pg_buffercache.

Meet pg_stat_statements: Query Profiler

pg_stat_statements is an invaluable tool for understanding your database's workload. It tracks execution statistics for all SQL statements executed by the server.

This extension helps you identify:

Which queries are run most frequently.
Which queries consume the most total time.
Queries with high average execution times.
Queries that read/write a lot of disk blocks.

It's your go-to for pinpointing performance bottlenecks at the query level.

Activating pg_stat_statements

To use pg_stat_statements, you first need to enable it in your PostgreSQL configuration.

1. Edit your postgresql.conf file and add pg_stat_statements to the shared_preload_libraries parameter. E.g., shared_preload_libraries = 'pg_stat_statements'.

2. Restart your PostgreSQL server for the change to take effect.

3. Finally, connect to your database and create the extension:

CREATE EXTENSION pg_stat_statements;

Deciphering pg_stat_statements Output

Once enabled, pg_stat_statements collects data in a view named pg_stat_statements. Here are some key columns you'll often check:

query: The normalized SQL statement.
calls: How many times the query was executed.
total_time: Total time spent executing this query (in milliseconds).
mean_time: Average execution time per call.
rows: Total rows returned or affected.
shared_blks_hit / shared_blks_read: Cache hits vs. disk reads.

Sorting by total_time helps find the biggest overall resource consumers.

Practical Example: Top Queries

Let's see how to find the top 5 queries that have consumed the most total execution time. This query helps you prioritize your optimization efforts.

The hit_percent column gives you an idea of how effective PostgreSQL's buffer cache is for that query.

SELECT
    query,
    calls,
    total_time,
    mean_time,
    rows,
    100.0 * shared_blks_hit / (shared_blks_hit + shared_blks_read + 1) AS hit_percent
FROM
    pg_stat_statements
ORDER BY
    total_time DESC
LIMIT 5;

Meet pg_buffercache: Memory Inspector

While pg_stat_statements shows you query performance, pg_buffercache gives you insight into PostgreSQL's shared buffer cache. This is the memory area where PostgreSQL stores frequently accessed data blocks.

Understanding what's in the buffer cache helps you determine:

Which tables or indexes are most actively used.
If your shared_buffers setting is adequate.
Whether queries are benefiting from cached data or hitting disk.

Activating pg_buffercache

Enabling pg_buffercache is simpler than pg_stat_statements. It typically does not require modification to shared_preload_libraries or a server restart.

You just need to connect to your database and create the extension:

CREATE EXTENSION pg_buffercache;

Peeking into the Shared Buffer Cache

After creating the extension, you can query the pg_buffercache view to see which relations (tables or indexes) occupy the most buffers. Each buffer typically represents an 8KB data block.

This query shows the top 5 relations by the number of buffers they occupy in the cache:

SELECT
    c.relname AS relation_name,
    count(*) AS buffers_in_cache
FROM
    pg_buffercache b
JOIN
    pg_class c ON b.relfilenode = c.relfilenode
JOIN
    pg_database d ON b.reldatabase = d.oid AND d.datname = current_database()
GROUP BY
    c.relname
ORDER BY
    buffers_in_cache DESC
LIMIT 5;

Interpreting Cache Effectiveness

If a table or index consistently appears at the top of the pg_buffercache output with many buffers, it means that data is frequently accessed and kept in memory.

This is generally a good sign, as memory access is much faster than disk I/O. A high hit_percent in pg_stat_statements often correlates with data being present in the buffer cache.

You can use this information to decide if increasing shared_buffers or optimizing queries to access less data would be beneficial.

Quick Check: Monitoring Tools

Which of the following statements are true regarding pg_stat_statements and pg_buffercache?

Recap: Deep Dives with Extensions

Great job! You've learned how to leverage two powerful PostgreSQL extensions for performance monitoring:

pg_stat_statements: Your essential tool for profiling SQL queries, identifying slow-running or frequently executed statements, and understanding their resource consumption.
pg_buffercache: Gives you visibility into the shared buffer cache, helping you understand what data is actively residing in memory and how effectively your caching is working.

Combined, these extensions provide deep insights into your database's workload and memory utilization, guiding your optimization efforts.

Frequently asked questions

Is the “Using pg_stat_statements and pg_buffercache” lesson free?

Yes — the full text of “Using pg_stat_statements and pg_buffercache” is free to read here on the web, and the PostgreSQL Performance & Query Optimization course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the PostgreSQL Performance & Query Optimization course, upgrade to CoddyKit PRO.

What will I learn in “Using pg_stat_statements and pg_buffercache”?

Leverage powerful extensions like `pg_stat_statements` and `pg_buffercache` for deep performance insights. You practise PostgreSQL Performance & Query Optimization with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start PostgreSQL Performance & Query Optimization?

No prior experience is required. PostgreSQL Performance & Query Optimization on CoddyKit is structured for beginners through advanced learners; this is — lesson 1 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Using pg_stat_statements and pg_buffercache” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this PostgreSQL Performance & Query Optimization lesson?

Yes. Every PostgreSQL Performance & Query Optimization lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

Using pg_stat_statements and pg_buffercache
Logging Configuration for Analysis
External Monitoring Tools Integration
Diagnosing Live Activity with pg_stat_activity

← Back to PostgreSQL Performance & Query Optimization