recovery.conf is gone in PostgreSQL v12

The biggest change in PostgreSQL v12 from the viewpoint of backward compatibility is that recovery.conf has been absorbed into postgresql.conf.

This article describes the changes and how you can adapt to them.

Getting rid of recovery.conf

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
• The 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?

Before, recovery.conf was renamed to recovery.done after recovery was finished. This effectively removed the recovery parameters.

From v12 on, the recovery.signal or 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 pg_basebackup?

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 recovery.conf?

If you didn't notice the changes and try to recover PostgreSQL v12 with recovery.conf, the following will happen:

• recovery.conf is ignored.
• PostgreSQL finds backup_label, but no signal file, so it will perform crash recovery from the checkpoint in backup_label.
• If you created the backup with pg_basebackup and 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 recovery_target_time:

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

Wrapping up

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.

In order to receive regular updates on important changes in PostgreSQL, subscribe to our newsletter, or follow us on Twitter, Facebook, or LinkedIn.