begriffs open source - ai-pg/blob - full-docs/src/sgml/html/pgvisibility.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.36. pg_visibility — visibility map information and utilities</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="pgtrgm.html" title="F.35. pg_trgm — support for similarity of text using trigram matching" /><link rel="next" href="pgwalinspect.html" title="F.37. pg_walinspect — low-level WAL inspection" /></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.36. pg_visibility — visibility map information and utilities</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="pgtrgm.html" title="F.35. pg_trgm —&#10;   support for similarity of text using trigram matching">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="pgwalinspect.html" title="F.37. pg_walinspect — low-level WAL inspection">Next</a></td></tr></table><hr /></div><div class="sect1" id="PGVISIBILITY"><div class="titlepage"><div><div><h2 class="title" style="clear: both">F.36. pg_visibility — visibility map information and utilities <a href="#PGVISIBILITY" class="id_link">#</a></h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="pgvisibility.html#PGVISIBILITY-FUNCS">F.36.1. Functions</a></span></dt><dt><span class="sect2"><a href="pgvisibility.html#PGVISIBILITY-AUTHOR">F.36.2. Author</a></span></dt></dl></div><a id="id-1.11.7.46.2" class="indexterm"></a><p>
   3   The <code class="filename">pg_visibility</code> module provides a means for examining the
   4   visibility map (VM) and page-level visibility information of a table.
   5   It also provides functions to check the integrity of a visibility map and to
   6   force it to be rebuilt.
   7  </p><p>
   8   Three different bits are used to store information about page-level
   9   visibility.  The all-visible bit in the visibility map indicates that every
  10   tuple in the corresponding page of the relation is visible to every current
  11   and future transaction.  The all-frozen bit in the visibility map indicates
  12   that every tuple in the page is frozen; that is, no future vacuum will need
  13   to modify the page until such time as a tuple is inserted, updated, deleted,
  14   or locked on that page.
  15   The page header's <code class="literal">PD_ALL_VISIBLE</code> bit has the
  16   same meaning as the all-visible bit in the visibility map, but is stored
  17   within the data page itself rather than in a separate data structure.
  18   These two bits will normally agree, but the page's all-visible bit can
  19   sometimes be set while the visibility map bit is clear after a crash
  20   recovery.  The reported values can also disagree because of a change that
  21   occurs after <code class="literal">pg_visibility</code> examines the visibility map and
  22   before it examines the data page.  Any event that causes data corruption
  23   can also cause these bits to disagree.
  24  </p><p>
  25   Functions that display information about <code class="literal">PD_ALL_VISIBLE</code> bits
  26   are much more costly than those that only consult the visibility map,
  27   because they must read the relation's data blocks rather than only the
  28   (much smaller) visibility map.  Functions that check the relation's
  29   data blocks are similarly expensive.
  30  </p><div class="sect2" id="PGVISIBILITY-FUNCS"><div class="titlepage"><div><div><h3 class="title">F.36.1. Functions <a href="#PGVISIBILITY-FUNCS" class="id_link">#</a></h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="function">pg_visibility_map(relation regclass, blkno bigint, all_visible OUT boolean, all_frozen OUT boolean) returns record</code></span></dt><dd><p>
  31       Returns the all-visible and all-frozen bits in the visibility map for
  32       the given block of the given relation.
  33      </p></dd><dt><span class="term"><code class="function">pg_visibility(relation regclass, blkno bigint, all_visible OUT boolean, all_frozen OUT boolean, pd_all_visible OUT boolean) returns record</code></span></dt><dd><p>
  34       Returns the all-visible and all-frozen bits in the visibility map for
  35       the given block of the given relation, plus the
  36       <code class="literal">PD_ALL_VISIBLE</code> bit of that block.
  37      </p></dd><dt><span class="term"><code class="function">pg_visibility_map(relation regclass, blkno OUT bigint, all_visible OUT boolean, all_frozen OUT boolean) returns setof record</code></span></dt><dd><p>
  38       Returns the all-visible and all-frozen bits in the visibility map for
  39       each block of the given relation.
  40      </p></dd><dt><span class="term"><code class="function">pg_visibility(relation regclass, blkno OUT bigint, all_visible OUT boolean, all_frozen OUT boolean, pd_all_visible OUT boolean) returns setof record</code></span></dt><dd><p>
  41       Returns the all-visible and all-frozen bits in the visibility map for
  42       each block of the given relation, plus the <code class="literal">PD_ALL_VISIBLE</code>
  43       bit of each block.
  44      </p></dd><dt><span class="term"><code class="function">pg_visibility_map_summary(relation regclass, all_visible OUT bigint, all_frozen OUT bigint) returns record</code></span></dt><dd><p>
  45       Returns the number of all-visible pages and the number of all-frozen
  46       pages in the relation according to the visibility map.
  47      </p></dd><dt><span class="term"><code class="function">pg_check_frozen(relation regclass, t_ctid OUT tid) returns setof tid</code></span></dt><dd><p>
  48       Returns the TIDs of non-frozen tuples stored in pages marked all-frozen
  49       in the visibility map.  If this function returns a non-empty set of
  50       TIDs, the visibility map is corrupt.
  51      </p></dd><dt><span class="term"><code class="function">pg_check_visible(relation regclass, t_ctid OUT tid) returns setof tid</code></span></dt><dd><p>
  52       Returns the TIDs of non-all-visible tuples stored in pages marked
  53       all-visible in the visibility map.  If this function returns a non-empty
  54       set of TIDs, the visibility map is corrupt.
  55      </p></dd><dt><span class="term"><code class="function">pg_truncate_visibility_map(relation regclass) returns void</code></span></dt><dd><p>
  56       Truncates the visibility map for the given relation.  This function is
  57       useful if you believe that the visibility map for the relation is
  58       corrupt and wish to force rebuilding it.  The first <code class="command">VACUUM</code>
  59       executed on the given relation after this function is executed will scan
  60       every page in the relation and rebuild the visibility map.  (Until that
  61       is done, queries will treat the visibility map as containing all zeroes.)
  62      </p></dd></dl></div><p>
  63    By default, these functions are executable only by superusers and roles with privileges
  64    of the <code class="literal">pg_stat_scan_tables</code> role, with the exception of
  65    <code class="function">pg_truncate_visibility_map(relation regclass)</code> which can only
  66    be executed by superusers.
  67   </p></div><div class="sect2" id="PGVISIBILITY-AUTHOR"><div class="titlepage"><div><div><h3 class="title">F.36.2. Author <a href="#PGVISIBILITY-AUTHOR" class="id_link">#</a></h3></div></div></div><p>
  68    Robert Haas <code class="email">&lt;<a class="email" href="mailto:rhaas@postgresql.org">rhaas@postgresql.org</a>&gt;</code>
  69   </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="pgtrgm.html" title="F.35. pg_trgm —&#10;   support for similarity of text using trigram matching">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="pgwalinspect.html" title="F.37. pg_walinspect — low-level WAL inspection">Next</a></td></tr><tr><td width="40%" align="left" valign="top">F.35. pg_trgm —
  70    support for similarity of text using trigram matching </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.37. pg_walinspect — low-level WAL inspection</td></tr></table></div></body></html>