Copy-editing for contrib/pg_visibility documentation.
Add omitted names for some function parameters. Fix some minor grammatical issues.
This commit is contained in:
Tom Lane
parent
ea046f08d1
commit
33596edf09
|
|
@ -9,31 +9,33 @@
|
|||
|
||||
<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 of the visibility map and to
|
||||
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 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>
|
||||
Functions which display information about <literal>PD_ALL_VISIBLE</>
|
||||
are much more costly than those which only consult the visibility map,
|
||||
Functions that display information about <literal>PD_ALL_VISIBLE</> 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.
|
||||
|
|
@ -44,7 +46,7 @@
|
|||
|
||||
<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(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
|
||||
|
|
@ -54,40 +56,40 @@
|
|||
</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>
|
||||
<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</> bit for that block.
|
||||
<literal>PD_ALL_VISIBLE</> bit of 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(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 the given relation.
|
||||
each block of the 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(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 the given relation, plus the <literal>PD_ALL_VISIBLE</>
|
||||
bit for each block.
|
||||
each block of the given relation, plus the <literal>PD_ALL_VISIBLE</>
|
||||
bit of 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(relation regclass, all_visible OUT bigint, all_frozen OUT bigint) returns record</function></term>
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
|
|
@ -96,50 +98,49 @@
|
|||
</para>
|
||||
</listitem>
|
||||
</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>
|
||||
<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
|
||||
TIDs, the database 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.
|
||||
TIDs, the visibility map is corrupt.
|
||||
</para>
|
||||
</listitem>
|
||||
</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>
|
||||
<para>
|
||||
Truncates the visibility map for the given relation. This function
|
||||
is only expected to be useful if you suspect that the visibility map
|
||||
for the indicated relation is corrupt and wish to rebuild 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.
|
||||
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</>
|
||||
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 not publicly executable.
|
||||
By default, these functions are executable only by superusers.
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue