Subject: Possible mistake in Section 63.6 - 9.6devel Documentation

From: Vignesh Raghunathan <[email-masked]>
Date: Mon, 20 Jul 2015 14:54:08 -0700

Hello,

It has been mentioned in Section 63.6 that the first two fields in
PageHeaderData track the most recent WAL entry related to the page.
However, I am not sure how pd_checksum is related to WAL. Could it be
possible that the sentence has been carried over from previous versions of
the documentations without considering the change to the second field in
PageHeaderData?

Thanks,
Vignesh.

---

From: Michael Paquier <[email-masked]>
Date: Tue, 21 Jul 2015 09:59:30 +0900

On Tue, Jul 21, 2015 at 6:54 AM, Vignesh Raghunathan
<[email-masked]> wrote:
> PageHeaderData track the most recent WAL entry related to the page. However,
> I am not sure how pd_checksum is related to WAL. Could it be possible that
> the sentence has been carried over from previous versions of the
> documentations without considering the change to the second field in
> PageHeaderData?

Yes, the documentation is mistaken. The two bytes of pd_tli have been
switched to pd_checksum in 9.3, hence only the first field is relevant
for WAL, aka pd_lsn. Looking at this portion of the docs I think that
it should be updated as attached, mentioning pd_checksum as well.
-- 
Michael
diff --git a/doc/src/sgml/storage.sgml b/doc/src/sgml/storage.sgml
index e5b7b4b..073fe2b 100644
--- a/doc/src/sgml/storage.sgml
+++ b/doc/src/sgml/storage.sgml
@@ -758,18 +758,18 @@ data. Empty in ordinary tables.</entry>
  <para>
 
   The first 24 bytes of each page consists of a page header
-  (PageHeaderData). Its format is detailed in <xref
-  linkend="pageheaderdata-table">. The first two fields track the most
-  recent WAL entry related to this page. Next is a 2-byte field
-  containing flag bits. This is followed by three 2-byte integer fields
-  (<structfield>pd_lower</structfield>, <structfield>pd_upper</structfield>,
-  and <structfield>pd_special</structfield>). These contain byte offsets
-  from the page start to the start
-  of unallocated space, to the end of unallocated space, and to the start of
-  the special space.
-  The next 2 bytes of the page header,
-  <structfield>pd_pagesize_version</structfield>, store both the page size
-  and a version indicator.  Beginning with
+  (<structname>PageHeaderData</>). Its format is detailed in <xref
+  linkend="pageheaderdata-table">. The first field tracks the most
+  recent WAL entry related to this page. The second field contains
+  the page checksum if <xref linkend="app-initdb-data-checksums"> are
+  enabled.  Next is a 2-byte field containing flag bits. This is followed
+  by three 2-byte integer fields (<structfield>pd_lower</structfield>,
+  <structfield>pd_upper</structfield>, and
+  <structfield>pd_special</structfield>).  These contain byte offsets
+  from the page start to the start of unallocated space, to the end of
+  unallocated space, and to the start of the special space.  The next 2
+  bytes of the page header, <structfield>pd_pagesize_version</structfield>,
+  store both the page size and a version indicator.  Beginning with
   <productname>PostgreSQL</productname> 8.3 the version number is 4;
   <productname>PostgreSQL</productname> 8.1 and 8.2 used version number 3;
   <productname>PostgreSQL</productname> 8.0 used version number 2;

-- 
Sent via pgsql-docs mailing list ([email-masked])
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs

---

From: Fujii Masao <[email-masked]>
Date: Thu, 10 Sep 2015 00:42:27 +0900

> it should be updated as attached, mentioning pd_checksum as well.

Also the type of pd_lsn in the Table 63-3 should be PageXLogRecPtr.

Regards,

-- 
Fujii Masao

---

From: Michael Paquier <[email-masked]>
Date: Thu, 10 Sep 2015 15:05:55 +0900

> Also the type of pd_lsn in the Table 63-3 should be PageXLogRecPtr.

Yep. See attached FWIW.
index e5b7b4b..0153b08 100644
 
@@ -799,7 +799,7 @@ data. Empty in ordinary tables.</entry>
  <tbody>
   <row>
    <entry>pd_lsn</entry>
-   <entry>XLogRecPtr</entry>
+   <entry>PageXLogRecPtr</entry>
    <entry>8 bytes</entry>
    <entry>LSN: next byte after last byte of xlog record for last change
    to this page</entry>

---

From: Fujii Masao <[email-masked]>
Date: Fri, 11 Sep 2015 13:04:03 +0900

>> Also the type of pd_lsn in the Table 63-3 should be PageXLogRecPtr.

Thanks! Applied.

Regards,

-- 
Fujii Masao