Subject: change default default_toast_compression to lz4?

From: Peter Eisentraut <[email-masked]>
Date: Fri, 21 Nov 2025 12:11:38 +0100

How about changing the default of default_toast_compression to lz4?

I have seen cases where servers had performance problems and were 
CPU-bound because of pglz TOAST compression, and changing it to lz4 
relieved it significantly.  I suspect many users are leaving easy 
performance improvements on the table by not using this option.

The feature was introduced in PostgreSQL 14, so it should be well 
stabilized now.

I suppose one issue is that lz4 support is not compiled-in by default, 
but in practice most users will have it.  The default could be lz4 if 
lz4 support is built, otherwise pglz.  This would be similar to other 
parameters where the default is the best one depending on the build 
configuration.

---

From: Aleksander Alekseev <[email-masked]>
Date: Fri, 21 Nov 2025 14:33:38 +0300

Hi Peter,

> How about changing the default of default_toast_compression to lz4?

To me it sounds like a great idea.

> parameters where the default is the best one depending on the build

Are there good reasons why we can't simply make lz4 a required
dependency? In the worst case we could simply copy its implementation,
the license permits.

-- 
Best regards,
Aleksander Alekseev

---

From: Daniel Gustafsson <[email-masked]>
Date: Fri, 21 Nov 2025 13:27:28 +0100

> On 21 Nov 2025, at 12:33, Aleksander Alekseev <[email-masked]> wrote:

>> The default could be lz4 if

+1

> dependency? In the worst case we could simply copy its implementation,

I think we should, as much as we can, avoid vendoring code, especially
something like lz4 which can be expected to be available nearly everywhere.

--
Daniel Gustafsson

---

From: Andres Freund <[email-masked]>
Date: Fri, 21 Nov 2025 11:10:14 -0500

Hi,

On 2025-11-21 12:11:38 +0100, Peter Eisentraut wrote:
> I have seen cases where servers had performance problems and were CPU-bound
> because of pglz TOAST compression, and changing it to lz4 relieved it
> significantly.  I suspect many users are leaving easy performance
> improvements on the table by not using this option.

+1 - I also have seen *and* hit this numerous times.

IIRC it makes the tests runs a tad bit faster too.

> I suppose one issue is that lz4 support is not compiled-in by default, but
> in practice most users will have it.  The default could be lz4 if lz4
> support is built, otherwise pglz.  This would be similar to other parameters
> where the default is the best one depending on the build configuration.

