Waiting for PostgreSQL 14 – Rename wal_keep_segments to wal_keep_size.

On 20th of July 2020, Fujii Masao committed patch:

Rename wal_keep_segments to wal_keep_size.
max_slot_wal_keep_size that was added in v13 and wal_keep_segments are
the GUC parameters to specify how much WAL files to retain for
the standby servers. While max_slot_wal_keep_size accepts the number of
bytes of WAL files, wal_keep_segments accepts the number of WAL files.
This difference of setting units between those similar parameters could
be confusing to users.
To alleviate this situation, this commit renames wal_keep_segments to
wal_keep_size, and make users specify the WAL size in it instead of
the number of WAL files.
There was also the idea to rename max_slot_wal_keep_size to
max_slot_wal_keep_segments, in the discussion. But we have been moving
away from measuring in segments, for example, checkpoint_segments was
replaced by max_wal_size. So we concluded to rename wal_keep_segments
to wal_keep_size.
Back-patch to v13 where max_slot_wal_keep_size was added.
Author: Fujii Masao
Reviewed-by: Álvaro Herrera, Kyotaro Horiguchi, David Steele
Discussion: https://postgr.es/m/574b4ea3-e0f9-b175-ead2-ebea7faea855@oss.nttdata.com

Commit message makes it abundantly clear what has changed, and why, but just let me quickly show example.

In previous versions, we had wal_keep_segments GUC that made sure that certain number of WAL files will be kept on primary server even if they were already archived. This was to make it easier to setup and sustain streaming replication.

One could have, for example:

$ SHOW wal_keep_segments;
(1 ROW)

Now, if you'd have “wal_keep_segments" in your config, PostgreSQL will not start:

=$ pg_ctl START
waiting FOR server TO START....2020-07-27 10:29:10.244 GMT [74802] LOG:  unrecognized configuration parameter "wal_keep_segments" IN file "/home/pgdba/data/conf.d/depesz.conf" line 21
2020-07-27 10:29:10.244 GMT [74802] FATAL:  configuration file "/home/pgdba/data/conf.d/depesz.conf" contains errors
 stopped waiting
pg_ctl: could NOT START server
Examine the log output.

And instead you have to provide it as:

wal_keep_size = 16000

In psql, we can see that unit for the value is MB:

$ SELECT * FROM pg_settings WHERE name = 'wal_keep_size';
─[ RECORD 1 ]───┬─────────────────────────────────────────────────────
name            │ wal_keep_size
setting         │ 16000
unit            │ MB
category        │ Replication / Sending Servers
short_desc      │ Sets the SIZE OF WAL files held FOR standby servers.
extra_desc      │ [NULL]
context         │ sighup
vartype         │ INTEGER
SOURCE          │ configuration file
min_val         │ 0
max_val         │ 2147483647
enumvals        │ [NULL]
boot_val        │ 0
reset_val       │ 16000
sourcefile      │ /home/pgdba/DATA/conf.d/depesz.conf
sourceline      │ 16
pending_restart │ f

So, if your previous value in wal_keep_segments was “N", then, to achieve the same effect, you should set wal_keep_size to 16 * N.

Simple change, yet something that one has to be aware about when upgrading while keeping the same config source.

But – it will be more consistent and more readable, which I think is good. Thanks to all involved.

4 thoughts on “Waiting for PostgreSQL 14 – Rename wal_keep_segments to wal_keep_size.”

  1. @Justin:

    yes, as can be seen in commit log: “Back-patch to v13 where max_slot_wal_keep_size was added”

    But the change originated in Pg 14, hence the title.

  2. is this parmeters will change automatically when upgrading from pg12 to pg13 ? or we must manually chage it?

  3. @Valeh:
    not sure what you mean.
    this is parameter in config file.
    How it will be set in newer pg depends on how you will be upgrading.

Comments are closed.