doc/src/sgml/pageinspect.sgml

   1 <!-- $PostgreSQL$ -->
   2
   3 <sect1 id="pageinspect">
   4  <title>pageinspect</title>
   5
   6  <indexterm zone="pageinspect">
   7   <primary>pageinspect</primary>
   8  </indexterm>
   9
  10  <para>
  11   The <filename>pageinspect</> module provides functions that allow you to
  12   inspect the contents of database pages at a low level, which is useful for
  13   debugging purposes.  All of these functions may be used only by superusers.
  14  </para>
  15
  16  <sect2>
  17   <title>Functions</title>
  18
  19   <variablelist>
  20    <varlistentry>
  21     <term>
  22      <function>get_raw_page(relname text, fork text, blkno int) returns bytea</function>
  23     </term>
  24
  25     <listitem>
  26      <para>
  27       <function>get_raw_page</function> reads the specified block of the named
  28       table and returns a copy as a <type>bytea</> value.  This allows a
  29       single time-consistent copy of the block to be obtained.
  30       <replaceable>fork</replaceable> should be <literal>'main'</literal> for
  31       the main data fork, or <literal>'fsm'</literal> for the free space map,
  32       or <literal>'vm'</literal> for the visibility map.
  33      </para>
  34     </listitem>
  35    </varlistentry>
  36
  37    <varlistentry>
  38     <term>
  39      <function>get_raw_page(relname text, blkno int) returns bytea</function>
  40     </term>
  41
  42     <listitem>
  43      <para>
  44       A shorthand version of <function>get_raw_page</function>, for reading
  45       from the main fork.  Equivalent to
  46       <literal>get_raw_page(relname, 'main', blkno)</literal>
  47      </para>
  48     </listitem>
  49    </varlistentry>
  50
  51    <varlistentry>
  52     <term>
  53      <function>page_header(page bytea) returns record</function>
  54     </term>
  55
  56     <listitem>
  57      <para>
  58       <function>page_header</function> shows fields that are common to all
  59       <productname>PostgreSQL</> heap and index pages.
  60      </para>
  61
  62      <para>
  63       A page image obtained with <function>get_raw_page</function> should be
  64       passed as argument.  For example:
  65      </para>
  66      <programlisting>
  67 test=# SELECT * FROM page_header(get_raw_page('pg_class', 0));
  68     lsn    | tli | flags | lower | upper | special | pagesize | version | prune_xid
  69 -----------+-----+-------+-------+-------+---------+----------+---------+-----------
  70  0/24A1B50 |   1 |     1 |   232 |   368 |    8192 |     8192 |       4 |         0
  71      </programlisting>
  72
  73      <para>
  74       The returned columns correspond to the fields in the
  75       <structname>PageHeaderData</> struct.
  76       See <filename>src/include/storage/bufpage.h</> for details.
  77     </para>
  78     </listitem>
  79    </varlistentry>
  80
  81    <varlistentry>
  82     <term>
  83      <function>heap_page_items(page bytea) returns setof record</function>
  84     </term>
  85
  86     <listitem>
  87      <para>
  88       <function>heap_page_items</function> shows all line pointers on a heap
  89       page.  For those line pointers that are in use, tuple headers are also
  90       shown. All tuples are shown, whether or not the tuples were visible to
  91       an MVCC snapshot at the time the raw page was copied.
  92      </para>
  93      <para>
  94       A heap page image obtained with <function>get_raw_page</function> should
  95       be passed as argument.  For example:
  96      </para>
  97      <programlisting>
  98 test=# SELECT * FROM heap_page_items(get_raw_page('pg_class', 0));
  99      </programlisting>
 100      <para>
 101       See <filename>src/include/storage/itemid.h</> and
 102       <filename>src/include/access/htup.h</> for explanations of the fields
 103       returned.
 104      </para>
 105     </listitem>
 106    </varlistentry>
 107
 108    <varlistentry>
 109     <term>
 110      <function>bt_metap(relname text) returns record</function>
 111     </term>
 112
 113     <listitem>
 114      <para>
 115       <function>bt_metap</function> returns information about a btree
 116       index's metapage.  For example:
 117      </para>
 118      <programlisting>
 119 test=# SELECT * FROM bt_metap('pg_cast_oid_index');
 120 -[ RECORD 1 ]-----
 121 magic     | 340322
 122 version   | 2
 123 root      | 1
 124 level     | 0
 125 fastroot  | 1
 126 fastlevel | 0
 127      </programlisting>
 128     </listitem>
 129    </varlistentry>
 130
 131    <varlistentry>
 132     <term>
 133      <function>bt_page_stats(relname text, blkno int) returns record</function>
 134     </term>
 135
 136     <listitem>
 137      <para>
 138       <function>bt_page_stats</function> returns summary information about
 139       single pages of btree indexes.  For example:
 140      </para>
 141      <programlisting>
 142 test=# SELECT * FROM bt_page_stats('pg_cast_oid_index', 1);
 143 -[ RECORD 1 ]-+-----
 144 blkno         | 1
 145 type          | l
 146 live_items    | 256
 147 dead_items    | 0
 148 avg_item_size | 12
 149 page_size     | 8192
 150 free_size     | 4056
 151 btpo_prev     | 0
 152 btpo_next     | 0
 153 btpo          | 0
 154 btpo_flags    | 3
 155      </programlisting>
 156     </listitem>
 157    </varlistentry>
 158
 159    <varlistentry>
 160     <term>
 161      <function>bt_page_items(relname text, blkno int) returns setof record</function>
 162     </term>
 163
 164     <listitem>
 165      <para>
 166       <function>bt_page_items</function> returns detailed information about
 167       all of the items on a btree index page.  For example:
 168      </para>
 169      <programlisting>
 170 test=# SELECT * FROM bt_page_items('pg_cast_oid_index', 1);
 171  itemoffset |  ctid   | itemlen | nulls | vars |    data
 172 ------------+---------+---------+-------+------+-------------
 173           1 | (0,1)   |      12 | f     | f    | 23 27 00 00
 174           2 | (0,2)   |      12 | f     | f    | 24 27 00 00
 175           3 | (0,3)   |      12 | f     | f    | 25 27 00 00
 176           4 | (0,4)   |      12 | f     | f    | 26 27 00 00
 177           5 | (0,5)   |      12 | f     | f    | 27 27 00 00
 178           6 | (0,6)   |      12 | f     | f    | 28 27 00 00
 179           7 | (0,7)   |      12 | f     | f    | 29 27 00 00
 180           8 | (0,8)   |      12 | f     | f    | 2a 27 00 00
 181      </programlisting>
 182     </listitem>
 183    </varlistentry>
 184
 185    <varlistentry>
 186     <term>
 187      <function>fsm_page_contents(page bytea) returns text</function>
 188     </term>
 189
 190     <listitem>
 191      <para>
 192       <function>fsm_page_contents</function> shows the internal node structure
 193       of a FSM page. The output is a multi-line string, with one line per
 194       node in the binary tree within the page. Only those nodes that are not
 195       zero are printed. The so-called "next" pointer, which points to the
 196       next slot to be returned from the page, is also printed.
 197      </para>
 198      <para>
 199       See <filename>src/backend/storage/freespace/README</> for more
 200       information on the structure of an FSM page.
 201      </para>
 202     </listitem>
 203    </varlistentry>
 204   </variablelist>
 205  </sect2>
 206
 207 </sect1>