Improve some comments in pg_checksums about the needed clean shutdown

It was not clear from the code why it is necessary.  And we need a clean
shutdown to avoid random checksum failures caused by torn pages.

Author: Masahiko Sawada
Discussion: https://postgr.es/m/CAD21AoDum5MbAb7F=pa9dOD1W2tukuDMPzWT7NjZceNoWB_6Qw@mail.gmail.com

diff --git a/src/bin/pg_checksums/pg_checksums.c b/src/bin/pg_checksums/pg_checksums.c
index 7c7a75cdcd6167290f0500db1a4695be841ed652..b8e7c32dba72307b978006eda190c2c4c66db90a 100644 (file)
--- a/src/bin/pg_checksums/pg_checksums.c
+++ b/src/bin/pg_checksums/pg_checksums.c
@@ -475,7 +475,7 @@ main(int argc, char *argv[])
                exit(1);
        }
 
-       /* Check if cluster is running */
+       /* Read the control file and check compatibility */
        ControlFile = get_controlfile(DataDir, &crc_ok);
        if (!crc_ok)
        {
@@ -497,6 +497,11 @@ main(int argc, char *argv[])
                exit(1);
        }
 
+       /*
+        * Check if cluster is running.  A clean shutdown is required to avoid
+        * random checksum failures caused by torn pages.  Note that this doesn't
+        * guard against someone starting the cluster concurrently.
+        */
        if (ControlFile->state != DB_SHUTDOWNED &&
                ControlFile->state != DB_SHUTDOWNED_IN_RECOVERY)
        {