docs: Clarify how ALTER TABLE .. SET COMPRESSION works.

Justin Pryzby, per a complaint from Michael Paquier. Reviewed by
Dilip Kumar and by me.

Discussion: http://postgr.es/m/20210429040132[email protected]

diff --git a/doc/src/sgml/ref/alter_table.sgml b/doc/src/sgml/ref/alter_table.sgml
index 6166b263345230bafb489411ace47471b9fe27e2..9cef1f101eb25f8828a062bd2abe70fc100b7e1a 100644 (file)
--- a/doc/src/sgml/ref/alter_table.sgml
+++ b/doc/src/sgml/ref/alter_table.sgml
@@ -391,7 +391,21 @@ WITH ( MODULUS numeric_literal, REM
     
     
      
-      This sets the compression method for a column.  The supported compression
+      This sets the compression method to be used for data inserted into a column.
+
+      This does not cause the table to be rewritten, so existing data may still
+      be compressed with other compression methods.  If the table is rewritten with
+      VACUUM FULL or CLUSTER, or restored
+      with pg_restore, then all tuples are rewritten
+      with the configured compression methods.
+
+      Also, note that when data is inserted from another relation (for example,
+      by INSERT ... SELECT), tuples from the source data are
+      not necessarily detoasted, and any previously compressed data is retained
+      with its existing compression method, rather than recompressing with the
+      compression methods of the target columns.
+
+      The supported compression
       methods are pglz and lz4.
       lz4 is available only if --with-lz4
       was used when building PostgreSQL.