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

   1
   2 F.36. pg_visibility — visibility map information and utilities #
   3
   4    F.36.1. Functions
   5    F.36.2. Author
   6
   7    The pg_visibility module provides a means for examining the visibility
   8    map (VM) and page-level visibility information of a table. It also
   9    provides functions to check the integrity of a visibility map and to
  10    force it to be rebuilt.
  11
  12    Three different bits are used to store information about page-level
  13    visibility. The all-visible bit in the visibility map indicates that
  14    every tuple in the corresponding page of the relation is visible to
  15    every current and future transaction. The all-frozen bit in the
  16    visibility map indicates that every tuple in the page is frozen; that
  17    is, no future vacuum will need to modify the page until such time as a
  18    tuple is inserted, updated, deleted, or locked on that page. The page
  19    header's PD_ALL_VISIBLE bit has the same meaning as the all-visible bit
  20    in the visibility map, but is stored within the data page itself rather
  21    than in a separate data structure. These two bits will normally agree,
  22    but the page's all-visible bit can sometimes be set while the
  23    visibility map bit is clear after a crash recovery. The reported values
  24    can also disagree because of a change that occurs after pg_visibility
  25    examines the visibility map and before it examines the data page. Any
  26    event that causes data corruption can also cause these bits to
  27    disagree.
  28
  29    Functions that display information about PD_ALL_VISIBLE bits are much
  30    more costly than those that only consult the visibility map, because
  31    they must read the relation's data blocks rather than only the (much
  32    smaller) visibility map. Functions that check the relation's data
  33    blocks are similarly expensive.
  34
  35 F.36.1. Functions #
  36
  37    pg_visibility_map(relation regclass, blkno bigint, all_visible OUT
  38           boolean, all_frozen OUT boolean) returns record
  39           Returns the all-visible and all-frozen bits in the visibility
  40           map for the given block of the given relation.
  41
  42    pg_visibility(relation regclass, blkno bigint, all_visible OUT boolean,
  43           all_frozen OUT boolean, pd_all_visible OUT boolean) returns
  44           record
  45           Returns the all-visible and all-frozen bits in the visibility
  46           map for the given block of the given relation, plus the
  47           PD_ALL_VISIBLE bit of that block.
  48
  49    pg_visibility_map(relation regclass, blkno OUT bigint, all_visible OUT
  50           boolean, all_frozen OUT boolean) returns setof record
  51           Returns the all-visible and all-frozen bits in the visibility
  52           map for each block of the given relation.
  53
  54    pg_visibility(relation regclass, blkno OUT bigint, all_visible OUT
  55           boolean, all_frozen OUT boolean, pd_all_visible OUT boolean)
  56           returns setof record
  57           Returns the all-visible and all-frozen bits in the visibility
  58           map for each block of the given relation, plus the
  59           PD_ALL_VISIBLE bit of each block.
  60
  61    pg_visibility_map_summary(relation regclass, all_visible OUT bigint,
  62           all_frozen OUT bigint) returns record
  63           Returns the number of all-visible pages and the number of
  64           all-frozen pages in the relation according to the visibility
  65           map.
  66
  67    pg_check_frozen(relation regclass, t_ctid OUT tid) returns setof tid
  68           Returns the TIDs of non-frozen tuples stored in pages marked
  69           all-frozen in the visibility map. If this function returns a
  70           non-empty set of TIDs, the visibility map is corrupt.
  71
  72    pg_check_visible(relation regclass, t_ctid OUT tid) returns setof tid
  73           Returns the TIDs of non-all-visible tuples stored in pages
  74           marked all-visible in the visibility map. If this function
  75           returns a non-empty set of TIDs, the visibility map is corrupt.
  76
  77    pg_truncate_visibility_map(relation regclass) returns void
  78           Truncates the visibility map for the given relation. This
  79           function is useful if you believe that the visibility map for
  80           the relation is corrupt and wish to force rebuilding it. The
  81           first VACUUM executed on the given relation after this function
  82           is executed will scan every page in the relation and rebuild the
  83           visibility map. (Until that is done, queries will treat the
  84           visibility map as containing all zeroes.)
  85
  86    By default, these functions are executable only by superusers and roles
  87    with privileges of the pg_stat_scan_tables role, with the exception of
  88    pg_truncate_visibility_map(relation regclass) which can only be
  89    executed by superusers.
  90
  91 F.36.2. Author #
  92
  93    Robert Haas <rhaas@postgresql.org>