Subject: [PATCH v3] Change wal_compression=on to the first of zstd, lz4, pglz

From: Christoph Berg <[email-masked]>
Date: Fri, 31 Jul 2026 14:24:23 +0200

Previously, wal_compression=on was an alias for pglz, with the idea that
users could make an informed choice to pick a better option. But in
practice, users either don't want to make that choice (they just want
WAL compression), can't really pick the best option (they are setting
the default in an environment where someone else is running the
workload), or simply don't know that there are other options
(previously, "on" was the only choice available).

In all these cases, mapping "on" to something that isn't pglz is better.
It is strictly slower and does not compress better. We pick zstd here.
Users can still make the informed choice and switch to lz4 if their
workload works better there, but zstd is still better than pglz in that
case.

Like for the default TOAST compression, the actual default "on" value
depends on if PostgreSQL was compiled with the compression algorithms.
The first of zstd, lz4, pglz is picked. (Only the latter is always
available, but practically, builds will have at least one of the better
algorithms.)
---
 doc/src/sgml/config.sgml                      | 12 ++++++------
 src/backend/utils/misc/guc_tables.c           |  8 ++++----
 src/backend/utils/misc/postgresql.conf.sample |  3 ++-
 src/include/access/xlog.h                     | 13 +++++++++++++
 4 files changed, 25 insertions(+), 11 deletions(-)

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index aa7b1bd75d2..9bfe0443848 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -3667,12 +3667,12 @@ include_dir 'conf.d'
         <xref linkend="guc-full-page-writes"/> is on, during a base backup,
         etc.).
         A compressed page image will be decompressed during WAL replay.
-        The supported methods are <literal>pglz</literal>,
-        <literal>lz4</literal> (if <productname>PostgreSQL</productname>
-        was compiled with <option>--with-lz4</option>) and
-        <literal>zstd</literal> (if <productname>PostgreSQL</productname>
-        was compiled with <option>--with-zstd</option>).
-        The value <literal>on</literal> is a historical spelling of <literal>pglz</literal>.
+        The supported methods are <literal>off</literal>, <literal>on</literal>,
+        <literal>zstd</literal> (if <productname>PostgreSQL</productname> was compiled with <option>--with-zstd</option>)
+        <literal>lz4</literal> (if <productname>PostgreSQL</productname> was compiled with <option>--with-lz4</option>), and
+        <literal>pglz</literal>.
+        The value <literal>on</literal> selects the first of <literal>zstd</literal>,
+        <literal>lz4</literal>, <literal>pglz</literal> that is available.
         The default value is <literal>off</literal>.
         Only superusers and users with the appropriate <literal>SET</literal>
         privilege can change this setting.
diff --git a/src/backend/utils/misc/guc_tables.c b/src/backend/utils/misc/guc_tables.c
index 1ec460b6a82..e0b21053287 100644
--- a/src/backend/utils/misc/guc_tables.c
+++ b/src/backend/utils/misc/guc_tables.c
@@ -484,13 +484,13 @@ static const struct config_enum_entry wal_compression_options[] = {
 #ifdef USE_ZSTD
 	{"zstd", WAL_COMPRESSION_ZSTD, false},
 #endif
-	{"on", WAL_COMPRESSION_PGLZ, false},
+	{"on", DEFAULT_WAL_COMPRESSION, false},
 	{"off", WAL_COMPRESSION_NONE, false},
-	{"true", WAL_COMPRESSION_PGLZ, true},
+	{"true", DEFAULT_WAL_COMPRESSION, true},
 	{"false", WAL_COMPRESSION_NONE, true},
-	{"yes", WAL_COMPRESSION_PGLZ, true},
+	{"yes", DEFAULT_WAL_COMPRESSION, true},
 	{"no", WAL_COMPRESSION_NONE, true},
-	{"1", WAL_COMPRESSION_PGLZ, true},
+	{"1", DEFAULT_WAL_COMPRESSION, true},
 	{"0", WAL_COMPRESSION_NONE, true},
 	{NULL, 0, false}
 };
diff --git a/src/backend/utils/misc/postgresql.conf.sample b/src/backend/utils/misc/postgresql.conf.sample
index 7958653077b..9d178fb09c1 100644
--- a/src/backend/utils/misc/postgresql.conf.sample
+++ b/src/backend/utils/misc/postgresql.conf.sample
@@ -262,7 +262,8 @@
 #wal_log_hints = off                    # also do full page writes of non-critical updates
                                         # (change requires restart)
 #wal_compression = off                  # enables compression of full-page writes;
-                                        # off, pglz (or "on"), lz4, or zstd
+                                        # off, on, zstd, lz4, or pglz (on = zstd if
+                                        # available, else lz4 if available, else pglz)
 #wal_init_zero = on                     # zero-fill new WAL files
 #wal_recycle = on                       # recycle WAL files
 #wal_buffers = -1                       # min 32kB, -1 sets based on shared_buffers
diff --git a/src/include/access/xlog.h b/src/include/access/xlog.h
index 4dd98624204..9259b3461c7 100644
--- a/src/include/access/xlog.h
+++ b/src/include/access/xlog.h
@@ -87,6 +87,19 @@ typedef enum WalCompression
 	WAL_COMPRESSION_ZSTD,
 } WalCompression;
 
+/*
+ * Choose an appropriate default WAL compression method for wal_compression=on.
+ * Prefer zstd when compiled in; otherwise use lz4 if available, falling back
+ * to pglz.
+ */
+#ifdef USE_ZSTD
+#define DEFAULT_WAL_COMPRESSION	WAL_COMPRESSION_ZSTD
+#elif defined(USE_LZ4)
+#define DEFAULT_WAL_COMPRESSION	WAL_COMPRESSION_LZ4
+#else
+#define DEFAULT_WAL_COMPRESSION	WAL_COMPRESSION_PGLZ
+#endif
+
 /* Recovery states */
 typedef enum RecoveryState
 {
-- 
2.53.0

--CjtMoaqLlMP6LcXJ--