public inbox for [email protected]
help / color / mirror / Atom feedUnsupported version mentioned at Using EXPLAIN
4+ messages / 3 participants
[nested] [flat]
* Unsupported version mentioned at Using EXPLAIN
@ 2021-05-07 09:04 [email protected] <[email protected]>
2021-05-07 14:24 ` Re: Unsupported version mentioned at Using EXPLAIN Alvaro Herrera <[email protected]>
0 siblings, 1 reply; 4+ messages in thread
From: [email protected] @ 2021-05-07 09:04 UTC (permalink / raw)
To: [email protected] <[email protected]>
Hi
When referring Doc, found one place mentioned "using 9.3 development sources." at [1]. Which I think 9.3 means PG9.3
[1]
https://www.postgresql.org/docs/current/using-explain.html
It seems to show up since PG9.2 and changed to 9.3 at PG9.3. However, since 9.3 nobody updates the version anymore.
Maybe we can just remove the specific PG version. Say "using current development sources." Thoughts?
Regards,
Tang
^ permalink raw reply [nested|flat] 4+ messages in thread
* Re: Unsupported version mentioned at Using EXPLAIN
2021-05-07 09:04 Unsupported version mentioned at Using EXPLAIN [email protected] <[email protected]>
@ 2021-05-07 14:24 ` Alvaro Herrera <[email protected]>
2021-05-07 14:43 ` Re: Unsupported version mentioned at Using EXPLAIN Tom Lane <[email protected]>
0 siblings, 1 reply; 4+ messages in thread
From: Alvaro Herrera @ 2021-05-07 14:24 UTC (permalink / raw)
To: [email protected] <[email protected]>; +Cc: [email protected] <[email protected]>
On 2021-May-07, [email protected] wrote:
> Hi
>
> When referring Doc, found one place mentioned "using 9.3 development sources." at [1]. Which I think 9.3 means PG9.3
>
> [1]
> https://www.postgresql.org/docs/current/using-explain.html
>
> It seems to show up since PG9.2 and changed to 9.3 at PG9.3. However, since 9.3 nobody updates the version anymore.
> Maybe we can just remove the specific PG version. Say "using current development sources." Thoughts?
I think there's more to this than just changing or removing the version
number; a better approach might be to update the documentation so that
it matches what current versions do. There are minor changes here and
there and it'd be sad to let it all drift too much from current reality.
The estimated cost for the very first EXPLAIN is different in current
sources from what the docs say, for example; there's also one example
that the docs show to produce an incremental sort, but didn't in my
hands; and there's one additional line in the first EXPLAIN ANALYZE
output (BitmapHeapScans now show number of heap blocks processed). I
didn't try to run everything but I suggest we need a little bit of effort.
If we just removed the version number, we'd falsify the examples. I
think we should update both in unison. Make it say "Using 14
development sources ..." and make sure to use the output from the
current version, then recheck again in a few years. It is good to keep
these updated as new plan types are added so that everything is covered.
--
Álvaro Herrera Valdivia, Chile
^ permalink raw reply [nested|flat] 4+ messages in thread
* Re: Unsupported version mentioned at Using EXPLAIN
2021-05-07 09:04 Unsupported version mentioned at Using EXPLAIN [email protected] <[email protected]>
2021-05-07 14:24 ` Re: Unsupported version mentioned at Using EXPLAIN Alvaro Herrera <[email protected]>
@ 2021-05-07 14:43 ` Tom Lane <[email protected]>
2021-05-07 15:34 ` RE: Unsupported version mentioned at Using EXPLAIN [email protected] <[email protected]>
0 siblings, 1 reply; 4+ messages in thread
From: Tom Lane @ 2021-05-07 14:43 UTC (permalink / raw)
To: Alvaro Herrera <[email protected]>; +Cc: [email protected] <[email protected]>; [email protected] <[email protected]>
Alvaro Herrera <[email protected]> writes:
> On 2021-May-07, [email protected] wrote:
>> Maybe we can just remove the specific PG version. Say "using current development sources." Thoughts?
> I think there's more to this than just changing or removing the version
> number; a better approach might be to update the documentation so that
> it matches what current versions do.
Yeah. The reason why a specific version is mentioned is exactly that
the details tend to change. I don't know if anyone else has touched
that text, but when I've done so it's been exactly the sort of effort
you mention: run through all the examples in that file and make them
match current reality. I don't think just taking out the version
number is a good idea.
regards, tom lane
^ permalink raw reply [nested|flat] 4+ messages in thread
* RE: Unsupported version mentioned at Using EXPLAIN
2021-05-07 09:04 Unsupported version mentioned at Using EXPLAIN [email protected] <[email protected]>
2021-05-07 14:24 ` Re: Unsupported version mentioned at Using EXPLAIN Alvaro Herrera <[email protected]>
2021-05-07 14:43 ` Re: Unsupported version mentioned at Using EXPLAIN Tom Lane <[email protected]>
@ 2021-05-07 15:34 ` [email protected] <[email protected]>
0 siblings, 0 replies; 4+ messages in thread
From: [email protected] @ 2021-05-07 15:34 UTC (permalink / raw)
To: Tom Lane <[email protected]>; Alvaro Herrera <[email protected]>; +Cc: [email protected] <[email protected]>
Tom Lane <[email protected]> wrote:
> On 2021-May-07, Alvaro Herrera <[email protected]> wrote:
>> I think there's more to this than just changing or removing the version
>> number; a better approach might be to update the documentation so that
>> it matches what current versions do.
>Yeah. The reason why a specific version is mentioned is exactly that
>the details tend to change.
Thanks for your kindly explanation on the usage of version number in Doc.
In fact, I noticed the different context in the examples among different PG version like "increment sort" which was newly introduced in PG13.
The fix I mentioned at the previous mail(change "using 9.3 development sources" to " using current development sources") is meant to tell users to refer to the "current" PG source. E.G. when a user looks at PG13.2's doc, "current" = PG13.2.
Since I do think your advice on the fix is more reasonable and friendly, I followed your hint to modify the Doc in the attached patch.
Please tell me if there's anything else insufficient.
Regards,
Tang
Attachments:
[application/octet-stream] 0001-Using-current-version-in-Using-EXPLAIN-Doc.patch (907B, 2-0001-Using-current-version-in-Using-EXPLAIN-Doc.patch)
download | inline diff:
From cad86e591368eccdce3270f3d4b99776d08c5c47 Mon Sep 17 00:00:00 2001
From: tanghy <[email protected]>
Date: Sat, 8 May 2021 00:14:50 +0900
Subject: [PATCH] Using current version in Using EXPLAIN Doc
diff --git a/doc/src/sgml/perform.sgml b/doc/src/sgml/perform.sgml
index 89ff58338e..d8d7b14301 100644
--- a/doc/src/sgml/perform.sgml
+++ b/doc/src/sgml/perform.sgml
@@ -39,7 +39,7 @@
<para>
Examples in this section are drawn from the regression test database
- after doing a <command>VACUUM ANALYZE</command>, using 9.3 development sources.
+ after doing a <command>VACUUM ANALYZE</command>, using &version; development sources.
You should be able to get similar results if you try the examples
yourself, but your estimated costs and row counts might vary slightly
because <command>ANALYZE</command>'s statistics are random samples rather
--
2.30.0.windows.2
^ permalink raw reply [nested|flat] 4+ messages in thread
end of thread, other threads:[~2021-05-07 15:34 UTC | newest]
Thread overview: 4+ messages (download: mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2021-05-07 09:04 Unsupported version mentioned at Using EXPLAIN [email protected] <[email protected]>
2021-05-07 14:24 ` Alvaro Herrera <[email protected]>
2021-05-07 14:43 ` Tom Lane <[email protected]>
2021-05-07 15:34 ` [email protected] <[email protected]>
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox