pg_resetwal: add --cluster-state option

On Mon, Oct 5, 2026 at 12:03 AM shihao zhong <zhong950419@gmail.com> wrote:

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.

Hi Shihao,

I tested the patch and confirmed that the default behaviour preserves
the unlogged table's 1,000 rows, while `--cluster-state=in-production`
causes the table to be emptied on the next startup, as described.

I noticed that an invalid value for `--cluster-state` directs the user
to `--help`, but the help output doesn't list the accepted values.
Would it be useful to include them there, similar to how `pg_ctl --help`
lists the values for `--mode`?

```
-m, --mode=MODE MODE can be "smart", "fast", or "immediate"
```

Kind regards,
Sho Ito

--
＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝
*Sho Ito (Sean)*

E-mail: i.sho.0628@gmail.com
LinkedIn: *https://www.linkedin.com/in/sho-ito-0628/
<https://www.linkedin.com/in/sho-ito-0628/&gt;*
GitHub: https://github.com/sean0628/
＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝

On Oct 5, 2026, at 12:03, shihao zhong <zhong950419@gmail.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] /messages/by-id/ar8mhs05SzC4hjmu@paquier.xyz
[2] /messages/by-id/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/

Hi Sho, Chao,

Thanks for looking. v2 is attached.

Sho Ito wrote:

I noticed that an invalid value for `--cluster-state` directs the user
to `--help`, but the help output doesn't list the accepted values.

Agreed, --help lists them now.

Chao Li wrote:

* Print the previous recorded state alongside the new state before
updating the control file.

pg_resetwal prints nothing on a real run, so I put this in --dry-run.
It now shows the stored state under "Current pg_control values", and
the new one under "Values to be changed". Both use the names the
option takes.

* Provide an explicit mode to change only the cluster state, without
doing other things.

I left this out. A wrong state can be fixed by running pg_resetwal -f
again with the right one. The WAL is already gone by then, so the
second reset loses nothing. I tried in-production, then -f with
shut-down, and the unlogged table kept its rows.

Without the reset it is a different tool, I think. For example,
setting shut-down on a crashed cluster would skip recovery while the
WAL is still there.

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.

Right. That paragraph now says it does not hold when --cluster-state
sets a state other than shut-down.

Thanks,
Shihao

On Fri, Oct 9, 2026 at 1:02 AM shihao zhong <zhong950419@gmail.com> wrote:

Hi Sho, Chao,

Thanks for looking. v2 is attached.

Sho Ito wrote:

I noticed that an invalid value for `--cluster-state` directs the user
to `--help`, but the help output doesn't list the accepted values.

Agreed, --help lists them now.

Hi Shihao,

Thanks. I built v2 on master with assertions enabled and verified the help
output and current/new state display in `--dry-run`. All six accepted states
were stored correctly.

Thanks,
Sho

--
＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝
*Sho Ito (Sean)*

E-mail: i.sho.0628@gmail.com
LinkedIn: *https://www.linkedin.com/in/sho-ito-0628/
<https://www.linkedin.com/in/sho-ito-0628/&gt;*
GitHub: https://github.com/sean0628/
＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