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