Re: clean up pg_checksums.sgml
On Sun, Apr 07, 2019 at 07:15:46PM -0500, Justin Pryzby wrote: > Sorry, the patch was on top of an brief effort I made to rename "check > checksums" to "verify checksums", before asking about the idea. > > PFA patch to master. Thanks for the patch, Justin. That looks indeed clearer after considering your proposal, so I have applied most of it. There were some terms I found fuzzy though. For example, I have replaced "checksum state" by "data checksum configuration", but kept "verifying" because "check checksums" sounds kind of redundant. -- Michael signature.asc Description: PGP signature
Re: clean up pg_checksums.sgml
On Sat, Mar 30, 2019 at 10:51:23AM +0900, Michael Paquier wrote: > On Fri, Mar 29, 2019 at 09:32:10AM -0500, Justin Pryzby wrote: > > PFA patch with minor improvements to documentation. > > Patch does not apply, and I have reworded the last paragraph about > failures while operating. Sorry, the patch was on top of an brief effort I made to rename "check checksums" to "verify checksums", before asking about the idea. PFA patch to master. Justin > > Also, what do you think about changing user-facing language from > > "check checksum" to "verify checksum" ? I see that commit ed308d78 > > actually moved in the other direction, but I preferred "verify". > > Yes, that's a debate that we had during the discussion for the new > switches, and we have decided to use --check over --verify for the > default option. On the one hand, "Check checksums" is rather > redundant, but that's more consistent with the option name. "Verify > checksums" is perhaps more elegant. My opinion is that having some > consistency between the option names and the docs is nicer. >From f151f8200c65f4a3ae61afe444f213e190e94013 Mon Sep 17 00:00:00 2001 From: Justin Pryzby Date: Thu, 28 Mar 2019 19:20:52 -0500 Subject: [PATCH] Clean up pg_checksums.sgml --- doc/src/sgml/ref/pg_checksums.sgml | 18 +- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/doc/src/sgml/ref/pg_checksums.sgml b/doc/src/sgml/ref/pg_checksums.sgml index 47d4a62..01c65fe 100644 --- a/doc/src/sgml/ref/pg_checksums.sgml +++ b/doc/src/sgml/ref/pg_checksums.sgml @@ -39,15 +39,16 @@ PostgreSQL documentation pg_checksums checks, enables or disables data checksums in a PostgreSQL cluster. The server must be shut down cleanly before running - pg_checksums. The exit status is zero if there - are no checksum errors when checking them, and nonzero if at least one - checksum failure is detected. If enabling or disabling checksums, the + pg_checksums. When verifying checksums, the exit + status is zero if there are no checksum errors, and nonzero if at least one + checksum failure is detected. When enabling or disabling checksums, the exit status is nonzero if the operation failed. - While checking or enabling checksums needs to scan or write every file in - the cluster, disabling checksums will only update the file + When verifying checksums, every file in the cluster is scanned; + When enabling checksums, every file in the cluster is also rewritten. + Disabling checksums only updates the file pg_control. @@ -218,10 +219,9 @@ PostgreSQL documentation If pg_checksums is aborted or killed while - enabling or disabling checksums, the cluster will keep the same - configuration for data checksums as before the operation attempted. - pg_checksums can be restarted to - attempt again the same operation. + enabling or disabling checksums, the cluster's checksum state will be + unchanged, and pg_checksums would need to be + rerun and start its operation from scratch. -- 2.1.4
Re: clean up pg_checksums.sgml
On Fri, Mar 29, 2019 at 09:32:10AM -0500, Justin Pryzby wrote: > PFA patch with minor improvements to documentation. Patch does not apply, and I have reworded the last paragraph about failures while operating. > Also, what do you think about changing user-facing language from > "check checksum" to "verify checksum" ? I see that commit ed308d78 > actually moved in the other direction, but I preferred "verify". Yes, that's a debate that we had during the discussion for the new switches, and we have decided to use --check over --verify for the default option. On the one hand, "Check checksums" is rather redundant, but that's more consistent with the option name. "Verify checksums" is perhaps more elegant. My opinion is that having some consistency between the option names and the docs is nicer. -- Michael signature.asc Description: PGP signature
clean up pg_checksums.sgml
PFA patch with minor improvements to documentation. Also, what do you think about changing user-facing language from "check checksum" to "verify checksum" ? I see that commit ed308d78 actually moved in the other direction, but I preferred "verify". >From d8e627cf340e5384d59ab4fc3f3d0b4891a5b1c0 Mon Sep 17 00:00:00 2001 From: Justin Pryzby Date: Thu, 28 Mar 2019 19:20:52 -0500 Subject: [PATCH] Clean up pg_checksums.sgml --- doc/src/sgml/ref/pg_checksums.sgml | 20 ++-- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/doc/src/sgml/ref/pg_checksums.sgml b/doc/src/sgml/ref/pg_checksums.sgml index c60695d..9433782 100644 --- a/doc/src/sgml/ref/pg_checksums.sgml +++ b/doc/src/sgml/ref/pg_checksums.sgml @@ -39,15 +39,16 @@ PostgreSQL documentation pg_checksums verifies, enables or disables data checksums in a PostgreSQL cluster. The server must be shut down cleanly before running - pg_checksums. The exit status is zero if there - are no checksum errors when checking them, and nonzero if at least one - checksum failure is detected. If enabling or disabling checksums, the + pg_checksums. When verifying checksums, the exit + status is zero if there are no checksum errors, and nonzero if at least one + checksum failure is detected. When enabling or disabling checksums, the exit status is nonzero if the operation failed. - While verifying or enabling checksums needs to scan or write every file in - the cluster, disabling checksums will only update the file + When verifying checksums, every file in the cluster is scanned; + When enabling checksums, every file in the cluster is also rewritten. + Disabling checksums only updates the file pg_control. @@ -195,11 +196,10 @@ PostgreSQL documentation safe. - If pg_checksums is aborted or killed while - enabling or disabling checksums, the cluster will keep the same - configuration for data checksums as before the operation attempted. - pg_checksums can be restarted to - attempt again the same operation. + If pg_checksums is aborted or killed + while enabling or disabling checksums, the cluster's checksum state + will be unchanged, and pg_checksums would need to + be rerun and start its operation from scratch. -- 2.1.4
