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

   1
   2 F.30. pg_prewarm — preload relation data into buffer caches #
   3
   4    F.30.1. Functions
   5    F.30.2. Configuration Parameters
   6    F.30.3. Author
   7
   8    The pg_prewarm module provides a convenient way to load relation data
   9    into either the operating system buffer cache or the PostgreSQL buffer
  10    cache. Prewarming can be performed manually using the pg_prewarm
  11    function, or can be performed automatically by including pg_prewarm in
  12    shared_preload_libraries. In the latter case, the system will run a
  13    background worker which periodically records the contents of shared
  14    buffers in a file called autoprewarm.blocks and will, using 2
  15    background workers, reload those same blocks after a restart.
  16
  17 F.30.1. Functions #
  18
  19 pg_prewarm(regclass, mode text default 'buffer', fork text default 'main',
  20            first_block int8 default null,
  21            last_block int8 default null) RETURNS int8
  22
  23    The first argument is the relation to be prewarmed. The second argument
  24    is the prewarming method to be used, as further discussed below; the
  25    third is the relation fork to be prewarmed, usually main. The fourth
  26    argument is the first block number to prewarm (NULL is accepted as a
  27    synonym for zero). The fifth argument is the last block number to
  28    prewarm (NULL means prewarm through the last block in the relation).
  29    The return value is the number of blocks prewarmed.
  30
  31    There are three available prewarming methods. prefetch issues
  32    asynchronous prefetch requests to the operating system, if this is
  33    supported, or throws an error otherwise. read reads the requested range
  34    of blocks; unlike prefetch, this is synchronous and supported on all
  35    platforms and builds, but may be slower. buffer reads the requested
  36    range of blocks into the database buffer cache.
  37
  38    Note that with any of these methods, attempting to prewarm more blocks
  39    than can be cached — by the OS when using prefetch or read, or by
  40    PostgreSQL when using buffer — will likely result in lower-numbered
  41    blocks being evicted as higher numbered blocks are read in. Prewarmed
  42    data also enjoys no special protection from cache evictions, so it is
  43    possible that other system activity may evict the newly prewarmed
  44    blocks shortly after they are read; conversely, prewarming may also
  45    evict other data from cache. For these reasons, prewarming is typically
  46    most useful at startup, when caches are largely empty.
  47 autoprewarm_start_worker() RETURNS void
  48
  49    Launch the main autoprewarm worker. This will normally happen
  50    automatically, but is useful if automatic prewarm was not configured at
  51    server startup time and you wish to start up the worker at a later
  52    time.
  53 autoprewarm_dump_now() RETURNS int8
  54
  55    Update autoprewarm.blocks immediately. This may be useful if the
  56    autoprewarm worker is not running but you anticipate running it after
  57    the next restart. The return value is the number of records written to
  58    autoprewarm.blocks.
  59
  60 F.30.2. Configuration Parameters #
  61
  62    pg_prewarm.autoprewarm (boolean)
  63           Controls whether the server should run the autoprewarm worker.
  64           This is on by default. This parameter can only be set at server
  65           start.
  66
  67    pg_prewarm.autoprewarm_interval (integer)
  68           This is the interval between updates to autoprewarm.blocks. The
  69           default is 300 seconds. If set to 0, the file will not be dumped
  70           at regular intervals, but only when the server is shut down.
  71
  72    These parameters must be set in postgresql.conf. Typical usage might
  73    be:
  74 # postgresql.conf
  75 shared_preload_libraries = 'pg_prewarm'
  76
  77 pg_prewarm.autoprewarm = true
  78 pg_prewarm.autoprewarm_interval = 300s
  79
  80
  81 F.30.3. Author #
  82
  83    Robert Haas <rhaas@postgresql.org>