From e8c435a824e123f43067ce6f69d66f14cfb8815e Mon Sep 17 00:00:00 2001
From: Robert Haas <rhaas@postgresql.org>
Date: Tue, 13 Apr 2021 14:56:12 -0400
Subject: [PATCH] docs: Update TOAST storage docs for configurable compression.

Mention that there are multiple TOAST compression methods and that the
compression method used is stored in a TOAST pointer along with the
other information that was stored there previously. Add a reference to
the documentation for default_toast_compression, where the supported
methods are listed, instead of duplicating that here.

I haven't tried to preserve the text claiming that pglz is "fairly
simple and very fast." I have no view on the veracity of the former
claim, but LZ4 seems to be faster (and to compress better) so it
seems better not to muddy the waters by talking about compression
speed as a strong point of PGLZ.

Patch by me, reviewed by Justin Pryzby.

Discussion: http://postgr.es/m/CA+Tgmoaw_YBwQhOS_hhEPPwFhfAnu+VCLs18EfGr9gQw1z4H-w@mail.gmail.com
---
 doc/src/sgml/storage.sgml | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/doc/src/sgml/storage.sgml b/doc/src/sgml/storage.sgml
index 3234adb639f..bfccda77afd 100644
--- a/doc/src/sgml/storage.sgml
+++ b/doc/src/sgml/storage.sgml
@@ -394,9 +394,9 @@ Further details appear in <xref linkend="storage-toast-inmemory"/>.
 
 <para>
 The compression technique used for either in-line or out-of-line compressed
-data is a fairly simple and very fast member
-of the LZ family of compression techniques.  See
-<filename>src/common/pg_lzcompress.c</filename> for the details.
+data can be selected using the <literal>COMPRESSION</literal> option on a per-column
+basis when creating a table. The default for columns with no explicit setting
+is taken from the value of <xref linkend="guc-default-toast-compression" />.
 </para>
 
 <sect2 id="storage-toast-ondisk">
@@ -425,8 +425,9 @@ retrieval of the values.  A pointer datum representing an out-of-line on-disk
 <acronym>TOAST</acronym>ed value therefore needs to store the OID of the
 <acronym>TOAST</acronym> table in which to look and the OID of the specific value
 (its <structfield>chunk_id</structfield>).  For convenience, pointer datums also store the
-logical datum size (original uncompressed data length) and physical stored size
-(different if compression was applied).  Allowing for the varlena header bytes,
+logical datum size (original uncompressed data length), physical stored size
+(different if compression was applied), and the compression method used, if
+any.  Allowing for the varlena header bytes,
 the total size of an on-disk <acronym>TOAST</acronym> pointer datum is therefore 18
 bytes regardless of the actual size of the represented value.
 </para>