begriffs open source - ai-pg/blob - full-docs/txt/pgbuffercache.txt

   1
   2 F.25. pg_buffercache — inspect PostgreSQL buffer cache state #
   3
   4    F.25.1. The pg_buffercache View
   5    F.25.2. The pg_buffercache_numa View
   6    F.25.3. The pg_buffercache_summary() Function
   7    F.25.4. The pg_buffercache_usage_counts() Function
   8    F.25.5. The pg_buffercache_evict() Function
   9    F.25.6. The pg_buffercache_evict_relation() Function
  10    F.25.7. The pg_buffercache_evict_all() Function
  11    F.25.8. Sample Output
  12    F.25.9. Authors
  13
  14    The pg_buffercache module provides a means for examining what's
  15    happening in the shared buffer cache in real time. It also offers a
  16    low-level way to evict data from it, for testing purposes.
  17
  18    This module provides the pg_buffercache_pages() function (wrapped in
  19    the pg_buffercache view), the pg_buffercache_numa_pages() function
  20    (wrapped in the pg_buffercache_numa view), the pg_buffercache_summary()
  21    function, the pg_buffercache_usage_counts() function, the
  22    pg_buffercache_evict() function, the pg_buffercache_evict_relation()
  23    function and the pg_buffercache_evict_all() function.
  24
  25    The pg_buffercache_pages() function returns a set of records, each row
  26    describing the state of one shared buffer entry. The pg_buffercache
  27    view wraps the function for convenient use.
  28
  29    The pg_buffercache_numa_pages() function provides NUMA node mappings
  30    for shared buffer entries. This information is not part of
  31    pg_buffercache_pages() itself, as it is much slower to retrieve. The
  32    pg_buffercache_numa view wraps the function for convenient use.
  33
  34    The pg_buffercache_summary() function returns a single row summarizing
  35    the state of the shared buffer cache.
  36
  37    The pg_buffercache_usage_counts() function returns a set of records,
  38    each row describing the number of buffers with a given usage count.
  39
  40    By default, use of the above functions is restricted to superusers and
  41    roles with privileges of the pg_monitor role. Access may be granted to
  42    others using GRANT.
  43
  44    The pg_buffercache_evict() function allows a block to be evicted from
  45    the buffer pool given a buffer identifier. Use of this function is
  46    restricted to superusers only.
  47
  48    The pg_buffercache_evict_relation() function allows all unpinned shared
  49    buffers in the relation to be evicted from the buffer pool given a
  50    relation identifier. Use of this function is restricted to superusers
  51    only.
  52
  53    The pg_buffercache_evict_all() function allows all unpinned shared
  54    buffers to be evicted in the buffer pool. Use of this function is
  55    restricted to superusers only.
  56
  57 F.25.1. The pg_buffercache View #
  58
  59    The definitions of the columns exposed by the view are shown in
  60    Table F.14.
  61
  62    Table F.14. pg_buffercache Columns
  63
  64    Column Type
  65
  66    Description
  67
  68    bufferid integer
  69
  70    ID, in the range 1..shared_buffers
  71
  72    relfilenode oid (references pg_class.relfilenode)
  73
  74    Filenode number of the relation
  75
  76    reltablespace oid (references pg_tablespace.oid)
  77
  78    Tablespace OID of the relation
  79
  80    reldatabase oid (references pg_database.oid)
  81
  82    Database OID of the relation
  83
  84    relforknumber smallint
  85
  86    Fork number within the relation; see common/relpath.h
  87
  88    relblocknumber bigint
  89
  90    Page number within the relation
  91
  92    isdirty boolean
  93
  94    Is the page dirty?
  95
  96    usagecount smallint
  97
  98    Clock-sweep access count
  99
 100    pinning_backends integer
 101
 102    Number of backends pinning this buffer
 103
 104    There is one row for each buffer in the shared cache. Unused buffers
 105    are shown with all fields null except bufferid. Shared system catalogs
 106    are shown as belonging to database zero.
 107
 108    Because the cache is shared by all the databases, there will normally
 109    be pages from relations not belonging to the current database. This
 110    means that there may not be matching join rows in pg_class for some
 111    rows, or that there could even be incorrect joins. If you are trying to
 112    join against pg_class, it's a good idea to restrict the join to rows
 113    having reldatabase equal to the current database's OID or zero.
 114
 115    Since buffer manager locks are not taken to copy the buffer state data
 116    that the view will display, accessing pg_buffercache view has less
 117    impact on normal buffer activity but it doesn't provide a consistent
 118    set of results across all buffers. However, we ensure that the
 119    information of each buffer is self-consistent.
 120
 121 F.25.2. The pg_buffercache_numa View #
 122
 123    The definitions of the columns exposed by the view are shown in
 124    Table F.15.
 125
 126    Table F.15. pg_buffercache_numa Columns
 127
 128    Column Type
 129
 130    Description
 131
 132    bufferid integer
 133
 134    ID, in the range 1..shared_buffers
 135
 136    os_page_num bigint
 137
 138    number of OS memory page for this buffer
 139
 140    numa_node int
 141
 142    ID of NUMA node
 143
 144    As NUMA node ID inquiry for each page requires memory pages to be
 145    paged-in, the first execution of this function can take a noticeable
 146    amount of time. In all the cases (first execution or not), retrieving
 147    this information is costly and querying the view at a high frequency is
 148    not recommended.
 149
 150 Warning
 151
 152    When determining the NUMA node, the view touches all memory pages for
 153    the shared memory segment. This will force allocation of the shared
 154    memory, if it wasn't allocated already, and the memory may get
 155    allocated in a single NUMA node (depending on system configuration).
 156
 157 F.25.3. The pg_buffercache_summary() Function #
 158
 159    The definitions of the columns exposed by the function are shown in
 160    Table F.16.
 161
 162    Table F.16. pg_buffercache_summary() Output Columns
 163
 164    Column Type
 165
 166    Description
 167
 168    buffers_used int4
 169
 170    Number of used shared buffers
 171
 172    buffers_unused int4
 173
 174    Number of unused shared buffers
 175
 176    buffers_dirty int4
 177
 178    Number of dirty shared buffers
 179
 180    buffers_pinned int4
 181
 182    Number of pinned shared buffers
 183
 184    usagecount_avg float8
 185
 186    Average usage count of used shared buffers
 187
 188    The pg_buffercache_summary() function returns a single row summarizing
 189    the state of all shared buffers. Similar and more detailed information
 190    is provided by the pg_buffercache view, but pg_buffercache_summary() is
 191    significantly cheaper.
 192
 193    Like the pg_buffercache view, pg_buffercache_summary() does not acquire
 194    buffer manager locks. Therefore concurrent activity can lead to minor
 195    inaccuracies in the result.
 196
 197 F.25.4. The pg_buffercache_usage_counts() Function #
 198
 199    The definitions of the columns exposed by the function are shown in
 200    Table F.17.
 201
 202    Table F.17. pg_buffercache_usage_counts() Output Columns
 203
 204    Column Type
 205
 206    Description
 207
 208    usage_count int4
 209
 210    A possible buffer usage count
 211
 212    buffers int4
 213
 214    Number of buffers with the usage count
 215
 216    dirty int4
 217
 218    Number of dirty buffers with the usage count
 219
 220    pinned int4
 221
 222    Number of pinned buffers with the usage count
 223
 224    The pg_buffercache_usage_counts() function returns a set of rows
 225    summarizing the states of all shared buffers, aggregated over the
 226    possible usage count values. Similar and more detailed information is
 227    provided by the pg_buffercache view, but pg_buffercache_usage_counts()
 228    is significantly cheaper.
 229
 230    Like the pg_buffercache view, pg_buffercache_usage_counts() does not
 231    acquire buffer manager locks. Therefore concurrent activity can lead to
 232    minor inaccuracies in the result.
 233
 234 F.25.5. The pg_buffercache_evict() Function #
 235
 236    The pg_buffercache_evict() function takes a buffer identifier, as shown
 237    in the bufferid column of the pg_buffercache view. It returns
 238    information about whether the buffer was evicted and flushed. The
 239    buffer_evicted column is true on success, and false if the buffer
 240    wasn't valid, if it couldn't be evicted because it was pinned, or if it
 241    became dirty again after an attempt to write it out. The buffer_flushed
 242    column is true if the buffer was flushed. This does not necessarily
 243    mean that buffer was flushed by us, it might be flushed by someone
 244    else. The result is immediately out of date upon return, as the buffer
 245    might become valid again at any time due to concurrent activity. The
 246    function is intended for developer testing only.
 247
 248 F.25.6. The pg_buffercache_evict_relation() Function #
 249
 250    The pg_buffercache_evict_relation() function is very similar to the
 251    pg_buffercache_evict() function. The difference is that the
 252    pg_buffercache_evict_relation() takes a relation identifier instead of
 253    buffer identifier. It tries to evict all buffers for all forks in that
 254    relation. It returns the number of evicted buffers, flushed buffers and
 255    the number of buffers that could not be evicted. Flushed buffers
 256    haven't necessarily been flushed by us, they might have been flushed by
 257    someone else. The result is immediately out of date upon return, as
 258    buffers might immediately be read back in due to concurrent activity.
 259    The function is intended for developer testing only.
 260
 261 F.25.7. The pg_buffercache_evict_all() Function #
 262
 263    The pg_buffercache_evict_all() function is very similar to the
 264    pg_buffercache_evict() function. The difference is, the
 265    pg_buffercache_evict_all() function does not take an argument; instead
 266    it tries to evict all buffers in the buffer pool. It returns the number
 267    of evicted buffers, flushed buffers and the number of buffers that
 268    could not be evicted. Flushed buffers haven't necessarily been flushed
 269    by us, they might have been flushed by someone else. The result is
 270    immediately out of date upon return, as buffers might immediately be
 271    read back in due to concurrent activity. The function is intended for
 272    developer testing only.
 273
 274 F.25.8. Sample Output #
 275
 276 regression=# SELECT n.nspname, c.relname, count(*) AS buffers
 277              FROM pg_buffercache b JOIN pg_class c
 278              ON b.relfilenode = pg_relation_filenode(c.oid) AND
 279                 b.reldatabase IN (0, (SELECT oid FROM pg_database
 280                                       WHERE datname = current_database()))
 281              JOIN pg_namespace n ON n.oid = c.relnamespace
 282              GROUP BY n.nspname, c.relname
 283              ORDER BY 3 DESC
 284              LIMIT 10;
 285
 286   nspname   |        relname         | buffers
 287 ------------+------------------------+---------
 288  public     | delete_test_table      |     593
 289  public     | delete_test_table_pkey |     494
 290  pg_catalog | pg_attribute           |     472
 291  public     | quad_poly_tbl          |     353
 292  public     | tenk2                  |     349
 293  public     | tenk1                  |     349
 294  public     | gin_test_idx           |     306
 295  pg_catalog | pg_largeobject         |     206
 296  public     | gin_test_tbl           |     188
 297  public     | spgist_text_tbl        |     182
 298 (10 rows)
 299
 300
 301 regression=# SELECT * FROM pg_buffercache_summary();
 302  buffers_used | buffers_unused | buffers_dirty | buffers_pinned | usagecount_avg
 303 --------------+----------------+---------------+----------------+---------------
 304 -
 305           248 |        2096904 |            39 |              0 |       3.141129
 306 (1 row)
 307
 308
 309 regression=# SELECT * FROM pg_buffercache_usage_counts();
 310  usage_count | buffers | dirty | pinned
 311 -------------+---------+-------+--------
 312            0 |   14650 |     0 |      0
 313            1 |    1436 |   671 |      0
 314            2 |     102 |    88 |      0
 315            3 |      23 |    21 |      0
 316            4 |       9 |     7 |      0
 317            5 |     164 |   106 |      0
 318 (6 rows)
 319
 320 F.25.9. Authors #
 321
 322    Mark Kirkwood <markir@paradise.net.nz>
 323
 324    Design suggestions: Neil Conway <neilc@samurai.com>
 325
 326    Debugging advice: Tom Lane <tgl@sss.pgh.pa.us>