The biggest change in PostgreSQL v12 from the viewpoint of backward compatibility is that
recovery.conf has been absorbed into
This article describes the changes and how you can adapt to them.
Getting rid of
Up to now, the presence of the file
recovery.conf was the trigger for PostgreSQL to go into recovery mode upon server start. In addition, the file contained all parameters to configure recovery, for example
standby_mode: determines whether this is normal archive recovery or standby mode
restore_command: command to restore archived WAL segments
recovery_target*parameters to determine which point to recover to
primary_conninfo: how to connect to the streaming replication primary server
recovery.conf has been perceived as a wart for a long time, since it is unreasonable to have configuration parameters in more than one file.
In v12 PostgreSQL the move has been made, and the
recovery.conf parameters are now part of
postgresql.conf. These parameters are ignored until PostgreSQL is in recovery mode.
While this makes PostgreSQL work more naturally for newcomers, it has a few consequences that experienced users have to adapt to:
How to tell PostgreSQL to enter recovery mode?
Up to now, the existence of the file
recovery.conf triggered recovery mode.
Since the file is gone, two new files have taken its place:
recovery.signal: tells PostgreSQL to enter normal archive recovery
standby.signal: tells PostgreSQL to enter standby mode
The files can be empty, only the fact that they exist is relevant. They are deleted as soon as recovery finishes.
The parameter “
standby_mode” is not necessary anymore and has been removed.
What happens to the parameters after recovery is done?
recovery.conf was renamed to
recovery.done after recovery was finished. This effectively removed the recovery parameters.
From v12 on, the
standby.signal files will be deleted when recovery finishes, but the parameters in
postgresql.conf remain. They will be ignored as long as PostgreSQL is not in recovery, but it is a good idea to disable them with a “
#” comment. This will avoid nasty surprises later on, for example when you create a standby server.
If you set the recovery parameters using
ALTER SYSTEM, reset them with
ALTER SYSTEM RESET.
What happens to the “
--write-recovery-conf” option of
The option is still there, and that is no mistake. It doesn’t create
recovery.conf any more, but it adds recovery configuration parameters.
Rather than adding the parameters to
postgresql.conf, it adds them to
postgresql.auto.conf, just like
ALTER SYSTEM does. This is safer, since that file is made for automatic editing.
What happens if I recover PostgreSQL v12 with
If you didn’t notice the changes and try to recover PostgreSQL v12 with
recovery.conf, the following will happen:
- PostgreSQL finds
backup_label, but no signal file, so it will perform crash recovery from the checkpoint in
- If you created the backup with
pg_basebackupand left the option “
--wal-method” at its default level “
stream”, PostgreSQL will recover successfully to the end of the backup, but no further.
That means you have to restart recovery from the beginning.
- If the backup doesn’t include all the required WAL segments in
pg_wal, crash recovery will fail with the error message:
ERROR: could not find redo location referenced by checkpoint record
Since no recovery has been performed yet, you can fix your mistake and continue recovering.
How to adapt my backup scripts?
Backup is not affected by the change. So your backup scripts need no modification.
Scripts that perform archive recovery or set up standby servers will have to be adapted. The main difficulty will be to add the necessary recovery parameters.
My recommendation is to add the parameters to
postgresql.auto.conf, because as I said before, that file is made for automatic editing.
Here is some sample
bash code to add
sed --in-place \ -e "/^recovery_target/d" \ -e "$ a recovery_target_time = '2019-11-20 12:00:00'" \ $PGDATA/postgresql.auto.conf
The command first removes all options starting with “
recovery_target” and then adds the parameter.
Don’t forget to do the following before starting the server:
I recommend that you remove the recovery parameters again once recovery is done.
I am using some third-party backup software – what shall I do?
Any dedicated PostgreSQL backup software that is worth its salt should have adapted to these changes by now. Upgrade to a current release.
I have checked PostgreSQL v12 support for the most widely-used programs:
- pgBackRest: supports v12 from version 2.18 on
- pg_probackup: supports v12 from version 2.2.5 on
- Barman: supports v12 from version 2.9 on
The changes in recovery will need some getting used to for experienced users, but it shouldn’t be too hard to adapt.
Scripts that perform automatic recovery will have to be modified.
Take this as an opportunity to test your backup and recovery procedure!
For more information on backup in PostgreSQL, see my post on the deprecation of the “exclusive” backup method as of PostgreSQL v15.