Date: Fri, 29 Sep 2023 18:19:58 -0400
From: Bruce Momjian <bruce@momjian.us>
To: Laurenz Albe <laurenz.albe@cybertec.at>
Cc: suchithjn22@gmail.com, pgsql-docs@lists.postgresql.org
Subject: Re: The documentation for storage type 'plain' actually allows
 single byte header
Message-ID: <ZRdNjrI6lUQbD90Y@momjian.us>
References: 
 <167336599095.2667301.15497893107226841625@wrigleys.postgresql.org>
 <d99b3e0beebdde0741d28035aaea7f4af56fa050.camel@cybertec.at>
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Disposition: inline
Content-Transfer-Encoding: 8bit
In-Reply-To: <d99b3e0beebdde0741d28035aaea7f4af56fa050.camel@cybertec.at>
Archived-At: 
 <https://www.postgresql.org/message-id/ZRdNjrI6lUQbD90Y%40momjian.us>
Precedence: bulk

On Thu, Jan 12, 2023 at 03:43:57PM +0100, Laurenz Albe wrote:
> On Tue, 2023-01-10 at 15:53 +0000, PG Doc comments form wrote:
> > https://www.postgresql.org/docs/devel/storage-toast.html - This is the
> > development version.
> > 
> > > PLAIN prevents either compression or out-of-line storage; furthermore it
> > > disables use of single-byte headers for varlena types. This is the only
> > > possible strategy for columns of non-TOAST-able data types.
> > 
> > However, it does allow "single byte" headers. How to verify this?
> > 
> > CREATE EXTENSION pageinspect;
> > CREATE TABLE test(a VARCHAR(10000) STORAGE PLAIN);
> > INSERT INTO test VALUES (repeat('A',10));
> > 
> > Now peek into the page with pageinspect functions
> > 
> > SELECT left(encode(t_data, 'hex'), 40) FROM
> > heap_page_items(get_raw_page('test', 0));
> > 
> > This returned value of "1741414141414141414141".
> > Here the first byte 0x17 = 0001 0111 in binary.
> > Length + 1 is stored in the length bits (1-7). So Len = 0001011-1 = (11-1)
> > [base-10] = 10 [base-10]
> > which exactly matches the expected length. Further the data "41" repeated 10
> > times also indicates character A (65 or 0x41 in ASCII) repeated 10 times.
> > 
> > So....This does **not** disable 1-B header. That sentence should be removed
> > from the documentation unless this is a bug.
> 
> I think that the documentation is wrong.  The attached patch removes the
> offending half-sentence.
> 
> Yours,
> Laurenz Albe

> From 5bf0b43fe73384a21f59d9ad1f7a8d7cbc81f8c4 Mon Sep 17 00:00:00 2001
> From: Laurenz Albe <laurenz.albe@cybertec.at>
> Date: Thu, 12 Jan 2023 15:41:56 +0100
> Subject: [PATCH] Fix documentation for STORAGE PLAIN
> 
> Commit 3e23b68dac0, which introduced single-byte varlena headers,
> added documentation that STORAGE PLAIN would prevent such single-byte
> headers.  This has never been true.
> ---
>  doc/src/sgml/storage.sgml | 4 +---
>  1 file changed, 1 insertion(+), 3 deletions(-)
> 
> diff --git a/doc/src/sgml/storage.sgml b/doc/src/sgml/storage.sgml
> index e5b9f3f1ff..4795a485d0 100644
> --- a/doc/src/sgml/storage.sgml
> +++ b/doc/src/sgml/storage.sgml
> @@ -456,9 +456,7 @@ for storing <acronym>TOAST</acronym>-able columns on disk:
>      <listitem>
>       <para>
>        <literal>PLAIN</literal> prevents either compression or
> -      out-of-line storage; furthermore it disables use of single-byte headers
> -      for varlena types.
> -      This is the only possible strategy for
> +      out-of-line storage.  This is the only possible strategy for
>        columns of non-<acronym>TOAST</acronym>-able data types.
>       </para>
>      </listitem>
> -- 
> 2.39.0
> 

Where did we end with this?  Is a doc patch the solution?

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EDB                                      https://enterprisedb.com

  Only you can decide what is important to you.