mirror of
https://github.com/postgres/postgres.git
synced 2025-06-08 22:02:03 +03:00
Add new documentation on page format.
Martijn van Ooster
This commit is contained in:
Bruce Momjian
parent
42ef2c9cb7
commit
d1fcd337e0
@ -22,9 +22,13 @@ refers to data that is stored in <productname>PostgreSQL</productname> tables.
|
|||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
<xref linkend="page-table"> shows how pages in both normal <productname>PostgreSQL</productname> tables
|
|
||||||
and <productname>PostgreSQL</productname> indexes
|
<xref linkend="page-table"> shows how pages in both normal
|
||||||
(e.g., a B-tree index) are structured.
|
<productname>PostgreSQL</productname> tables and
|
||||||
|
<productname>PostgreSQL</productname> indexes (e.g., a B-tree index)
|
||||||
|
are structured. This structure is also used for toast tables and sequences.
|
||||||
|
There are five parts to each page.
|
||||||
|
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<table tocentry="1" id="page-table">
|
<table tocentry="1" id="page-table">
|
||||||
@ -42,114 +46,256 @@ Item
|
|||||||
|
|
||||||
<tbody>
|
<tbody>
|
||||||
|
|
||||||
|
<row>
|
||||||
|
<entry>PageHeaderData</entry>
|
||||||
|
<entry>20 bytes long. Contains general information about the page to allow to access it.</entry>
|
||||||
|
</row>
|
||||||
|
|
||||||
<row>
|
<row>
|
||||||
<entry>itemPointerData</entry>
|
<entry>itemPointerData</entry>
|
||||||
|
<entry>List of (offset,length) pairs pointing to the actual item.</entry>
|
||||||
</row>
|
</row>
|
||||||
|
|
||||||
<row>
|
<row>
|
||||||
<entry>filler</entry>
|
<entry>Free space</entry>
|
||||||
|
<entry>The unallocated space. All new tuples are allocated from here, generally from the end.</entry>
|
||||||
</row>
|
</row>
|
||||||
|
|
||||||
<row>
|
<row>
|
||||||
<entry>itemData...</entry>
|
<entry>items</entry>
|
||||||
</row>
|
<entry>The actual items themselves. Different access method have different data here.</entry>
|
||||||
|
|
||||||
<row>
|
|
||||||
<entry>Unallocated Space</entry>
|
|
||||||
</row>
|
|
||||||
|
|
||||||
<row>
|
|
||||||
<entry>ItemContinuationData</entry>
|
|
||||||
</row>
|
</row>
|
||||||
|
|
||||||
<row>
|
<row>
|
||||||
<entry>Special Space</entry>
|
<entry>Special Space</entry>
|
||||||
</row>
|
<entry>Access method specific data. Different method store different data. Unused by normal tables.</entry>
|
||||||
|
|
||||||
<row>
|
|
||||||
<entry><quote>ItemData 2</quote></entry>
|
|
||||||
</row>
|
|
||||||
|
|
||||||
<row>
|
|
||||||
<entry><quote>ItemData 1</quote></entry>
|
|
||||||
</row>
|
|
||||||
|
|
||||||
<row>
|
|
||||||
<entry>ItemIdData</entry>
|
|
||||||
</row>
|
|
||||||
|
|
||||||
<row>
|
|
||||||
<entry>PageHeaderData</entry>
|
|
||||||
</row>
|
</row>
|
||||||
|
|
||||||
</tbody>
|
</tbody>
|
||||||
</tgroup>
|
</tgroup>
|
||||||
</table>
|
</table>
|
||||||
|
|
||||||
<!--
|
<para>
|
||||||
.\" Running
|
|
||||||
.\" .q .../bin/dumpbpages
|
The first 20 bytes of each page consists of a page header
|
||||||
.\" or
|
(PageHeaderData). It's format is detailed in <xref
|
||||||
.\" .q .../src/support/dumpbpages
|
linkend="pageheaderdata-table">. The first two fields deal with WAL
|
||||||
.\" as the postgres superuser
|
related stuff. This is followed by three 2-byte integer fields
|
||||||
.\" with the file paths associated with
|
(<firstterm>lower</firstterm>, <firstterm>upper</firstterm>, and
|
||||||
.\" (heap or B-tree index) classes,
|
<firstterm>special</firstterm>). These represent byte offsets to the start
|
||||||
.\" .q .../data/base/<database-name>/<class-name>,
|
of unallocated space, to the end of unallocated space, and to the start of
|
||||||
.\" will display the page structure used by the classes.
|
the special space.
|
||||||
.\" Specifying the
|
|
||||||
.\" .q -r
|
</para>
|
||||||
.\" flag will cause the classes to be
|
|
||||||
.\" treated as heap classes and for more information to be displayed.
|
<table tocentry="1" id="pageheaderdata-table">
|
||||||
-->
|
<title>PageHeaderData Layout</title>
|
||||||
|
<titleabbrev>PageHeaderData Layout</titleabbrev>
|
||||||
|
<tgroup cols="4">
|
||||||
|
<thead>
|
||||||
|
<row>
|
||||||
|
<entry>Field</entry>
|
||||||
|
<entry>Type</entry>
|
||||||
|
<entry>Length</entry>
|
||||||
|
<entry>Description</entry>
|
||||||
|
</row>
|
||||||
|
</thead>
|
||||||
|
<tbody>
|
||||||
|
<row>
|
||||||
|
<entry>pd_lsn</entry>
|
||||||
|
<entry>XLogRecPtr</entry>
|
||||||
|
<entry>6 bytes</entry>
|
||||||
|
<entry>LSN: next byte after last byte of xlog</entry>
|
||||||
|
</row>
|
||||||
|
<row>
|
||||||
|
<entry>pd_sui</entry>
|
||||||
|
<entry>StartUpID</entry>
|
||||||
|
<entry>4 bytes</entry>
|
||||||
|
<entry>SUI of last changes (currently it's used by heap AM only)</entry>
|
||||||
|
</row>
|
||||||
|
<row>
|
||||||
|
<entry>pd_lower</entry>
|
||||||
|
<entry>LocationIndex</entry>
|
||||||
|
<entry>2 bytes</entry>
|
||||||
|
<entry>Offset to start of free space.</entry>
|
||||||
|
</row>
|
||||||
|
<row>
|
||||||
|
<entry>pd_upper</entry>
|
||||||
|
<entry>LocationIndex</entry>
|
||||||
|
<entry>2 bytes</entry>
|
||||||
|
<entry>Offset to end of free space.</entry>
|
||||||
|
</row>
|
||||||
|
<row>
|
||||||
|
<entry>pd_special</entry>
|
||||||
|
<entry>LocationIndex</entry>
|
||||||
|
<entry>2 bytes</entry>
|
||||||
|
<entry>Offset to start of special space.</entry>
|
||||||
|
</row>
|
||||||
|
<row>
|
||||||
|
<entry>pd_opaque</entry>
|
||||||
|
<entry>OpaqueData</entry>
|
||||||
|
<entry>2 bytes</entry>
|
||||||
|
<entry>AM-generic information. Currently just stores the page size.</entry>
|
||||||
|
</row>
|
||||||
|
</tbody>
|
||||||
|
</tgroup>
|
||||||
|
</table>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
The first 8 bytes of each page consists of a page header
|
Special space is a region at the end of the page that is allocated at page
|
||||||
(PageHeaderData).
|
initialization time and contains information specific to an access method.
|
||||||
Within the header, the first three 2-byte integer fields
|
The last 2 bytes of the page header, <firstterm>opaque</firstterm>,
|
||||||
(<firstterm>lower</firstterm>,
|
currently only stores the page size. Page size is stored in each page
|
||||||
<firstterm>upper</firstterm>,
|
because frames in the buffer pool may be subdivided into equal sized pages
|
||||||
and
|
on a frame by frame basis within a table (is this true? - mvo).
|
||||||
<firstterm>special</firstterm>)
|
|
||||||
represent byte offsets to the start of unallocated space, to the end
|
|
||||||
of unallocated space, and to the start of <firstterm>special space</firstterm>.
|
|
||||||
Special space is a region at the end of the page that is allocated at
|
|
||||||
page initialization time and contains information specific to an
|
|
||||||
access method. The last 2 bytes of the page header,
|
|
||||||
<firstterm>opaque</firstterm>,
|
|
||||||
encode the page size and information on the internal fragmentation of
|
|
||||||
the page. Page size is stored in each page because frames in the
|
|
||||||
buffer pool may be subdivided into equal sized pages on a frame by
|
|
||||||
frame basis within a table. The internal fragmentation information is
|
|
||||||
used to aid in determining when page reorganization should occur.
|
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
|
|
||||||
Following the page header are item identifiers
|
Following the page header are item identifiers
|
||||||
(<firstterm>ItemIdData</firstterm>).
|
(<firstterm>ItemIdData</firstterm>). New item identifiers are allocated
|
||||||
New item identifiers are allocated from the first four bytes of
|
from the first four bytes of unallocated space. Because an item
|
||||||
unallocated space. Because an item identifier is never moved until it
|
identifier is never moved until it is freed, its index may be used to
|
||||||
is freed, its index may be used to indicate the location of an item on
|
indicate the location of an item on a page. In fact, every pointer to an
|
||||||
a page. In fact, every pointer to an item
|
item (<firstterm>ItemPointer</firstterm>, also know as
|
||||||
(<firstterm>ItemPointer</firstterm>)
|
<firstterm>CTID</firstterm>) created by
|
||||||
created by <productname>PostgreSQL</productname> consists of a frame number and an index of an item
|
<productname>PostgreSQL</productname> consists of a frame number and an
|
||||||
identifier. An item identifier contains a byte-offset to the start of
|
index of an item identifier. An item identifier contains a byte-offset to
|
||||||
an item, its length in bytes, and a set of attribute bits which affect
|
the start of an item, its length in bytes, and a set of attribute bits
|
||||||
its interpretation.
|
which affect its interpretation.
|
||||||
|
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
The items themselves are stored in space allocated backwards from
|
|
||||||
the end of unallocated space. Usually, the items are not interpreted.
|
The items themselves are stored in space allocated backwards from the end
|
||||||
However when the item is too long to be placed on a single page or
|
of unallocated space. The exact structure varies depending on what the
|
||||||
when fragmentation of the item is desired, the item is divided and
|
table is to contain. Sequences and tables both use a structure named
|
||||||
each piece is handled as distinct items in the following manner. The
|
<firstterm>HeapTupleHeaderData</firstterm>, describe below.
|
||||||
first through the next to last piece are placed in an item
|
|
||||||
continuation structure
|
|
||||||
(<firstterm>ItemContinuationData</firstterm>).
|
|
||||||
This structure contains
|
|
||||||
itemPointerData
|
|
||||||
which points to the next piece and the piece itself. The last piece
|
|
||||||
is handled normally.
|
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
|
||||||
|
The final section is the "special section" which may contain anything the
|
||||||
|
access method wishes to store. Ordinary tables do not use this at all
|
||||||
|
(indicated by setting the offset to the pagesize).
|
||||||
|
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
|
||||||
|
All tuples are structured the same way. A header of around 31 bytes
|
||||||
|
followed by an optional null bitmask and the data. The header is detailed
|
||||||
|
below in <xref linkend="heaptupleheaderdata-table">. The null bitmask is
|
||||||
|
only present if the <firstterm>HEAP_HASNULL</firstterm> bit is set in the
|
||||||
|
<firstterm>t_infomask</firstterm>. If it is present it takes up the space
|
||||||
|
between the end of the header and the beginning of the data, as indicated
|
||||||
|
by the <firstterm>t_hoff</firstterm> field. In this list of bits, a 1 bit
|
||||||
|
indicates not-null, a 0 bit is a null.
|
||||||
|
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<table tocentry="1" id="heaptupleheaderdata-table">
|
||||||
|
<title>HeapTupleHeaderData Layout</title>
|
||||||
|
<titleabbrev>HeapTupleHeaderData Layout</titleabbrev>
|
||||||
|
<tgroup cols="4">
|
||||||
|
<thead>
|
||||||
|
<row>
|
||||||
|
<entry>Field</entry>
|
||||||
|
<entry>Type</entry>
|
||||||
|
<entry>Length</entry>
|
||||||
|
<entry>Description</entry>
|
||||||
|
</row>
|
||||||
|
</thead>
|
||||||
|
<tbody>
|
||||||
|
<row>
|
||||||
|
<entry>t_oid</entry>
|
||||||
|
<entry>Oid</entry>
|
||||||
|
<entry>4 bytes</entry>
|
||||||
|
<entry>OID of this tuple</entry>
|
||||||
|
</row>
|
||||||
|
<row>
|
||||||
|
<entry>t_cmin</entry>
|
||||||
|
<entry>CommandId</entry>
|
||||||
|
<entry>4 bytes</entry>
|
||||||
|
<entry>insert CID stamp</entry>
|
||||||
|
</row>
|
||||||
|
<row>
|
||||||
|
<entry>t_cmax</entry>
|
||||||
|
<entry>CommandId</entry>
|
||||||
|
<entry>4 bytes</entry>
|
||||||
|
<entry>delete CID stamp</entry>
|
||||||
|
</row>
|
||||||
|
<row>
|
||||||
|
<entry>t_xmin</entry>
|
||||||
|
<entry>TransactionId</entry>
|
||||||
|
<entry>4 bytes</entry>
|
||||||
|
<entry>insert XID stamp</entry>
|
||||||
|
</row>
|
||||||
|
<row>
|
||||||
|
<entry>t_xmax</entry>
|
||||||
|
<entry>TransactionId</entry>
|
||||||
|
<entry>4 bytes</entry>
|
||||||
|
<entry>delete XID stamp</entry>
|
||||||
|
</row>
|
||||||
|
<row>
|
||||||
|
<entry>t_ctid</entry>
|
||||||
|
<entry>ItemPointerData</entry>
|
||||||
|
<entry>6 bytes</entry>
|
||||||
|
<entry>current TID of this or newer tuple</entry>
|
||||||
|
</row>
|
||||||
|
<row>
|
||||||
|
<entry>t_natts</entry>
|
||||||
|
<entry>int16</entry>
|
||||||
|
<entry>2 bytes</entry>
|
||||||
|
<entry>number of attributes</entry>
|
||||||
|
</row>
|
||||||
|
<row>
|
||||||
|
<entry>t_infomask</entry>
|
||||||
|
<entry>uint16</entry>
|
||||||
|
<entry>2 bytes</entry>
|
||||||
|
<entry>Various flags</entry>
|
||||||
|
</row>
|
||||||
|
<row>
|
||||||
|
<entry>t_hoff</entry>
|
||||||
|
<entry>uint8</entry>
|
||||||
|
<entry>1 byte</entry>
|
||||||
|
<entry>length of tuple header. Also offset of data.</entry>
|
||||||
|
</row>
|
||||||
|
</tbody>
|
||||||
|
</tgroup>
|
||||||
|
</table>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
|
||||||
|
All the details may be found in src/include/storage/bufpage.h.
|
||||||
|
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
|
||||||
|
Interpreting the actual data can only be done with information obtained
|
||||||
|
from other tables, mostly <firstterm>pg_attribute</firstterm>. The
|
||||||
|
particular fields are <firstterm>attlen</firstterm> and
|
||||||
|
<firstterm>attalign</firstterm>. There is no way to directly get a
|
||||||
|
particular attribute, except when there are only fixed width fields and no
|
||||||
|
NULLs. All this trickery is wrapped up in the functions
|
||||||
|
<firstterm>heap_getattr</firstterm>, <firstterm>fastgetattr</firstterm>
|
||||||
|
and <firstterm>heap_getsysattr</firstterm>.
|
||||||
|
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
|
||||||
|
To read the data you need to examine each attribute in turn. First check
|
||||||
|
whether the field is NULL according to the null bitmap. If it is, go to
|
||||||
|
the next. Then make sure you have the right alignment. If the field is a
|
||||||
|
fixed width field, then all the bytes are simply placed. If it's a
|
||||||
|
variable length field (attlen == -1) then it's a bit more complicated,
|
||||||
|
using the variable length structure <firstterm>varattrib</firstterm>.
|
||||||
|
Depending on the flags, the data may be either inline, compressed or in
|
||||||
|
another table (TOAST).
|
||||||
|
|
||||||
|
</para>
|
||||||
</chapter>
|
</chapter>
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user