mirrors/postgres
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Copy-editing for contrib/pg_visibility documentation.

Browse Source 
Add omitted names for some function parameters.
Fix some minor grammatical issues.
This commit is contained in:
Tom Lane 2016-10-01 15:32:53 -04:00
parent ea046f08d1
commit 33596edf09
1 changed files with 50 additions and 49 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

97
doc/src/sgml/pgvisibility.sgml
View File

@ -9,31 +9,33 @@
<para> <para>
The <filename>pg_visibility</> module provides a means for examining the The <filename>pg_visibility</> module provides a means for examining the
visibility map (VM) and page-level visibility information. It also visibility map (VM) and page-level visibility information of a table.
provides functions to check the integrity of the visibility map and to It also provides functions to check the integrity of a visibility map and to
force it to be rebuilt. force it to be rebuilt.
</para> </para>
<para> <para>
Three different bits are used to store information about page-level Three different bits are used to store information about page-level
visibility. The all-visible bit in the visibility map indicates that every 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. tuple in the corresponding page of the relation is visible to every current
The all-frozen bit in the visibility map indicates that every tuple on the and future transaction. The all-frozen bit in the visibility map indicates
page is frozen; that is, no future vacuum will need to modify the page that every tuple in the page is frozen; that is, no future vacuum will need
until such time as a tuple is inserted, updated, deleted, or locked on to modify the page until such time as a tuple is inserted, updated, deleted,
that page. The page-level <literal>PD_ALL_VISIBLE</literal> bit has the 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 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 within the data page itself rather than in a separate data structure.
will normally agree, but the page-level bit can sometimes be set while the These two bits will normally agree, but the page's all-visible bit can
visibility map bit is clear after a crash recovery; or they can disagree sometimes be set while the visibility map bit is clear after a crash
because of a change which occurs after <literal>pg_visibility</> examines recovery. The reported values can also disagree because of a change that
the visibility map and before it examines the data page. Any event which occurs after <literal>pg_visibility</> examines the visibility map and
causes data corruption can also cause these bits to disagree. before it examines the data page. Any event that causes data corruption
can also cause these bits to disagree.
</para> </para>
<para> <para>
Functions which display information about <literal>PD_ALL_VISIBLE</> Functions that display information about <literal>PD_ALL_VISIBLE</> bits
are much more costly than those which only consult the visibility map, 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 because they must read the relation's data blocks rather than only the
(much smaller) visibility map. Functions that check the relation's (much smaller) visibility map. Functions that check the relation's
data blocks are similarly expensive. data blocks are similarly expensive.
@ -44,7 +46,7 @@
<variablelist> <variablelist>
<varlistentry> <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(relation regclass, blkno bigint, all_visible OUT boolean, all_frozen OUT boolean) returns record</function></term>
<listitem> <listitem>
<para> <para>
Returns the all-visible and all-frozen bits in the visibility map for Returns the all-visible and all-frozen bits in the visibility map for
@ -54,40 +56,40 @@
</varlistentry> </varlistentry>
<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(relation regclass, blkno bigint, all_visible OUT boolean, all_frozen OUT boolean, pd_all_visible OUT boolean) returns record</function></term>
<listitem> <listitem>
<para> <para>
Returns the all-visible and all-frozen bits in the visibility map for Returns the all-visible and all-frozen bits in the visibility map for
the given block of the given relation, plus the the given block of the given relation, plus the
<literal>PD_ALL_VISIBLE</> bit for that block. <literal>PD_ALL_VISIBLE</> bit of that block.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<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(relation regclass, blkno OUT bigint, all_visible OUT boolean, all_frozen OUT boolean) returns setof record</function></term>
<listitem> <listitem>
<para> <para>
Returns the all-visible and all-frozen bits in the visibility map for Returns the all-visible and all-frozen bits in the visibility map for
each block the given relation. each block of the given relation.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<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(relation regclass, blkno OUT bigint, all_visible OUT boolean, all_frozen OUT boolean, pd_all_visible OUT boolean) returns setof record</function></term>
<listitem> <listitem>
<para> <para>
Returns the all-visible and all-frozen bits in the visibility map for Returns the all-visible and all-frozen bits in the visibility map for
each block the given relation, plus the <literal>PD_ALL_VISIBLE</> each block of the given relation, plus the <literal>PD_ALL_VISIBLE</>
bit for each block. bit of each block.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<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(relation regclass, all_visible OUT bigint, all_frozen OUT bigint) returns record</function></term>
<listitem> <listitem>
<para> <para>
@ -98,48 +100,47 @@
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><function>pg_check_frozen(regclass, t_ctid OUT tid) returns setof tid</function></term> <term><function>pg_check_frozen(relation regclass, t_ctid OUT tid) returns setof tid</function></term>
<listitem> <listitem>
<para> <para>
Returns the TIDs of non-frozen tuples present in pages marked all-frozen 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 in the visibility map. If this function returns a non-empty set of
TIDs, the database is corrupt. TIDs, the visibility map is corrupt.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><function>pg_check_visible(regclass, 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.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><function>pg_truncate_visibility_map(regclass) returns void</function></term> <term><function>pg_check_visible(relation regclass, t_ctid OUT tid) returns setof tid</function></term>
<listitem> <listitem>
<para> <para>
Truncates the visibility map for the given relation. This function Returns the TIDs of non-all-visible tuples stored in pages marked
is only expected to be useful if you suspect that the visibility map all-visible in the visibility map. If this function returns a non-empty
for the indicated relation is corrupt and wish to rebuild it. The first set of TIDs, the visibility map is corrupt.
<command>VACUUM</> executed on the given relation after this function </para>
is executed will scan every page in the relation and rebuild the </listitem>
visibility map. </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</>
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> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
</variablelist> </variablelist>
<para> <para>
By default, these functions are not publicly executable. By default, these functions are executable only by superusers.
</para> </para>
</sect2> </sect2>