I think we should mark lz4 as a default-required dependency if we change the
default. That way one needs to explicitly opt into a build that won't be
compatible with existing data directories created (due to pre-existing lz4 .

Greetings,

Andres Freund

---

From: Tom Lane <[email-masked]>
Date: Fri, 21 Nov 2025 11:16:21 -0500

> compatible with existing data directories created (due to pre-existing lz4 .

Agreed --- we should make it act like icu or readline, you have to
opt out.  (I'm not voting one way or the other on changing the
default, but if we do we should do it that way.)

			regards, tom lane

---

From: Álvaro Herrera <[email-masked]>
Date: Sat, 22 Nov 2025 14:11:56 +0100

> something like lz4 which can be expected to be available nearly everywhere.

Yeah.  There's the security aspect: if lz4 is found to have a security
bug, we would be obliged to issue an advisory and matching release.
It's best if the library code is kept separate, so their own security
advisory is enough.

-- 
Álvaro Herrera         PostgreSQL Developer  —  https://www.EnterpriseDB.com/

---

From: Michael Paquier <[email-masked]>
Date: Wed, 26 Nov 2025 13:35:08 +0900

> where the default is the best one depending on the build configuration.

+1.  That makes sense here to flip the default depending on what the
code is built with, with lz4 if available, pglz otherwise.
--
Michael

---

From: "Euler Taveira" <[email-masked]>
Date: Wed, 26 Nov 2025 15:59:37 -0300

> code is built with, with lz4 if available, pglz otherwise.

Since we have an agreement that $SUBJECT is ok, I wrote a patch for it. It
selects the compression method based on USE_LZ4. It also adjusts the
postgresql.conf if required.

-- 
Euler Taveira
EDB   https://www.enterprisedb.com/

From 89084e17df13823077bad2f6ad4c1cb0e095ccc4 Mon Sep 17 00:00:00 2001
From: Euler Taveira <[email-masked]>
Date: Wed, 26 Nov 2025 12:40:43 -0300
Subject: [PATCH v1] Change default_toast_compression to lz4

The default value for default_toast_compression was pglz. The main
reason is that this option is always available. However, it is known
that pglz uses more CPU than lz4. The default value will be lz4 if lz4
support is built, otherwise, pglz.
---
 doc/src/sgml/config.sgml                      | 3 ++-
 src/backend/access/common/toast_compression.c | 2 +-
 src/backend/utils/misc/guc_parameters.dat     | 2 +-
 src/bin/initdb/initdb.c                       | 5 +++++
 src/include/access/toast_compression.h        | 9 +++++++++
 5 files changed, 18 insertions(+), 3 deletions(-)

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 737b90736bf..c063f013e2f 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -9910,7 +9910,8 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
         The supported compression methods are <literal>pglz</literal> and
         (if <productname>PostgreSQL</productname> was compiled with
         <option>--with-lz4</option>) <literal>lz4</literal>.
-        The default is <literal>pglz</literal>.
+        The default is <literal>lz4</literal> (if available); otherwise,
+        <literal>pglz</literal>.
        </para>
       </listitem>
      </varlistentry>
diff --git a/src/backend/access/common/toast_compression.c b/src/backend/access/common/toast_compression.c
index 926f1e4008a..4bb29665eab 100644
--- a/src/backend/access/common/toast_compression.c
+++ b/src/backend/access/common/toast_compression.c
@@ -23,7 +23,7 @@
 #include "varatt.h"
 
 /* GUC */
-int			default_toast_compression = TOAST_PGLZ_COMPRESSION;
+int			default_toast_compression = DEFAULT_TOAST_COMPRESSION;
 
 #define NO_COMPRESSION_SUPPORT(method) \
 	ereport(ERROR, \
diff --git a/src/backend/utils/misc/guc_parameters.dat b/src/backend/utils/misc/guc_parameters.dat
index 3b9d8349078..cbe9bf055b3 100644
--- a/src/backend/utils/misc/guc_parameters.dat
+++ b/src/backend/utils/misc/guc_parameters.dat
@@ -735,7 +735,7 @@
 { name => 'default_toast_compression', type => 'enum', context => 'PGC_USERSET', group => 'CLIENT_CONN_STATEMENT',
   short_desc => 'Sets the default compression method for compressible values.',
   variable => 'default_toast_compression',
-  boot_val => 'TOAST_PGLZ_COMPRESSION',
+  boot_val => 'DEFAULT_TOAST_COMPRESSION',
   options => 'default_toast_compression_options',
 },
 
diff --git a/src/bin/initdb/initdb.c b/src/bin/initdb/initdb.c
index 92fe2f531f7..92b120d8ab8 100644
--- a/src/bin/initdb/initdb.c
+++ b/src/bin/initdb/initdb.c
@@ -1424,6 +1424,11 @@ setup_config(void)
 									  "0640", false);
 	}
 
+#if USE_LZ4
+	conflines = replace_guc_value(conflines, "default_toast_compression",
+								  "lz4", true);
+#endif
+
 	/*
 	 * Now replace anything that's overridden via -c switches.
 	 */
diff --git a/src/include/access/toast_compression.h b/src/include/access/toast_compression.h
index 13c4612ceed..7526ea50c5a 100644
--- a/src/include/access/toast_compression.h
+++ b/src/include/access/toast_compression.h
@@ -52,6 +52,15 @@ typedef enum ToastCompressionId
 
 #define CompressionMethodIsValid(cm)  ((cm) != InvalidCompressionMethod)
 
+/*
+ * Choose an appropriate default toast compression method. If lz4 is
+ * compiled-in, use it, otherwise, use pglz.
+ */
+#ifdef USE_LZ4
+#define DEFAULT_TOAST_COMPRESSION	TOAST_LZ4_COMPRESSION
+#else
+#define DEFAULT_TOAST_COMPRESSION	TOAST_PGLZ_COMPRESSION
+#endif
 
 /* pglz compression/decompression routines */
 extern struct varlena *pglz_compress_datum(const struct varlena *value);
-- 
2.39.5

---

From: Aleksander Alekseev <[email-masked]>
Date: Thu, 27 Nov 2025 12:44:18 +0300

Hi Euler,

> postgresql.conf if required.

Many thanks for working on this. Unfortunately the patch is
incomplete. I think we also agreed that lz4 should be opt-out.

-- 
Best regards,
Aleksander Alekseev

---

From: "Euler Taveira" <[email-masked]>
Date: Thu, 04 Dec 2025 17:11:15 -0300

> incomplete. I think we also agreed that lz4 should be opt-out.

Aleksander, I missed this point.

Here it is v2. It enforces the lz4 dependency. It works the same as other
dependencies (readline, icu, zlib); error if the dependency could not be found.
Regarding meson, I'm confused. If any of the referred dependencies (icu,
readline, zlib) is not found, there is no hard error. Instead, the feature is
disabled. I searched for a discussion about this decision but couldn't find.
For this patch, I decided to use the same pattern (no error) but I added a
warning message (similar to zlib).

