1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>F.25. pg_buffercache — inspect PostgreSQL buffer cache state</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="passwordcheck.html" title="F.24. passwordcheck — verify password strength" /><link rel="next" href="pgcrypto.html" title="F.26. pgcrypto — cryptographic functions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">F.25. pg_buffercache — inspect <span class="productname">PostgreSQL</span>
3 buffer cache state</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="passwordcheck.html" title="F.24. passwordcheck — verify password strength">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules and Extensions">Up</a></td><th width="60%" align="center">Appendix F. Additional Supplied Modules and Extensions</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="pgcrypto.html" title="F.26. pgcrypto — cryptographic functions">Next</a></td></tr></table><hr /></div><div class="sect1" id="PGBUFFERCACHE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">F.25. pg_buffercache — inspect <span class="productname">PostgreSQL</span>
4 buffer cache state <a href="#PGBUFFERCACHE" class="id_link">#</a></h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="pgbuffercache.html#PGBUFFERCACHE-PG-BUFFERCACHE">F.25.1. The <code class="structname">pg_buffercache</code> View</a></span></dt><dt><span class="sect2"><a href="pgbuffercache.html#PGBUFFERCACHE-PG-BUFFERCACHE-NUMA">F.25.2. The <code class="structname">pg_buffercache_numa</code> View</a></span></dt><dt><span class="sect2"><a href="pgbuffercache.html#PGBUFFERCACHE-SUMMARY">F.25.3. The <code class="function">pg_buffercache_summary()</code> Function</a></span></dt><dt><span class="sect2"><a href="pgbuffercache.html#PGBUFFERCACHE-USAGE-COUNTS">F.25.4. The <code class="function">pg_buffercache_usage_counts()</code> Function</a></span></dt><dt><span class="sect2"><a href="pgbuffercache.html#PGBUFFERCACHE-PG-BUFFERCACHE-EVICT">F.25.5. The <code class="function">pg_buffercache_evict()</code> Function</a></span></dt><dt><span class="sect2"><a href="pgbuffercache.html#PGBUFFERCACHE-PG-BUFFERCACHE-EVICT-RELATION">F.25.6. The <code class="structname">pg_buffercache_evict_relation()</code> Function</a></span></dt><dt><span class="sect2"><a href="pgbuffercache.html#PGBUFFERCACHE-PG-BUFFERCACHE-EVICT-ALL">F.25.7. The <code class="structname">pg_buffercache_evict_all()</code> Function</a></span></dt><dt><span class="sect2"><a href="pgbuffercache.html#PGBUFFERCACHE-SAMPLE-OUTPUT">F.25.8. Sample Output</a></span></dt><dt><span class="sect2"><a href="pgbuffercache.html#PGBUFFERCACHE-AUTHORS">F.25.9. Authors</a></span></dt></dl></div><a id="id-1.11.7.35.2" class="indexterm"></a><p>
5 The <code class="filename">pg_buffercache</code> module provides a means for
6 examining what's happening in the shared buffer cache in real time.
7 It also offers a low-level way to evict data from it, for testing
9 </p><a id="id-1.11.7.35.4" class="indexterm"></a><a id="id-1.11.7.35.5" class="indexterm"></a><a id="id-1.11.7.35.6" class="indexterm"></a><a id="id-1.11.7.35.7" class="indexterm"></a><a id="id-1.11.7.35.8" class="indexterm"></a><a id="id-1.11.7.35.9" class="indexterm"></a><a id="id-1.11.7.35.10" class="indexterm"></a><p>
10 This module provides the <code class="function">pg_buffercache_pages()</code>
11 function (wrapped in the <code class="structname">pg_buffercache</code> view), the
12 <code class="function">pg_buffercache_numa_pages()</code> function (wrapped in the
13 <code class="structname">pg_buffercache_numa</code> view), the
14 <code class="function">pg_buffercache_summary()</code> function, the
15 <code class="function">pg_buffercache_usage_counts()</code> function, the
16 <code class="function">pg_buffercache_evict()</code> function, the
17 <code class="function">pg_buffercache_evict_relation()</code> function and the
18 <code class="function">pg_buffercache_evict_all()</code> function.
20 The <code class="function">pg_buffercache_pages()</code> function returns a set of
21 records, each row describing the state of one shared buffer entry. The
22 <code class="structname">pg_buffercache</code> view wraps the function for
25 The <code class="function">pg_buffercache_numa_pages()</code> function provides
26 <acronym class="acronym">NUMA</acronym> node mappings for shared buffer entries. This
27 information is not part of <code class="function">pg_buffercache_pages()</code>
28 itself, as it is much slower to retrieve.
29 The <code class="structname">pg_buffercache_numa</code> view wraps the function for
32 The <code class="function">pg_buffercache_summary()</code> function returns a single
33 row summarizing the state of the shared buffer cache.
35 The <code class="function">pg_buffercache_usage_counts()</code> function returns a set
36 of records, each row describing the number of buffers with a given usage
39 By default, use of the above functions is restricted to superusers and roles
40 with privileges of the <code class="literal">pg_monitor</code> role. Access may be
41 granted to others using <code class="command">GRANT</code>.
43 The <code class="function">pg_buffercache_evict()</code> function allows a block to
44 be evicted from the buffer pool given a buffer identifier. Use of this
45 function is restricted to superusers only.
47 The <code class="function">pg_buffercache_evict_relation()</code> function allows all
48 unpinned shared buffers in the relation to be evicted from the buffer pool
49 given a relation identifier. Use of this function is restricted to
52 The <code class="function">pg_buffercache_evict_all()</code> function allows all
53 unpinned shared buffers to be evicted in the buffer pool. Use of this
54 function is restricted to superusers only.
55 </p><div class="sect2" id="PGBUFFERCACHE-PG-BUFFERCACHE"><div class="titlepage"><div><div><h3 class="title">F.25.1. The <code class="structname">pg_buffercache</code> View <a href="#PGBUFFERCACHE-PG-BUFFERCACHE" class="id_link">#</a></h3></div></div></div><p>
56 The definitions of the columns exposed by the view are shown in <a class="xref" href="pgbuffercache.html#PGBUFFERCACHE-COLUMNS" title="Table F.14. pg_buffercache Columns">Table F.14</a>.
57 </p><div class="table" id="PGBUFFERCACHE-COLUMNS"><p class="title"><strong>Table F.14. <code class="structname">pg_buffercache</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_buffercache Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
62 </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
63 <code class="structfield">bufferid</code> <code class="type">integer</code>
66 ID, in the range 1..<code class="varname">shared_buffers</code>
67 </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
68 <code class="structfield">relfilenode</code> <code class="type">oid</code>
69 (references <a class="link" href="catalog-pg-class.html" title="52.11. pg_class"><code class="structname">pg_class</code></a>.<code class="structfield">relfilenode</code>)
72 Filenode number of the relation
73 </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
74 <code class="structfield">reltablespace</code> <code class="type">oid</code>
75 (references <a class="link" href="catalog-pg-tablespace.html" title="52.56. pg_tablespace"><code class="structname">pg_tablespace</code></a>.<code class="structfield">oid</code>)
78 Tablespace OID of the relation
79 </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
80 <code class="structfield">reldatabase</code> <code class="type">oid</code>
81 (references <a class="link" href="catalog-pg-database.html" title="52.15. pg_database"><code class="structname">pg_database</code></a>.<code class="structfield">oid</code>)
84 Database OID of the relation
85 </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
86 <code class="structfield">relforknumber</code> <code class="type">smallint</code>
89 Fork number within the relation; see
90 <code class="filename">common/relpath.h</code>
91 </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
92 <code class="structfield">relblocknumber</code> <code class="type">bigint</code>
95 Page number within the relation
96 </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
97 <code class="structfield">isdirty</code> <code class="type">boolean</code>
101 </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
102 <code class="structfield">usagecount</code> <code class="type">smallint</code>
105 Clock-sweep access count
106 </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
107 <code class="structfield">pinning_backends</code> <code class="type">integer</code>
110 Number of backends pinning this buffer
111 </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
112 There is one row for each buffer in the shared cache. Unused buffers are
113 shown with all fields null except <code class="structfield">bufferid</code>. Shared system
114 catalogs are shown as belonging to database zero.
116 Because the cache is shared by all the databases, there will normally be
117 pages from relations not belonging to the current database. This means
118 that there may not be matching join rows in <code class="structname">pg_class</code> for
119 some rows, or that there could even be incorrect joins. If you are
120 trying to join against <code class="structname">pg_class</code>, it's a good idea to
121 restrict the join to rows having <code class="structfield">reldatabase</code> equal to
122 the current database's OID or zero.
124 Since buffer manager locks are not taken to copy the buffer state data that
125 the view will display, accessing <code class="structname">pg_buffercache</code> view
126 has less impact on normal buffer activity but it doesn't provide a consistent
127 set of results across all buffers. However, we ensure that the information of
128 each buffer is self-consistent.
129 </p></div><div class="sect2" id="PGBUFFERCACHE-PG-BUFFERCACHE-NUMA"><div class="titlepage"><div><div><h3 class="title">F.25.2. The <code class="structname">pg_buffercache_numa</code> View <a href="#PGBUFFERCACHE-PG-BUFFERCACHE-NUMA" class="id_link">#</a></h3></div></div></div><p>
130 The definitions of the columns exposed by the view are shown in <a class="xref" href="pgbuffercache.html#PGBUFFERCACHE-NUMA-COLUMNS" title="Table F.15. pg_buffercache_numa Columns">Table F.15</a>.
131 </p><div class="table" id="PGBUFFERCACHE-NUMA-COLUMNS"><p class="title"><strong>Table F.15. <code class="structname">pg_buffercache_numa</code> Columns</strong></p><div class="table-contents"><table class="table" summary="pg_buffercache_numa Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
136 </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
137 <code class="structfield">bufferid</code> <code class="type">integer</code>
140 ID, in the range 1..<code class="varname">shared_buffers</code>
141 </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
142 <code class="structfield">os_page_num</code> <code class="type">bigint</code>
145 number of OS memory page for this buffer
146 </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
147 <code class="structfield">numa_node</code> <code class="type">int</code>
150 ID of <acronym class="acronym">NUMA</acronym> node
151 </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
152 As <acronym class="acronym">NUMA</acronym> node ID inquiry for each page requires memory pages
153 to be paged-in, the first execution of this function can take a noticeable
154 amount of time. In all the cases (first execution or not), retrieving this
155 information is costly and querying the view at a high frequency is not recommended.
156 </p><div class="warning"><h3 class="title">Warning</h3><p>
157 When determining the <acronym class="acronym">NUMA</acronym> node, the view touches
158 all memory pages for the shared memory segment. This will force
159 allocation of the shared memory, if it wasn't allocated already,
160 and the memory may get allocated in a single <acronym class="acronym">NUMA</acronym>
161 node (depending on system configuration).
162 </p></div></div><div class="sect2" id="PGBUFFERCACHE-SUMMARY"><div class="titlepage"><div><div><h3 class="title">F.25.3. The <code class="function">pg_buffercache_summary()</code> Function <a href="#PGBUFFERCACHE-SUMMARY" class="id_link">#</a></h3></div></div></div><p>
163 The definitions of the columns exposed by the function are shown in <a class="xref" href="pgbuffercache.html#PGBUFFERCACHE-SUMMARY-COLUMNS" title="Table F.16. pg_buffercache_summary() Output Columns">Table F.16</a>.
164 </p><div class="table" id="PGBUFFERCACHE-SUMMARY-COLUMNS"><p class="title"><strong>Table F.16. <code class="function">pg_buffercache_summary()</code> Output Columns</strong></p><div class="table-contents"><table class="table" summary="pg_buffercache_summary() Output Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
169 </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
170 <code class="structfield">buffers_used</code> <code class="type">int4</code>
173 Number of used shared buffers
174 </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
175 <code class="structfield">buffers_unused</code> <code class="type">int4</code>
178 Number of unused shared buffers
179 </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
180 <code class="structfield">buffers_dirty</code> <code class="type">int4</code>
183 Number of dirty shared buffers
184 </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
185 <code class="structfield">buffers_pinned</code> <code class="type">int4</code>
188 Number of pinned shared buffers
189 </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
190 <code class="structfield">usagecount_avg</code> <code class="type">float8</code>
193 Average usage count of used shared buffers
194 </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
195 The <code class="function">pg_buffercache_summary()</code> function returns a
196 single row summarizing the state of all shared buffers. Similar and more
197 detailed information is provided by the
198 <code class="structname">pg_buffercache</code> view, but
199 <code class="function">pg_buffercache_summary()</code> is significantly cheaper.
201 Like the <code class="structname">pg_buffercache</code> view,
202 <code class="function">pg_buffercache_summary()</code> does not acquire buffer
203 manager locks. Therefore concurrent activity can lead to minor inaccuracies
205 </p></div><div class="sect2" id="PGBUFFERCACHE-USAGE-COUNTS"><div class="titlepage"><div><div><h3 class="title">F.25.4. The <code class="function">pg_buffercache_usage_counts()</code> Function <a href="#PGBUFFERCACHE-USAGE-COUNTS" class="id_link">#</a></h3></div></div></div><p>
206 The definitions of the columns exposed by the function are shown in
207 <a class="xref" href="pgbuffercache.html#PGBUFFERCACHE_USAGE_COUNTS-COLUMNS" title="Table F.17. pg_buffercache_usage_counts() Output Columns">Table F.17</a>.
208 </p><div class="table" id="PGBUFFERCACHE_USAGE_COUNTS-COLUMNS"><p class="title"><strong>Table F.17. <code class="function">pg_buffercache_usage_counts()</code> Output Columns</strong></p><div class="table-contents"><table class="table" summary="pg_buffercache_usage_counts() Output Columns" border="1"><colgroup><col /></colgroup><thead><tr><th class="catalog_table_entry"><p class="column_definition">
213 </p></th></tr></thead><tbody><tr><td class="catalog_table_entry"><p class="column_definition">
214 <code class="structfield">usage_count</code> <code class="type">int4</code>
217 A possible buffer usage count
218 </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
219 <code class="structfield">buffers</code> <code class="type">int4</code>
222 Number of buffers with the usage count
223 </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
224 <code class="structfield">dirty</code> <code class="type">int4</code>
227 Number of dirty buffers with the usage count
228 </p></td></tr><tr><td class="catalog_table_entry"><p class="column_definition">
229 <code class="structfield">pinned</code> <code class="type">int4</code>
232 Number of pinned buffers with the usage count
233 </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
234 The <code class="function">pg_buffercache_usage_counts()</code> function returns a
235 set of rows summarizing the states of all shared buffers, aggregated over
236 the possible usage count values. Similar and more detailed information is
237 provided by the <code class="structname">pg_buffercache</code> view, but
238 <code class="function">pg_buffercache_usage_counts()</code> is significantly cheaper.
240 Like the <code class="structname">pg_buffercache</code> view,
241 <code class="function">pg_buffercache_usage_counts()</code> does not acquire buffer
242 manager locks. Therefore concurrent activity can lead to minor inaccuracies
244 </p></div><div class="sect2" id="PGBUFFERCACHE-PG-BUFFERCACHE-EVICT"><div class="titlepage"><div><div><h3 class="title">F.25.5. The <code class="function">pg_buffercache_evict()</code> Function <a href="#PGBUFFERCACHE-PG-BUFFERCACHE-EVICT" class="id_link">#</a></h3></div></div></div><p>
245 The <code class="function">pg_buffercache_evict()</code> function takes a buffer
246 identifier, as shown in the <code class="structfield">bufferid</code> column of
247 the <code class="structname">pg_buffercache</code> view. It returns information
248 about whether the buffer was evicted and flushed. The buffer_evicted
249 column is true on success, and false if the buffer wasn't valid, if it
250 couldn't be evicted because it was pinned, or if it became dirty again
251 after an attempt to write it out. The buffer_flushed column is true if the
252 buffer was flushed. This does not necessarily mean that buffer was flushed
253 by us, it might be flushed by someone else. The result is immediately out
254 of date upon return, as the buffer might become valid again at any time due
255 to concurrent activity. The function is intended for developer testing
257 </p></div><div class="sect2" id="PGBUFFERCACHE-PG-BUFFERCACHE-EVICT-RELATION"><div class="titlepage"><div><div><h3 class="title">F.25.6. The <code class="structname">pg_buffercache_evict_relation()</code> Function <a href="#PGBUFFERCACHE-PG-BUFFERCACHE-EVICT-RELATION" class="id_link">#</a></h3></div></div></div><p>
258 The <code class="function">pg_buffercache_evict_relation()</code> function is very
259 similar to the <code class="function">pg_buffercache_evict()</code> function. The
260 difference is that the <code class="function">pg_buffercache_evict_relation()</code>
261 takes a relation identifier instead of buffer identifier. It tries to
262 evict all buffers for all forks in that relation.
264 It returns the number of evicted buffers, flushed buffers and the number of
265 buffers that could not be evicted. Flushed buffers haven't necessarily
266 been flushed by us, they might have been flushed by someone else. The
267 result is immediately out of date upon return, as buffers might immediately
268 be read back in due to concurrent activity. The function is intended for
269 developer testing only.
270 </p></div><div class="sect2" id="PGBUFFERCACHE-PG-BUFFERCACHE-EVICT-ALL"><div class="titlepage"><div><div><h3 class="title">F.25.7. The <code class="structname">pg_buffercache_evict_all()</code> Function <a href="#PGBUFFERCACHE-PG-BUFFERCACHE-EVICT-ALL" class="id_link">#</a></h3></div></div></div><p>
271 The <code class="function">pg_buffercache_evict_all()</code> function is very
272 similar to the <code class="function">pg_buffercache_evict()</code> function. The
273 difference is, the <code class="function">pg_buffercache_evict_all()</code> function
274 does not take an argument; instead it tries to evict all buffers in the
275 buffer pool. It returns the number of evicted buffers, flushed buffers and
276 the number of buffers that could not be evicted. Flushed buffers haven't
277 necessarily been flushed by us, they might have been flushed by someone
278 else. The result is immediately out of date upon return, as buffers might
279 immediately be read back in due to concurrent activity. The function is
280 intended for developer testing only.
281 </p></div><div class="sect2" id="PGBUFFERCACHE-SAMPLE-OUTPUT"><div class="titlepage"><div><div><h3 class="title">F.25.8. Sample Output <a href="#PGBUFFERCACHE-SAMPLE-OUTPUT" class="id_link">#</a></h3></div></div></div><pre class="screen">
282 regression=# SELECT n.nspname, c.relname, count(*) AS buffers
283 FROM pg_buffercache b JOIN pg_class c
284 ON b.relfilenode = pg_relation_filenode(c.oid) AND
285 b.reldatabase IN (0, (SELECT oid FROM pg_database
286 WHERE datname = current_database()))
287 JOIN pg_namespace n ON n.oid = c.relnamespace
288 GROUP BY n.nspname, c.relname
292 nspname | relname | buffers
293 ------------+------------------------+---------
294 public | delete_test_table | 593
295 public | delete_test_table_pkey | 494
296 pg_catalog | pg_attribute | 472
297 public | quad_poly_tbl | 353
300 public | gin_test_idx | 306
301 pg_catalog | pg_largeobject | 206
302 public | gin_test_tbl | 188
303 public | spgist_text_tbl | 182
307 regression=# SELECT * FROM pg_buffercache_summary();
308 buffers_used | buffers_unused | buffers_dirty | buffers_pinned | usagecount_avg
309 --------------+----------------+---------------+----------------+----------------
310 248 | 2096904 | 39 | 0 | 3.141129
314 regression=# SELECT * FROM pg_buffercache_usage_counts();
315 usage_count | buffers | dirty | pinned
316 -------------+---------+-------+--------
324 </pre></div><div class="sect2" id="PGBUFFERCACHE-AUTHORS"><div class="titlepage"><div><div><h3 class="title">F.25.9. Authors <a href="#PGBUFFERCACHE-AUTHORS" class="id_link">#</a></h3></div></div></div><p>
325 Mark Kirkwood <code class="email"><<a class="email" href="mailto:markir@paradise.net.nz">markir@paradise.net.nz</a>></code>
327 Design suggestions: Neil Conway <code class="email"><<a class="email" href="mailto:neilc@samurai.com">neilc@samurai.com</a>></code>
329 Debugging advice: Tom Lane <code class="email"><<a class="email" href="mailto:tgl@sss.pgh.pa.us">tgl@sss.pgh.pa.us</a>></code>
330 </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="passwordcheck.html" title="F.24. passwordcheck — verify password strength">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules and Extensions">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="pgcrypto.html" title="F.26. pgcrypto — cryptographic functions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">F.24. passwordcheck — verify password strength </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> F.26. pgcrypto — cryptographic functions</td></tr></table></div></body></html>