begriffs open source - ai-pg/blob - full-docs/src/sgml/html/pgprewarm.html

   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.30. pg_prewarm — preload relation data into buffer caches</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="pgoverexplain.html" title="F.29. pg_overexplain — allow EXPLAIN to dump even more details" /><link rel="next" href="pgrowlocks.html" title="F.31. pgrowlocks — show a table's row locking information" /></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.30. pg_prewarm — preload relation data into buffer caches</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="pgoverexplain.html" title="F.29. pg_overexplain — allow EXPLAIN to dump even more details">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="pgrowlocks.html" title="F.31. pgrowlocks — show a table's row locking information">Next</a></td></tr></table><hr /></div><div class="sect1" id="PGPREWARM"><div class="titlepage"><div><div><h2 class="title" style="clear: both">F.30. pg_prewarm — preload relation data into buffer caches <a href="#PGPREWARM" class="id_link">#</a></h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="pgprewarm.html#PGPREWARM-FUNCS">F.30.1. Functions</a></span></dt><dt><span class="sect2"><a href="pgprewarm.html#PGPREWARM-CONFIG-PARAMS">F.30.2. Configuration Parameters</a></span></dt><dt><span class="sect2"><a href="pgprewarm.html#PGPREWARM-AUTHOR">F.30.3. Author</a></span></dt></dl></div><a id="id-1.11.7.40.2" class="indexterm"></a><p>
   3   The <code class="filename">pg_prewarm</code> module provides a convenient way
   4   to load relation data into either the operating system buffer cache
   5   or the <span class="productname">PostgreSQL</span> buffer cache.  Prewarming
   6   can be performed manually using the <code class="filename">pg_prewarm</code> function,
   7   or can be performed automatically by including <code class="literal">pg_prewarm</code> in
   8   <a class="xref" href="runtime-config-client.html#GUC-SHARED-PRELOAD-LIBRARIES">shared_preload_libraries</a>.  In the latter case, the
   9   system will run a background worker which periodically records the contents
  10   of shared buffers in a file called <code class="filename">autoprewarm.blocks</code> and
  11   will, using 2 background workers, reload those same blocks after a restart.
  12  </p><div class="sect2" id="PGPREWARM-FUNCS"><div class="titlepage"><div><div><h3 class="title">F.30.1. Functions <a href="#PGPREWARM-FUNCS" class="id_link">#</a></h3></div></div></div><pre class="synopsis">
  13 pg_prewarm(regclass, mode text default 'buffer', fork text default 'main',
  14            first_block int8 default null,
  15            last_block int8 default null) RETURNS int8
  16 </pre><p>
  17    The first argument is the relation to be prewarmed.  The second argument
  18    is the prewarming method to be used, as further discussed below; the third
  19    is the relation fork to be prewarmed, usually <code class="literal">main</code>.
  20    The fourth argument is the first block number to prewarm
  21    (<code class="literal">NULL</code> is accepted as a synonym for zero).  The fifth
  22    argument is the last block number to prewarm (<code class="literal">NULL</code>
  23    means prewarm through the last block in the relation).  The return value
  24    is the number of blocks prewarmed.
  25   </p><p>
  26    There are three available prewarming methods.  <code class="literal">prefetch</code>
  27    issues asynchronous prefetch requests to the operating system, if this is
  28    supported, or throws an error otherwise.  <code class="literal">read</code> reads
  29    the requested range of blocks; unlike <code class="literal">prefetch</code>, this is
  30    synchronous and supported on all platforms and builds, but may be slower.
  31    <code class="literal">buffer</code> reads the requested range of blocks into the
  32    database buffer cache.
  33   </p><p>
  34    Note that with any of these methods, attempting to prewarm more blocks than
  35    can be cached — by the OS when using <code class="literal">prefetch</code> or
  36    <code class="literal">read</code>, or by <span class="productname">PostgreSQL</span> when
  37    using <code class="literal">buffer</code> — will likely result in lower-numbered
  38    blocks being evicted as higher numbered blocks are read in.  Prewarmed data
  39    also enjoys no special protection from cache evictions, so it is possible
  40    that other system activity may evict the newly prewarmed blocks shortly
  41    after they are read; conversely, prewarming may also evict other data from
  42    cache. For these reasons, prewarming is typically most useful at startup,
  43    when caches are largely empty.
  44   </p><pre class="synopsis">
  45 autoprewarm_start_worker() RETURNS void
  46 </pre><p>
  47    Launch the main autoprewarm worker.  This will normally happen
  48    automatically, but is useful if automatic prewarm was not configured at
  49    server startup time and you wish to start up the worker at a later time.
  50   </p><pre class="synopsis">
  51 autoprewarm_dump_now() RETURNS int8
  52 </pre><p>
  53    Update <code class="filename">autoprewarm.blocks</code> immediately.  This may be useful
  54    if the autoprewarm worker is not running but you anticipate running it
  55    after the next restart.  The return value is the number of records written
  56    to <code class="filename">autoprewarm.blocks</code>.
  57   </p></div><div class="sect2" id="PGPREWARM-CONFIG-PARAMS"><div class="titlepage"><div><div><h3 class="title">F.30.2. Configuration Parameters <a href="#PGPREWARM-CONFIG-PARAMS" class="id_link">#</a></h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt><span class="term">
  58      <code class="varname">pg_prewarm.autoprewarm</code> (<code class="type">boolean</code>)
  59      <a id="id-1.11.7.40.5.2.1.1.3" class="indexterm"></a>
  60     </span></dt><dd><p>
  61       Controls whether the server should run the autoprewarm worker. This is
  62       on by default. This parameter can only be set at server start.
  63      </p></dd></dl></div><div class="variablelist"><dl class="variablelist"><dt><span class="term">
  64      <code class="varname">pg_prewarm.autoprewarm_interval</code> (<code class="type">integer</code>)
  65      <a id="id-1.11.7.40.5.3.1.1.3" class="indexterm"></a>
  66     </span></dt><dd><p>
  67       This is the interval between updates to <code class="literal">autoprewarm.blocks</code>.
  68       The default is 300 seconds. If set to 0, the file will not be
  69       dumped at regular intervals, but only when the server is shut down.
  70      </p></dd></dl></div><p>
  71    These parameters must be set in <code class="filename">postgresql.conf</code>.
  72    Typical usage might be:
  73   </p><pre class="programlisting">
  74 # postgresql.conf
  75 shared_preload_libraries = 'pg_prewarm'
  76
  77 pg_prewarm.autoprewarm = true
  78 pg_prewarm.autoprewarm_interval = 300s
  79
  80 </pre></div><div class="sect2" id="PGPREWARM-AUTHOR"><div class="titlepage"><div><div><h3 class="title">F.30.3. Author <a href="#PGPREWARM-AUTHOR" class="id_link">#</a></h3></div></div></div><p>
  81    Robert Haas <code class="email">&lt;<a class="email" href="mailto:rhaas@postgresql.org">rhaas@postgresql.org</a>&gt;</code>
  82   </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="pgoverexplain.html" title="F.29. pg_overexplain — allow EXPLAIN to dump even more details">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="pgrowlocks.html" title="F.31. pgrowlocks — show a table's row locking information">Next</a></td></tr><tr><td width="40%" align="left" valign="top">F.29. pg_overexplain — allow EXPLAIN to dump even more details </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.31. pgrowlocks — show a table's row locking information</td></tr></table></div></body></html>