$ meson setup build --prefix=/tmp/pg | grep -i warning
meson.build:1100: WARNING: did not find lz4
meson.build:1675: WARNING: did not find zlib

The other alternative is to always 'enabled' lz4 in meson_options.txt. This
requires you to explicitly enable/disable lz4 if you are using -Dauto_features
option.

Should it report an error (like autoconf) instead of silently disable the
feature that is a requirement? If yes, then we should add error messages for
these 3 dependencies.

$ ./configure --prefix=/tmp/pg
.
.
checking whether to build with ICU support... yes
checking for icu-uc icu-i18n... no
configure: error: Package requirements (icu-uc icu-i18n) were not met:

Package 'icu-uc', required by 'virtual:world', not found
Package 'icu-i18n', required by 'virtual:world', not found

Consider adjusting the PKG_CONFIG_PATH environment variable if you
installed software in a non-standard prefix.

Alternatively, you may set the environment variables ICU_CFLAGS
and ICU_LIBS to avoid the need to call pkg-config.
See the pkg-config man page for more details.

$ git clean -dfxq
$ meson setup build --prefix=/tmp/pg
.
.
Run-time dependency icu-uc found: NO (tried pkgconfig and cmake)
Run-time dependency icu found: NO (tried cmake)
.
.
Run-time dependency readline found: NO (tried pkgconfig and cmake)
Library readline found: NO
.
.
  External libraries
    bonjour                : NO
    bsd_auth               : NO
    docs                   : NO
    docs_pdf               : NO
    gss                    : NO
    icu                    : NO
    ldap                   : NO
    libcurl                : NO
    libnuma                : NO
    liburing               : NO
    libxml                 : NO
    libxslt                : NO
    llvm                   : NO
    lz4                    : NO
    nls                    : YES
    openssl                : NO
    pam                    : NO
    plperl                 : NO 5.40.1
    plpython               : NO
    pltcl                  : NO
    readline               : NO
    selinux                : NO
    systemd                : NO
    uuid                   : NO
    zlib                   : NO
    zstd                   : NO

  User defined options
    prefix                 : /tmp/pg

Found ninja-1.12.1 at /usr/bin/ninja

From d700609b2c194e00c7ded6ed9a16dd60427ff846 Mon Sep 17 00:00:00 2001
From: Euler Taveira <[email-masked]>
Date: Wed, 26 Nov 2025 12:40:43 -0300
Subject: [PATCH v2] Change default_toast_compression to lz4

 configure.ac                                  |  2 +-
 doc/src/sgml/installation.sgml                | 12 ++++++++++++
 meson.build                                   |  2 ++
 8 files changed, 33 insertions(+), 4 deletions(-)

diff --git a/configure.ac b/configure.ac
index c2413720a18..0a4598e511d 100644
--- a/configure.ac
+++ b/configure.ac
@@ -1133,7 +1133,7 @@ AC_SUBST(with_zlib)
 # LZ4
 #
 AC_MSG_CHECKING([whether to build with LZ4 support])
