diff options
Diffstat (limited to 'doc/src/sgml/pgvisibility.sgml')
| -rw-r--r-- | doc/src/sgml/pgvisibility.sgml | 158 |
1 files changed, 158 insertions, 0 deletions
diff --git a/doc/src/sgml/pgvisibility.sgml b/doc/src/sgml/pgvisibility.sgml new file mode 100644 index 0000000..8090aa5 --- /dev/null +++ b/doc/src/sgml/pgvisibility.sgml @@ -0,0 +1,158 @@ +<!-- doc/src/sgml/pgvisibility.sgml --> + +<sect1 id="pgvisibility" xreflabel="pg_visibility"> + <title>pg_visibility</title> + + <indexterm zone="pgvisibility"> + <primary>pg_visibility</primary> + </indexterm> + + <para> + The <filename>pg_visibility</filename> module provides a means for examining the + visibility map (VM) and page-level visibility information of a table. + It also provides functions to check the integrity of a 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 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 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</literal> 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> + Functions that display information about <literal>PD_ALL_VISIBLE</literal> bits + are much more costly than those that 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. + </para> + + <sect2> + <title>Functions</title> + + <variablelist> + <varlistentry> + <term><function>pg_visibility_map(relation regclass, 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 + the given block of the given relation. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><function>pg_visibility(relation regclass, 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</literal> bit of that block. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><function>pg_visibility_map(relation regclass, 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 of the given relation. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><function>pg_visibility(relation regclass, 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 of the given relation, plus the <literal>PD_ALL_VISIBLE</literal> + bit of each block. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><function>pg_visibility_map_summary(relation regclass, all_visible OUT bigint, all_frozen OUT bigint) returns record</function></term> + + <listitem> + <para> + Returns the number of all-visible pages and the number of all-frozen + pages in the relation according to the visibility map. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><function>pg_check_frozen(relation regclass, t_ctid OUT tid) returns setof tid</function></term> + + <listitem> + <para> + Returns the TIDs of non-frozen tuples stored in pages marked all-frozen + 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_check_visible(relation regclass, t_ctid OUT tid) returns setof tid</function></term> + + <listitem> + <para> + 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(relation regclass) returns void</function></term> + + <listitem> + <para> + Truncates the visibility map for the given relation. This function is + useful if you believe that the visibility map for the relation is + corrupt and wish to force rebuilding it. The first <command>VACUUM</command> + 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 the visibility map as containing all zeroes.) + </para> + </listitem> + </varlistentry> + </variablelist> + + <para> + By default, these functions are executable only by superusers and roles with privileges + of the <literal>pg_stat_scan_tables</literal> role, with the exception of + <function>pg_truncate_visibility_map(relation regclass)</function> which can only + be executed by superusers. + </para> + </sect2> + + <sect2> + <title>Author</title> + + <para> + Robert Haas <email>rhaas@postgresql.org</email> + </para> + </sect2> + +</sect1> |