<para>

The <filename>pg_visibility</> module provides a means for examining the

visibility map (VM) and page-level visibility information. It also

provides functions to check the integrity ofthe visibility map and to

visibility map (VM) and page-level visibility information of a table.

It alsoprovides functions to check the integrity ofa visibility map and to

force it to be rebuilt.

</para>

<para>

Three different bits are used to store information about page-level

visibility. The all-visible bit in the visibility map indicates that every

tuple on a given page of a relation is visible to every current transaction.

The all-frozen bit in the visibility map indicates that every tuple on the

page is frozen; that is, no future vacuum will need to modify the page

until such time as a tuple is inserted, updated, deleted, or locked on

that page. The page-level <literal>PD_ALL_VISIBLE</literal> bit has the

tuple in the corresponding page of the relation is visible to every current

and future transaction. The all-frozen bit in the visibility map indicates

that every tuple in the page is frozen; that is, no future vacuum will need

to modify the page until such time as a tuple is inserted, updated, deleted,

or locked on that page.

The page header's <literal>PD_ALL_VISIBLE</literal> bit has the

same meaning as the all-visible bit in the visibility map, but is stored

within the data page itself rather than a separate data structure. These

will normally agree, but the page-level bit can sometimes be set while the

visibility map bit is clear after a crash recovery; or they can disagree

because of a change which occurs after <literal>pg_visibility</> examines

the visibility map and before it examines the data page. Any event which

causes data corruption can also cause these bits to disagree.

within the data page itself rather than in a separate data structure.

These two bits will normally agree, but the page's all-visible bit can

sometimes be set while the visibility map bit is clear after a crash

recovery. The reported values can also disagree because of a change that

occurs after <literal>pg_visibility</> examines the visibility map and

before it examines the data page. Any event that causes data corruption

can also cause these bits to disagree.

</para>

<para>

Functionswhich display information about <literal>PD_ALL_VISIBLE</>

are much more costly than thosewhich only consult the visibility map,

Functionsthat display information about <literal>PD_ALL_VISIBLE</> bits

are much more costly than thosethat only consult the visibility map,

because they must read the relation's data blocks rather than only the

(much smaller) visibility map. Functions that check the relation's

data blocks are similarly expensive.

<variablelist>

<varlistentry>

<term><function>pg_visibility_map(regclass, blkno bigint, all_visible OUT boolean, all_frozen OUT boolean) returns record</function></term>

<term><function>pg_visibility_map(relationregclass, blkno bigint, all_visible OUT boolean, all_frozen OUT boolean) returns record</function></term>

<listitem>

<para>

Returns the all-visible and all-frozen bits in the visibility map for

</varlistentry>

<varlistentry>

<term><function>pg_visibility(regclass, blkno bigint, all_visible OUT boolean, all_frozen OUT boolean, pd_all_visible OUT boolean) returns record</function></term>

<term><function>pg_visibility(relationregclass, blkno bigint, all_visible OUT boolean, all_frozen OUT boolean, pd_all_visible OUT boolean) returns record</function></term>

<listitem>

<para>

Returns the all-visible and all-frozen bits in the visibility map for

the given block of the given relation, plus the

<literal>PD_ALL_VISIBLE</> bitfor that block.

<literal>PD_ALL_VISIBLE</> bitof that block.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><function>pg_visibility_map(regclass, blkno OUT bigint, all_visible OUT boolean, all_frozen OUT boolean) returns setof record</function></term>

<term><function>pg_visibility_map(relationregclass, blkno OUT bigint, all_visible OUT boolean, all_frozen OUT boolean) returns setof record</function></term>

<listitem>

<para>

Returns the all-visible and all-frozen bits in the visibility map for

each block the given relation.

each blockofthe given relation.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><function>pg_visibility(regclass, blkno OUT bigint, all_visible OUT boolean, all_frozen OUT boolean, pd_all_visible OUT boolean) returns setof record</function></term>

<term><function>pg_visibility(relationregclass, blkno OUT bigint, all_visible OUT boolean, all_frozen OUT boolean, pd_all_visible OUT boolean) returns setof record</function></term>

<listitem>

<para>

Returns the all-visible and all-frozen bits in the visibility map for

each block the given relation, plus the <literal>PD_ALL_VISIBLE</>

bitfor each block.

each blockofthe given relation, plus the <literal>PD_ALL_VISIBLE</>

bitof each block.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><function>pg_visibility_map_summary(regclass, all_visible OUT bigint, all_frozen OUT bigint) returns record</function></term>

<term><function>pg_visibility_map_summary(relationregclass, all_visible OUT bigint, all_frozen OUT bigint) returns record</function></term>

<listitem>

<para>

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><function>pg_check_frozen(regclass, t_ctid OUT tid) returns setof tid</function></term>

<term><function>pg_check_frozen(relationregclass, t_ctid OUT tid) returns setof tid</function></term>

<listitem>

<para>

Returns the TIDs of non-frozen tuplespresent in pages marked all-frozen

Returns the TIDs of non-frozen tuplesstored in pages marked all-frozen

in the visibility map. If this function returns a non-empty set of

TIDs, thedatabase is corrupt.

TIDs, thevisibility map is corrupt.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><function>pg_check_visible(regclass, t_ctid OUT tid) returns setof tid</function></term>

<varlistentry>

<term><function>pg_check_visible(relationregclass, t_ctid OUT tid) returns setof tid</function></term>

<listitem>

<para>

Returns the TIDs of tuples which are not all-visible despite the fact

that the pages which contain them are marked as all-visible in the

visibility map. If this function returns a non-empty set of TIDs, the

database is corrupt.

Returns the TIDs of non-all-visible tuples stored in pages marked

all-visible in the visibility map. If this function returns a non-empty

set of TIDs, the visibility map is corrupt.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><function>pg_truncate_visibility_map(regclass) returns void</function></term>

<term><function>pg_truncate_visibility_map(relationregclass) returns void</function></term>

<listitem>

<para>

Truncates the visibility map for the given relation. This function

is only expected to beuseful if yoususpect that the visibility map

for the indicated relation iscorrupt and wish torebuildit. The first

<command>VACUUM</>executed on the given relation after this function

is executed will scanevery page in the relation and rebuild the

visibility map.

Truncates the visibility map for the given relation. This function is

useful if youbelieve that the visibility map for the relation is

corrupt and wish toforce rebuildingit. The first <command>VACUUM</>

executed on the given relation after this function is executed will scan

every page in the relation and rebuild the visibility map. (Until that

is done, queries will treat thevisibility map as containing all zeroes.)

</para>

</listitem>

</varlistentry>

</variablelist>

<para>

By default, these functions arenot publicly executable.

By default, these functions areexecutable only by superusers.

</para>

</sect2>