-PGAC_ARG_BOOL(with, lz4, no, [build with LZ4 support],
+PGAC_ARG_BOOL(with, lz4, yes, [build without LZ4 support],
               [AC_DEFINE([USE_LZ4], 1, [Define to 1 to build with LZ4 support. (--with-lz4)])])
 AC_MSG_RESULT([$with_lz4])
 AC_SUBST(with_lz4)
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 405c9689bd0..73eb33e2d99 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -9910,7 +9910,8 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
         The supported compression methods are <literal>pglz</literal> and
         (if <productname>PostgreSQL</productname> was compiled with
         <option>--with-lz4</option>) <literal>lz4</literal>.
-        The default is <literal>pglz</literal>.
+        The default is <literal>lz4</literal> (if available); otherwise,
+        <literal>pglz</literal>.
        </para>
       </listitem>
      </varlistentry>
diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml
index fe8d73e1f8c..f8b43a8cb7b 100644
--- a/doc/src/sgml/installation.sgml
+++ b/doc/src/sgml/installation.sgml
@@ -1315,6 +1315,18 @@ build-postgresql:
        </listitem>
       </varlistentry>
 
+      <varlistentry id="configure-option-without-lz4">
+       <term><option>--without-lz4</option></term>
+       <listitem>
+        <para>
+         <indexterm>
+          <primary>lz4</primary>
+         </indexterm>
+         Prevents use of the <application>LZ4</application> library.
+        </para>
+       </listitem>
+      </varlistentry>
+
      </variablelist>
 
    </sect3>
diff --git a/meson.build b/meson.build
index 6e7ddd74683..1da53bf0138 100644
--- a/meson.build
+++ b/meson.build
@@ -1096,6 +1096,8 @@ if not lz4opt.disabled()
   if lz4.found()
     cdata.set('USE_LZ4', 1)
     cdata.set('HAVE_LIBLZ4', 1)
+  else
+    warning('did not find lz4')
   endif
 
 else
 
 /* GUC */

 
+#if USE_LZ4

+/*

---

From: Michael Paquier <[email-masked]>
Date: Fri, 5 Dec 2025 11:23:31 +0900

> warning message (similar to zlib).

Another thing to be careful of is that this would immediately break
the CI task CompilerWarnings for mingw:
[02:03:19.626] checking whether to build with LZ4 support... yes
[02:03:19.626] checking for liblz4... no
[02:03:19.694] configure: error: Package requirements (liblz4) were
not met:

So this had better be adjusted in one go, in the shape of a tweak in
mingw_cross_warning_script with the addition of a --without-lz4, same
way as for ICU.

> feature that is a requirement? If yes, then we should add error messages for

Hmm.  It seems to me that we should just set not_found_dep if lz4
cannot be found, leaving meson_options.txt as it is currently, no?
One could always force meson's hand with -Dlz4=disabled.  As a whole,
I'd value more consistency with how icu is handled if we want to force
LZ4 across the board in the backend.  The case with zlib is different
in the backend: we only use it on a wanted-basis for compression
specifications in server-side compressed base backups, so it seems to
me that there's a case for being a tad more aggressive with LZ4 as it
relates to TOAST compression, forcing an error rather than ignoring it
silently if it cannot be found.
--
Michael

---

From: Michael Paquier <[email-masked]>
Date: Wed, 4 Mar 2026 13:09:40 +0900

On Fri, Feb 27, 2026 at 10:10:20AM +0900, Michael Paquier wrote:
> Ah, right.  This is what we have done for ICU in fcb21b3acdcb.  While
> --with-lz4 is still allowed for backward-compatibility, we show only
> --without-icu in the output of configure --help.  Reflecting the
> documentation to show up the same contents as --help makes sense.

It would have been a waste to not see this change happening, so I have
looked a bit more in depth at it.  You are right that we should remove
the reference to --with-lz4, but it seems to me that this should apply
to all the references of the switch we have in the docs.  The change
in meson.build was not necessary.  Another thing not yet included was
the mandatory autoreconf.  With all that done, applied.

Now, let's see how much this breaks the buildfarm..  Because things
will break.  I'll send a poke to the buildfarm mailing list.
--
Michael

---

From: Jelte Fennema-Nio <[email-masked]>
Date: Wed, 4 Mar 2026 08:15:50 +0100

On Wed, 4 Mar 2026 at 06:05, Tom Lane <[email-masked]> wrote:
>
> Michael Paquier <[email-masked]> writes:
> > Now, let's see how much this abreaks the buildfarm..  Because things
> I don't think this idea is really fully baked yet.  What happens
> if I build with liblz4, and run for a while with that so that
> there are lz4-compressed TOAST values, and then try to update
> to a build without LZ4?

That doesn't seem like a new problem to me. That's already possible
since PG14. To me it actually seems more likely to happen, because we
default to allowing builds without lz4 (which we stopped doing on
master). The fact that we haven't had (many) people complain indicates
to me that it isn't a big problem in practice.