Re: pg_resetwal: add --cluster-state option

> On Oct 5, 2026, at 12:03, shihao zhong <zhong950419(at)gmail(dot)com> wrote:
>
> Hi hackers,
>
> pg_resetwal always marks the cluster as shut down in pg_control.
> Michael suggested in [1] an option to store another state, and David
> asked for a separate thread [2]. So here it is.
>
> The patch adds --cluster-state. It takes shut-down, which is the
> default, shut-down-in-recovery, shutting-down, in-crash-recovery,
> in-archive-recovery or in-production. DB_STARTUP is left out because
> the server refuses to start with it.
>
> With any state other than shut-down, the next start goes through crash
> recovery. There is no WAL to replay, but the other steps still run.
>
> What I can show is unlogged tables. After an immediate stop and
> pg_resetwal -f, the server starts as if it was shut down cleanly, and
> an unlogged table keeps what was on disk:
>
> LOG: database system was shut down at ...
> $ psql -Atc "select count(*) from u"
> 1000
> With --cluster-state=in-production the table is reset:
> LOG: database system was not properly shut down; automatic recovery in progress
> LOG: redo is not required
> $ psql -Atc "select count(*) from u"
> 0
>
> That is the only use I have so far. Michael, what did you have in mind
> for it?
>
> [1] https://postgr.es/m/ar8mhs05SzC4hjmu@paquier.xyz
> [2] https://postgr.es/m/10a44059-c8f8-4bb5-8950-63390eedfaa0@pgbackrest.org
>
> Thanks,
> Shihao
>
> <v1-0001-pg_resetwal-Add-cluster-state-option.patch><v1-0002-Test-pg_resetwal-cluster-state.patch>

Hi Shihao,

Thanks for the patch. I reviewed it and didn't find any obvious implementation issues. I have a few thoughts about the design.

As I understand it, there is normally no need to override the state of a healthy cluster that was cleanly shut down. For troubleshooting a problematic cluster, though, would the following be useful?

* Print the previous recorded state alongside the new state before updating the control file.
* Provide an explicit mode to change only the cluster state, without doing other things. Michael's suggestion of a name such as pg_control_update in [1] also seems relevant here.

These would help a DBA identify and correct an inappropriate state selection before restarting the server, without having to perform another WAL reset.

There is also a documentation point. The current doc says:
```
<para>
If <command>pg_resetwal</command> is used on a data directory where the
server has been cleanly shut down and the control file is sound, then it
will have no effect on the contents of the database system, except that no
longer used WAL files are cleared away. Any other use is potentially
```

With a non-default --cluster-state value, a cluster can enter recovery on its next startup and have its unlogged tables emptied. That affects the database contents, so this paragraph might need to be updated accordingly.

Best regards,
--
Chao Li (Evan)
HighGo Software Co., Ltd.
https://www.highgo.com/