postgres.git / summary / log / commit / refs
commit 931c9701f2509160a2bed7d50129669e2cb32bf9
Author: Tomas Vondra <tomas.vondra@postgresql.org>
Date: Tue Aug 11 23:08:21 2026 +0000
Change wal_compression=on to the first of zstd, lz4, pglz
Previously, wal_compression=on was an alias for pglz, with the
assumption that users could make an informed choice to pick a better
option. But in practice, users rarely got to that second step.
Many users don't want to be choosing algorithms - they just want WAL
compression, and expect that to work well. The configuration parameter
is set by administrators, who do not control the workload, and so are
not in a position to evaluate the options anyway. Some users may not
even realize there are other options, as previously "on" was the only
choice available.
This change maps "on" to non-pglz options, supported by the build. Both
lz4 and zstd are faster, with a comparable (or better) compression
ratio. We prefer zstd over lz4 - per our testing the better compression
ratio pays for the lower (de)compression speed.
Like for TOAST compression, the value depends on algorithms supported by
the PostgreSQL build, with lz4 and zstd being optional. But most builds
will have at least one of these external libraries. If neither zstd or
lz4 is supported, we fallback to pglz.
This only affects what "on" means. Users can still make the informed
choice and explicitly select a compression algorithm if it works better
for their system. The default value for "wal_compression" remains "off."
Initial proposal and patch by wenhui qiu, reviews and patch adjustments
by Christoph Berg. A number of other people participated in the
discussion. Benchmarks by me.
Backpatch to 19.
Author: wenhui qiu <qiuwenhuifx@gmail.com>
Reviewed-by: Christoph Berg <myon@debian.org>
Reviewed-by: Michael Paquier <michael@paquier.xyz>
Discussion: https://postgr.es/m/CAGjGUAL1b=Mwd1SCvLbo+fivEr9KDpFcu4jmqKCZXwT=6CiiGQ@mail.gmail.com
Backpatch-through: 19
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 10b304122ef..b9b6e6b29fc 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -3680,12 +3680,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 a7cb4ac32cf..c6d9b2a6f89 100644
--- a/src/backend/utils/misc/guc_tables.c
+++ b/src/backend/utils/misc/guc_tables.c
@@ -485,13 +485,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", WAL_COMPRESSION_ON, false},
{"off", WAL_COMPRESSION_NONE, false},
- {"true", WAL_COMPRESSION_PGLZ, true},
+ {"true", WAL_COMPRESSION_ON, true},
{"false", WAL_COMPRESSION_NONE, true},
- {"yes", WAL_COMPRESSION_PGLZ, true},
+ {"yes", WAL_COMPRESSION_ON, true},
{"no", WAL_COMPRESSION_NONE, true},
- {"1", WAL_COMPRESSION_PGLZ, true},
+ {"1", WAL_COMPRESSION_ON, 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 c6311837e67..e759f06b50f 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 means the first
+ # of zstd, lz4 and pglz, supported by the build)
#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..338d68d7424 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.
+ */
+#if defined(USE_ZSTD)
+#define WAL_COMPRESSION_ON WAL_COMPRESSION_ZSTD
+#elif defined(USE_LZ4)
+#define WAL_COMPRESSION_ON WAL_COMPRESSION_LZ4
+#else
+#define WAL_COMPRESSION_ON WAL_COMPRESSION_PGLZ
+#endif
+
/* Recovery states */
typedef enum RecoveryState
{
[parent: 040932c31146]