<!-- doc/src/sgml/pgbuffercache.sgml -->

<sect1 id="pgbuffercache" xreflabel="pg_buffercache">
 <title>pg_buffercache &mdash; inspect <productname>PostgreSQL</productname>
    buffer cache state</title>

 <indexterm zone="pgbuffercache">
  <primary>pg_buffercache</primary>
 </indexterm>

 <para>
  The <filename>pg_buffercache</filename> module provides a means for
  examining what's happening in the shared buffer cache in real time.
  It also offers a low-level way to evict data from it, for testing
  purposes.
 </para>

 <indexterm>
  <primary>pg_buffercache_pages</primary>
 </indexterm>

 <indexterm>
  <primary>pg_buffercache_summary</primary>
 </indexterm>

 <indexterm>
  <primary>pg_buffercache_evict</primary>
 </indexterm>

 <indexterm>
  <primary>pg_buffercache_evict_relation</primary>
 </indexterm>

 <indexterm>
  <primary>pg_buffercache_evict_all</primary>
 </indexterm>

 <para>
  This module provides the <function>pg_buffercache_pages()</function>
  function (wrapped in the <structname>pg_buffercache</structname> view),
  <function>pg_buffercache_numa_pages()</function> function (wrapped in the
  <structname>pg_buffercache_numa</structname> view), the
  <function>pg_buffercache_summary()</function> function, the
  <function>pg_buffercache_usage_counts()</function> function, the
  <function>pg_buffercache_evict()</function>, the
  <function>pg_buffercache_evict_relation()</function> function and the
  <function>pg_buffercache_evict_all()</function> function.
 </para>

 <para>
  The <function>pg_buffercache_pages()</function> function returns a set of
  records, each row describing the state of one shared buffer entry. The
  <structname>pg_buffercache</structname> view wraps the function for
  convenient use.
 </para>

 <para>
  The <function>pg_buffercache_numa_pages()</function> provides
  <acronym>NUMA</acronym> node mappings for shared buffer entries. This
  information is not part of <function>pg_buffercache_pages()</function>
  itself, as it is much slower to retrieve.
  The <structname>pg_buffercache_numa</structname> view wraps the function for
  convenient use.
 </para>

 <para>
  The <function>pg_buffercache_summary()</function> function returns a single
  row summarizing the state of the shared buffer cache.
 </para>

 <para>
  The <function>pg_buffercache_usage_counts()</function> function returns a set
  of records, each row describing the number of buffers with a given usage
  count.
 </para>

 <para>
  By default, use of the above functions is restricted to superusers and roles
  with privileges of the <literal>pg_monitor</literal> role. Access may be
  granted to others using <command>GRANT</command>.
 </para>

 <para>
  The <function>pg_buffercache_evict()</function> function allows a block to
  be evicted from the buffer pool given a buffer identifier.  Use of this
  function is restricted to superusers only.
 </para>

 <para>
  The <function>pg_buffercache_evict_relation()</function> function allows all
  unpinned shared buffers in the relation to be evicted from the buffer pool
  given a relation identifier.  Use of this function is restricted to
  superusers only.
 </para>

 <para>
  The <function>pg_buffercache_evict_all()</function> function allows all
  unpinned shared buffers to be evicted in the buffer pool.  Use of this
  function is restricted to superusers only.
 </para>

 <sect2 id="pgbuffercache-pg-buffercache">
  <title>The <structname>pg_buffercache</structname> View</title>

  <para>
   The definitions of the columns exposed by the view are shown in <xref linkend="pgbuffercache-columns"/>.
  </para>

  <table id="pgbuffercache-columns">
   <title><structname>pg_buffercache</structname> Columns</title>
   <tgroup cols="1">
    <thead>
     <row>
      <entry role="catalog_table_entry"><para role="column_definition">
       Column Type
      </para>
      <para>
       Description
      </para></entry>
     </row>
    </thead>

    <tbody>
     <row>
      <entry role="catalog_table_entry"><para