doc/src/sgml/pgprewarm.sgml

   1 <!-- doc/src/sgml/pgprewarm.sgml -->
   2
   3 <sect1 id="pgprewarm" xreflabel="pg_prewarm">
   4  <title>pg_prewarm &mdash; preload relation data into buffer caches</title>
   5
   6  <indexterm zone="pgprewarm">
   7   <primary>pg_prewarm</primary>
   8  </indexterm>
   9
  10  <para>
  11   The <filename>pg_prewarm</filename> module provides a convenient way
  12   to load relation data into either the operating system buffer cache
  13   or the <productname>PostgreSQL</productname> buffer cache.  Prewarming
  14   can be performed manually using the <filename>pg_prewarm</filename> function,
  15   or can be performed automatically by including <literal>pg_prewarm</literal> in
  16   <xref linkend="guc-shared-preload-libraries"/>.  In the latter case, the
  17   system will run a background worker which periodically records the contents
  18   of shared buffers in a file called <filename>autoprewarm.blocks</filename> and
  19   will, using 2 background workers, reload those same blocks after a restart.
  20  </para>
  21
  22  <sect2 id="pgprewarm-funcs">
  23   <title>Functions</title>
  24
  25 <synopsis>
  26 pg_prewarm(regclass, mode text default 'buffer', fork text default 'main',
  27            first_block int8 default null,
  28            last_block int8 default null) RETURNS int8
  29 </synopsis>
  30
  31   <para>
  32    The first argument is the relation to be prewarmed.  The second argument
  33    is the prewarming method to be used, as further discussed below; the third
  34    is the relation fork to be prewarmed, usually <literal>main</literal>.
  35    The fourth argument is the first block number to prewarm
  36    (<literal>NULL</literal> is accepted as a synonym for zero).  The fifth
  37    argument is the last block number to prewarm (<literal>NULL</literal>
  38    means prewarm through the last block in the relation).  The return value
  39    is the number of blocks prewarmed.
  40   </para>
  41
  42   <para>
  43    There are three available prewarming methods.  <literal>prefetch</literal>
  44    issues asynchronous prefetch requests to the operating system, if this is
  45    supported, or throws an error otherwise.  <literal>read</literal> reads
  46    the requested range of blocks; unlike <literal>prefetch</literal>, this is
  47    synchronous and supported on all platforms and builds, but may be slower.
  48    <literal>buffer</literal> reads the requested range of blocks into the
  49    database buffer cache.
  50   </para>
  51
  52   <para>
  53    Note that with any of these methods, attempting to prewarm more blocks than
  54    can be cached &mdash; by the OS when using <literal>prefetch</literal> or
  55    <literal>read</literal>, or by <productname>PostgreSQL</productname> when
  56    using <literal>buffer</literal> &mdash; will likely result in lower-numbered
  57    blocks being evicted as higher numbered blocks are read in.  Prewarmed data
  58    also enjoys no special protection from cache evictions, so it is possible
  59    that other system activity may evict the newly prewarmed blocks shortly
  60    after they are read; conversely, prewarming may also evict other data from
  61    cache. For these reasons, prewarming is typically most useful at startup,
  62    when caches are largely empty.
  63   </para>
  64
  65 <synopsis>
  66 autoprewarm_start_worker() RETURNS void
  67 </synopsis>
  68
  69   <para>
  70    Launch the main autoprewarm worker.  This will normally happen
  71    automatically, but is useful if automatic prewarm was not configured at
  72    server startup time and you wish to start up the worker at a later time.
  73   </para>
  74
  75 <synopsis>
  76 autoprewarm_dump_now() RETURNS int8
  77 </synopsis>
  78
  79   <para>
  80    Update <filename>autoprewarm.blocks</filename> immediately.  This may be useful
  81    if the autoprewarm worker is not running but you anticipate running it
  82    after the next restart.  The return value is the number of records written
  83    to <filename>autoprewarm.blocks</filename>.
  84   </para>
  85  </sect2>
  86
  87  <sect2 id="pgprewarm-config-params">
  88   <title>Configuration Parameters</title>
  89
  90  <variablelist>
  91    <varlistentry>
  92     <term>
  93      <varname>pg_prewarm.autoprewarm</varname> (<type>boolean</type>)
  94      <indexterm>
  95       <primary><varname>pg_prewarm.autoprewarm</varname> configuration parameter</primary>
  96      </indexterm>
  97     </term>
  98     <listitem>
  99      <para>
 100       Controls whether the server should run the autoprewarm worker. This is
 101       on by default. This parameter can only be set at server start.
 102      </para>
 103     </listitem>
 104    </varlistentry>
 105   </variablelist>
 106
 107   <variablelist>
 108    <varlistentry>
 109    <term>
 110      <varname>pg_prewarm.autoprewarm_interval</varname> (<type>integer</type>)
 111      <indexterm>
 112       <primary><varname>pg_prewarm.autoprewarm_interval</varname> configuration parameter</primary>
 113      </indexterm>
 114     </term>
 115     <listitem>
 116      <para>
 117       This is the interval between updates to <literal>autoprewarm.blocks</literal>.
 118       The default is 300 seconds. If set to 0, the file will not be
 119       dumped at regular intervals, but only when the server is shut down.
 120      </para>
 121     </listitem>
 122    </varlistentry>
 123   </variablelist>
 124   <para>
 125    These parameters must be set in <filename>postgresql.conf</filename>.
 126    Typical usage might be:
 127   </para>
 128
 129 <programlisting>
 130 # postgresql.conf
 131 shared_preload_libraries = 'pg_prewarm'
 132
 133 pg_prewarm.autoprewarm = true
 134 pg_prewarm.autoprewarm_interval = 300s
 135
 136 </programlisting>
 137
 138  </sect2>
 139
 140  <sect2 id="pgprewarm-author">
 141   <title>Author</title>
 142
 143   <para>
 144    Robert Haas <email>rhaas@postgresql.org</email>
 145   </para>
 146  </sect2>
 147
 148 </sect1>