pg.ddx.io pgsql-hackers@postgresql.org mailing list archive
help / color / mirror / Atom feed[PATCH] Clean up pg_checksums.sgml
5+ messages / 3 participants
[nested] [flat]
Commits from this thread:
2019-04-08 e3865c3754 Tweak wording of documentation for pg_checksums
* [PATCH] Clean up pg_checksums.sgml
@ 2019-03-29 00:20 Justin Pryzby <pryzbyj@telsasoft.com>
0 siblings, 0 replies; 5+ messages in thread
From: Justin Pryzby @ 2019-03-29 00:20 UTC (permalink / raw)
---
doc/src/sgml/ref/pg_checksums.sgml | 18 +++++++++---------
1 file changed, 9 insertions(+), 9 deletions(-)
inline patch 1: doc/src/sgml/ref/pg_checksums.sgml (+9/-9 lines) download inline-1.patch
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
<application>pg_checksums</application> checks, enables or disables data
checksums in a <productname>PostgreSQL</productname> cluster. The server
must be shut down cleanly before running
- <application>pg_checksums</application>. 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
+ <application>pg_checksums</application>. 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.
</para>
<para>
- 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
<filename>pg_control</filename>.
</para>
</refsect1>
@@ -218,10 +219,9 @@ PostgreSQL documentation
</para>
<para>
If <application>pg_checksums</application> is aborted or killed while
- enabling or disabling checksums, the cluster will keep the same
- configuration for data checksums as before the operation attempted.
- <application>pg_checksums</application> can be restarted to
- attempt again the same operation.
+ enabling or disabling checksums, the cluster's checksum state will be
+ unchanged, and <application>pg_checksums</application> would need to be
+ rerun and start its operation from scratch.
</para>
</refsect1>
</refentry>
--
2.1.4
* clean up pg_checksums.sgml
@ 2019-03-29 14:32 Justin Pryzby <pryzby@telsasoft.com>
0 siblings, 1 reply; 5+ messages in thread
From: Justin Pryzby @ 2019-03-29 14:32 UTC (permalink / raw)
To: Michael Paquier <michael@paquier.xyz>; +Cc: pgsql-hackers
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".
Attachments:
0001-Clean-up-pg_checksums.sgml.patch (text/x-diff, 2.3K) download
From d8e627cf340e5384d59ab4fc3f3d0b4891a5b1c0 Mon Sep 17 00:00:00 2001
From: Justin Pryzby <pryzbyj@telsasoft.com>
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
<application>pg_checksums</application> verifies, enables or disables data
checksums in a <productname>PostgreSQL</productname> cluster. The server
must be shut down cleanly before running
- <application>pg_checksums</application>. 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
+ <application>pg_checksums</application>. 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.
</para>
<para>
- 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
<filename>pg_control</filename>.
</para>
</refsect1>
@@ -195,11 +196,10 @@ PostgreSQL documentation
safe.
</para>
<para>
- If <application>pg_checksums</application> is aborted or killed while
- enabling or disabling checksums, the cluster will keep the same
- configuration for data checksums as before the operation attempted.
- <application>pg_checksums</application> can be restarted to
- attempt again the same operation.
+ If <application>pg_checksums</application> is aborted or killed
+ while enabling or disabling checksums, the cluster's checksum state
+ will be unchanged, and <application>pg_checksums</application> would need to
+ be rerun and start its operation from scratch.
</para>
</refsect1>
</refentry>
--
2.1.4
* Re: clean up pg_checksums.sgml
@ 2019-03-30 01:51 Michael Paquier <michael@paquier.xyz>
parent: Justin Pryzby <pryzby@telsasoft.com>
0 siblings, 1 reply; 5+ messages in thread
From: Michael Paquier @ 2019-03-30 01:51 UTC (permalink / raw)
To: Justin Pryzby <pryzby@telsasoft.com>; +Cc: pgsql-hackers
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
Attachments:
signature.asc (application/pgp-signature, 832B) download
^ permalink raw reply [nested|flat] 5+ messages in thread
* Re: clean up pg_checksums.sgml
@ 2019-04-08 00:15 Justin Pryzby <pryzby@telsasoft.com>
parent: Michael Paquier <michael@paquier.xyz>
0 siblings, 1 reply; 5+ messages in thread
From: Justin Pryzby @ 2019-04-08 00:15 UTC (permalink / raw)
To: Michael Paquier <michael@paquier.xyz>; +Cc: pgsql-hackers
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.
Attachments:
0001-Clean-up-pg_checksums.sgml.patch (text/x-diff, 2.3K) download
From f151f8200c65f4a3ae61afe444f213e190e94013 Mon Sep 17 00:00:00 2001
From: Justin Pryzby <pryzbyj@telsasoft.com>
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
<application>pg_checksums</application> checks, enables or disables data
checksums in a <productname>PostgreSQL</productname> cluster. The server
must be shut down cleanly before running
- <application>pg_checksums</application>. 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
+ <application>pg_checksums</application>. 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.
</para>
<para>
- 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
<filename>pg_control</filename>.
</para>
</refsect1>
@@ -218,10 +219,9 @@ PostgreSQL documentation
</para>
<para>
If <application>pg_checksums</application> is aborted or killed while
- enabling or disabling checksums, the cluster will keep the same
- configuration for data checksums as before the operation attempted.
- <application>pg_checksums</application> can be restarted to
- attempt again the same operation.
+ enabling or disabling checksums, the cluster's checksum state will be
+ unchanged, and <application>pg_checksums</application> would need to be
+ rerun and start its operation from scratch.
</para>
</refsect1>
</refentry>
--
2.1.4
* Re: clean up pg_checksums.sgml
@ 2019-04-08 06:37 Michael Paquier <michael@paquier.xyz>
parent: Justin Pryzby <pryzby@telsasoft.com>
0 siblings, 0 replies; 5+ messages in thread
From: Michael Paquier @ 2019-04-08 06:37 UTC (permalink / raw)
To: Justin Pryzby <pryzby@telsasoft.com>; +Cc: pgsql-hackers
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
Attachments:
signature.asc (application/pgp-signature, 832B) download
^ permalink raw reply [nested|flat] 5+ messages in thread
end of thread, other threads:[~2019-04-08 06:37 UTC | newest]
Thread overview: 5+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2019-03-29 00:20 [PATCH] Clean up pg_checksums.sgml Justin Pryzby <pryzbyj@telsasoft.com>
2019-03-29 14:32 clean up pg_checksums.sgml Justin Pryzby <pryzby@telsasoft.com>
2019-03-30 01:51 ` Re: clean up pg_checksums.sgml Michael Paquier <michael@paquier.xyz>
2019-04-08 00:15 ` Re: clean up pg_checksums.sgml Justin Pryzby <pryzby@telsasoft.com>
2019-04-08 06:37 ` Re: clean up pg_checksums.sgml Michael Paquier <michael@paquier.xyz>
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox