The use "Postgres" in docs
The docs use PostgreSQL and not Postgres in all but two places, which I think we should change like in the attached to be consistent. Any objections to this? -- Daniel Gustafsson postgres_title.diff Description: Binary data
Re: The use "Postgres" in docs
> On 14 Mar 2023, at 13:55, Jonathan S. Katz wrote: > > On 3/14/23 7:31 AM, Alvaro Herrera wrote: >> On 2023-Mar-14, Daniel Gustafsson wrote: >>> The docs use PostgreSQL and not Postgres in all but two places, which I >>> think >>> we should change like in the attached to be consistent. Any objections to >>> this? >> Both are very new. No objection to the change. > > +1 -- good catch. Applied, thanks! -- Daniel Gustafsson
Re: Mistake in documentation (PG15+)
> On 24 Mar 2023, at 11:26, PG Doc comments form wrote: > But the correct range here would be from -99499 to 99499: > > select 99499::NUMERIC(2, -3); I'm not sure I see the error you indicate, numeric(2,-3) gives the range indicated in the documentation: postgres=# select -99499::numeric(2, -3) as neg, 99499::numeric(2, -3) as pos; neg | pos +--- -99000 | 99000 (1 row) -- Daniel Gustafsson
Re: Misleading "For more information..." placement
> On 25 Mar 2023, at 16:43, PG Doc comments form wrote:
> The final sentence ("For more information refer to Section 24.3") is easily
> read to refer to more information being available about character code zero
> (NUL). However, section 24.3 has no mention of NUL, but rather the
> available database character sets. I'd suggest moving that last sentence to
> immediately after the first sentence, which ends with "...when the database
> is created."
I think sentence with the link is better at the end, how about if we reword it
slightly to something like this to make it clearer?
"For more information on character sets refer to Section 24.3"
> A really minor point, but it caught me off-guard.
In Postgres we excel at caring about minor points, so thanks for your report!
--
Daniel Gustafsson
Re: Misleading "For more information..." placement
> On 27 Mar 2023, at 17:04, Randall Sindlinger wrote: > Fantastic! I'm rather used to things just going off into the ether. > I know I've > seen minor things before, so next time I notice one, I'll send it in. Please do, postgres is made by the community and no report is too small to be valuable. -- Daniel Gustafsson
Re: Minor typo in 13.3.5. Advisory Locks
> On 28 Mar 2023, at 22:45, Tom Lane wrote: > > PG Doc comments form writes: >> Page: https://www.postgresql.org/docs/15/explicit-locking.html > >> After the code snippet in the 6th paragraph of 13.3.5. Advisory Locks >> (https://www.postgresql.org/docs/current/explicit-locking.html#ADVISORY-LOCKS) >> I believe there is a mistake in this sentence (I've surrounded it with >> asterisks): > >> "In the above queries, the second *form* is dangerous because the >> LIMIT...". > >> I believe that "form" in the above sentence is actually meant to be "from", >> referencing the second line of code and its FROM clause in the snippet. > > No, I think "form" is exactly what was meant. Agreed, I think that was the indended spelling. > Maybe we should have said "second query" or something like that, though. Reading this section I agree that the mix of ok/danger in the same example can be tad misleading though. Something like the attached is what I would prefer as a reader. -- Daniel Gustafsson adv_lock_limit.diff Description: Binary data
Re: Minor typo in 13.3.5. Advisory Locks
> On 31 Mar 2023, at 14:35, Tom Lane wrote: > > Daniel Gustafsson writes: >> Reading this section I agree that the mix of ok/danger in the same example >> can >> be tad misleading though. Something like the attached is what I would prefer >> as a reader. > > I think in your rewrite, "this query" is dangling a bit because there's > several sentences more before the query actually appears. I suggest > ordering things more like: > > expressions are evaluated. For example, > this query is dangerous because the > LIMIT is not guaranteed to be applied before the > locking > function is executed: > > SELECT pg_advisory_lock(id) FROM foo WHERE id > 12345 LIMIT 100; -- danger! > > This might cause some locks to be acquired > that the application was not expecting, and hence would fail to > ... > On the other hand, these queries are safe: > > SELECT pg_advisory_lock(id) FROM foo WHERE id = 12345; -- ok > ... Yes, I like this version a lot better than what I proposed. > Separately from that: now that I look at this example, it's really > quite safe for any plausible plan shape. It used to be dangerous if > you had an ORDER BY, but there's no ORDER BY, and even if there were > we fixed that in 9118d03a8. Do we want to choose another example, and > if so what? The "not guaranteed" wording isn't really wrong, but an > example that doesn't do what we're saying it does isn't good either. Off the cuff I don't have any better suggestions, need to do some more thinking. -- Daniel Gustafsson
Re: Should 'sum(mvf)' read 'sum(mcv)'...?
> On 22 Aug 2022, at 14:58, Tom Lane wrote: > > Julien Rouhaud writes: >> On Sun, Aug 21, 2022 at 11:02:04PM +, PG Doc comments form wrote: >>> It appears the above sentence is referring to the "(1 - sum(mvf))" portion >>> of the formula, however I am not sure what "mvf" is referring to >>> there...shouldn't it be "(1 - sum(mcv))" in order to match what the >>> explanatory sentence is saying? > >> It should be mcf, ie. Most Common Frequencies. It looks like a very old typo >> that survived until now. > > I don't think it's a typo exactly, but an odd abbreviation for "Most > common Values' Frequencies". (Summing the MCVs themselves isn't > sensible; they might not even be numeric.) > > I'd vote for replacing mvf in both places with something a bit more > spelled-out, perhaps "mcv_freqs". I was inclined to spell it out as mcv_frequencies but we use xxx_freqs elsewhere on the same page so keeping it consistent seems better. The attached does this as well as adding mcf/mcv as acronyms as previously mentioned (since they are both tagged as ). -- Daniel Gustafsson mcf_mcv.diff Description: Binary data
Re: Should 'sum(mvf)' read 'sum(mcv)'...?
> On 12 Apr 2023, at 14:14, Tom Lane wrote:
>
> Daniel Gustafsson writes:
>> I was inclined to spell it out as mcv_frequencies but we use xxx_freqs
>> elsewhere on the same page so keeping it consistent seems better. The
>> attached
>> does this as well as adding mcf/mcv as acronyms as previously mentioned
>> (since
>> they are both tagged as ).
>
> mcv_freqs looks good. I'd write the glossary entries as singular
> (Most Common Frequency, Most Common Value) since our typical usage
> is to pluralize them at the point of use ("MCVs"). Also, just
> expanding the acronym doesn't seem that helpful. Maybe more like
Pushed with your suggested changes, thanks!
--
Daniel Gustafsson
Re: confusing positioning of notes in connection settings
> On 26 Apr 2023, at 08:08, Peter Eisentraut > wrote: > I wonder if the notes are even true. The text for tcp_keepalives_interval > already says that it is only supported if TCP_KEEPCNT is supported. Don't forget the "and on Windows;" part. > There is no specific code for Windows. We have pq_setkeepaliveswin32() for Windows which can work on Windows 2000 and later versions based on the existence of SIO_KEEPALIVE_VALS. > Random googling suggests that TCP_KEEPCNT does exist on Windows. For Windows what you want is SIO_KEEPALIVE_VALS. -- Daniel Gustafsson
Re: confusing positioning of notes in connection settings
> On 26 Apr 2023, at 10:18, Daniel Gustafsson wrote: > >> On 26 Apr 2023, at 08:08, Peter Eisentraut >> wrote: > >> I wonder if the notes are even true. The text for tcp_keepalives_interval >> already says that it is only supported if TCP_KEEPCNT is supported. Re-reading this I think there was some confusion, definitely so on my part. tcp_keepalives_interval relies on TCP_KEEPINTVL, with the Windows equivalent being SIO_KEEPALIVE_VALS. TCP_KEEPCNT is for tcp_keepalives_count which indeed is not supported on Windows. Jonathans original question was regarding _count and _timeout and not _interval. I do agree that all of these notes may just as well be added to the text, the option client_connection_check_interval following these have text about platform compatibility without using a note. -- Daniel Gustafsson
Re: some new glossary entries
> On 2 May 2023, at 09:05, Peter Eisentraut > wrote: > > I wrote glossary entries for some terms I wanted to look up there but didn't > find: "restartpoint" and "LSN". I put this together based on existing text. > "LSN" was already in the acronyms list but I think it's more appropriate in > the glossary, so I moved things around a bit. +1 LGTM. + + LSN + + The other entries doesn't have a glossentry id attribute set, is the use here related to the glossentry.show.acronym param? -- Daniel Gustafsson
Re: some new glossary entries
> On 2 May 2023, at 12:24, Alvaro Herrera wrote: > > On 2023-May-02, Daniel Gustafsson wrote: > >> + >> + LSN >> + >> + >> >> The other entries doesn't have a glossentry id >> attribute set, is the use here related to the glossentry.show.acronym param? > > I debated with myself for 347d2b07fcc2 on whether to add id attribs to > entries. The only saving grace for doing that is that you > can link to such entries; but if you do that, you're only causing the > user one more click in order to see the definition they want to see. So > in the end I decided not make the glosssee's directly referenceable. > And I think this new entry shouldn't have an id either. Agreed, that makes sense. > I think that what glossentry.show.acronym allows is to show the > text that's part of the main entry: > https://stackoverflow.com/questions/28869578/docbook-5-rendering-without-abbrev-tag/28879785#28879785 > so the fact that there's an id in the other entry doesn't change > anything. > > If we do turn glossentry.show.acronym on (and I don't see any reason not > to), we can follow up later to add and tags to other > entries, too. +1 -- Daniel Gustafsson
Re: Incorrect link tohttps://www.postgresql.org/docs/current/indexes-functional.html ?
> On 5 May 2023, at 13:03, Tom Lane wrote: > > PG Doc comments form writes: >> I found incorrect link to >> https://www.postgresql.org/docs/current/indexes-functional.html on this page >> https://www.postgresql.org/docs/7.3/indexes-functional.html. > > PG 7.3 has been out of support for more than fifteen years. Nobody > is going to correct any errors that may exist in those doc pages. > They're just there for historical reference. This is actually not an error in the 7.3 docs (which we clearly wouldn't address) but an error in pgweb in the warning for unsupported versions; it assumes it can link to the same page in /current. The relevant code is: This documentation is for an unsupported version of PostgreSQL. You may want to view the same page for the current This may well hit us in just-out-of-support versions which are still in use, but until there is a report from a more recent version than 7.3 there isn't much cause for concern I reckon. -- Daniel Gustafsson
Re: Incorrect link tohttps://www.postgresql.org/docs/current/indexes-functional.html ?
> On 5 May 2023, at 15:42, Tom Lane wrote: > > Daniel Gustafsson writes: >> This is actually not an error in the 7.3 docs (which we clearly wouldn't >> address) but an error in pgweb in the warning for unsupported versions; it >> assumes it can link to the same page in /current. > > Ah, good point. And it does know that the page doesn't exist in /current, > because the "same page in other versions" list just above doesn't include > that. Maybe we could have the link to "current" point to the docs top > level instead of the specific page in such cases? Or simpler, just omit > the "You may want to view the same page..." sentence altogether. Since this particular page doesn't exist in any supported version, the text in the box is actually wrong twice: "You may want to view the same page for the current version, or one of the other supported versions listed above instead." Since we know when rendering the page which versions it does exist in we could set one of three template variables: exist_in_current exist_in_supported exist_in_unsupported Depending on which is set we can choose the right text for the box. That being said, we should probably move this to -www for exposure among those who actually know the pgweb backend. -- Daniel Gustafsson
Re: tables on pgbench man page look garbled
> On 9 May 2023, at 15:40, Peter Eisentraut > wrote: > > The tables "pgbench Operators" and "pgbench Functions" on the pgbench man > page (the actual man page, not the HTML reference page) look pretty garbled. > Also, on macOS, man prints a warning that the page is invalidly formatted. > But the garbledness happens on Linux as well, for example. Apparently, our > custom table layout doesn't map properly to the man format. But for example, > the earlier table "pgbench Automatic Variables", which doesn't use the custom > table layout, looks fine. Anyone feel like looking into this further? Can you post a screenshot of what it looks like? I just built the manpages from HEAD on macOS and while they report the UNSUPP error the table itself looks like I would expect it to. -- Daniel Gustafsson
Re: tables on pgbench man page look garbled
> On 9 May 2023, at 17:14, Peter Eisentraut
> wrote:
> Note that formatting instructions (".PP") show in the output.
I took a look at this using macOS as the initial testbed; the TLDR is that
mandoc doesn't support macros in tables, and our single-column function
signature tables rely on that. macOS switched to mandoc in v11 I think, but I
don't have an older box handy to doublecheck.
Each row in the table is currently emitted like this:
T{
.PP
\fIboolean\fR
IS [NOT] (NULL|TRUE|FALSE)
→ \fIboolean\fR
.PP
Boolean value tests
.PP
1 is null
→ FALSE
T}
The .PP rendered in the output comes from the macro being indented from column
zero in the man page, the .PP macro on column zero is removed during rendering
and cause the UNSUPP warning.
Adding a rule in stylesheet-man.xsl to remove row/entry/para makes the manpages
render without warning, and the tables are no longer garbled. The attached PoC
diff is what I used for this.
That being said, the output is still not very good since T{T} text blocks are
not rendered with implicit newlines, all content is rendered on a single line
with whitespace intact but newlines stripped. This is mainly a problem for our
new-style function tables which use vertical whitespace for separation rather
than columns, but it also affects regular tables like the backslash sequence on
COPY(7) which is rendered like this:
"Backslash x followed by one or two hex digits specifiesthe byte
with that numeric code"
The whitespace gap in the output comes from a linebreak and indentation in the
source file.
The amount of whitespace can to some degree be controlled to some degree by
refactoring the indentation in pgbench.sgml file, but that seems like quite the
nightmare to maintain.
Not sure what the best path going forward is, relying on in-column formatting
for tables seems problematic when mandoc is used.
--
Daniel Gustafsson
mandoc_para_tbl.diff
Description: Binary data
Re: tables on pgbench man page look garbled
> On 10 May 2023, at 17:35, Tom Lane wrote:
>
> Daniel Gustafsson writes:
>> I took a look at this using macOS as the initial testbed; the TLDR is that
>> mandoc doesn't support macros in tables, and our single-column function
>> signature tables rely on that. macOS switched to mandoc in v11 I think, but
>> I
>> don't have an older box handy to doublecheck.
>
> Hmm, any chance of addressing this by expanding out the relevant macros?
Maybe, but I'm not too optimistic about that since I was unable to coerce
mandoc into accepting any form of explicit linebreaks in T{T} text blocks.
--
Daniel Gustafsson
Re: tables on pgbench man page look garbled
> On 10 May 2023, at 22:08, Daniel Gustafsson wrote:
>
>> On 10 May 2023, at 17:35, Tom Lane wrote:
>>
>> Daniel Gustafsson writes:
>>> I took a look at this using macOS as the initial testbed; the TLDR is that
>>> mandoc doesn't support macros in tables, and our single-column function
>>> signature tables rely on that. macOS switched to mandoc in v11 I think,
>>> but I
>>> don't have an older box handy to doublecheck.
>>
>> Hmm, any chance of addressing this by expanding out the relevant macros?
>
> Maybe, but I'm not too optimistic about that since I was unable to coerce
> mandoc into accepting any form of explicit linebreaks in T{T} text blocks.
Having spent some more time on this I've been unsuccessful in getting anything
to look better than the originally proposed diff upthread; which is far from
good but a) better than the current garbled output and b) fixes the warnings
from mandoc. Not sure how to make progress on this.
--
Daniel Gustafsson
Re: confusing positioning of notes in connection settings
> On 31 May 2023, at 13:16, Peter Eisentraut > wrote: > The first two hunks are pretty straightforward, they just move the existing > text around. > > For the other two, which are not supported on Windows, I added an explicit > parenthetical note. We don't list which of the Unix-like platforms support > the respective options, but I suspect that it's all of them in practice? > (Otherwise we should be more explicit.) So I think calling out Windows > explicitly is sensible, also considering that the first two settings are > supported on Windows but the latter two are not. I think this is a clear improvement over the current docs. Should we call out Windows explicitly in the same way in the corresponding options in the libpq connection string param docs as well? -- Daniel Gustafsson
Re: confusing positioning of notes in connection settings
> On 5 Jun 2023, at 19:10, Jonathan S. Katz wrote: > "It is only supported on systems where TCP_USER_TIMEOUT is available; on > other systems, it has no effect." > > If this is really only unsupported / has different settings on Windows, I > think it's OK to call that out. The original gripe was about readability, but > if we think the description in the other settings is no clear enough, we can > edit it. TCP_USER_TIMEOUT is not widely available, AFAIK FreeBSD, OpenBSD and macOS do not support it yet. -- Daniel Gustafsson
Re: Move --interactive in createuser.sgml?
> On 4 Jul 2023, at 09:58, Ekaterina Kiryanova > wrote: > I noticed that the --interactive option in createuser.sgml is in the list of > short options rather than in the list of the long ones later on. > If it makes sense to move it below, the attached patch fixes that for master > (after --bypassrls/--no-bypassrls). > Please take a look. I'm not sure this moves the needle much in terms of consistency in listing options, and I'm not sure there is policy to follow. createdb has long options in alphabetical order, pg_basebackup has long options both by alphabetical and grouped last, and pg_amcheck groups options by type. Whether or not an option has a short option as well as a long option is an implementation detail that I don't think should drive how we present the information to the users in order to help them find what they need. -- Daniel Gustafsson
Clarify errhint in sources.sgml
It was noted in 20230712015948.byqaftt57glwk...@awork3.anarazel.de that the errhint example in sources.sgml isn't as helpful as it could be. errhint should use a complete sentence, but the example doesn't, so I propose the attached change which makes it so. The style for hints is clearly spelled out further down on the page, but for anyone looking for a quick answer and not reading the whole page the current example might be misleading. -- Daniel Gustafsson errhint_example.diff Description: Binary data
Re: Clarify errhint in sources.sgml
> On 12 Jul 2023, at 15:30, Jonathan S. Katz wrote: > > On 7/12/23 3:08 AM, Daniel Gustafsson wrote: >> It was noted in 20230712015948.byqaftt57glwk...@awork3.anarazel.de that the >> errhint example in sources.sgml isn't as helpful as it could be. errhint >> should use a complete sentence, but the example doesn't, so I propose the >> attached change which makes it so. The style for hints is clearly spelled >> out >> further down on the page, but for anyone looking for a quick answer and not >> reading the whole page the current example might be misleading. > > +1. No need to bikeshed this one. Thanks for review, I'll go make that happen then in a bit unless anyone else objects. -- Daniel Gustafsson
Re: [PATCH] fix dead link to Homebrew
> On 14 Jul 2023, at 14:22, Niels Bom wrote: > I found a dead link on this page: https://www.postgresql.org/download/macosx/ Thanks for your report! This was recently reported by someone else as well and we’re currently discussing on the -www mailinglist on how to address it best. ./daniel
Re: Include PostgresNIO Swift client in the Documentation
> On 11 Aug 2023, at 02:23, Jonathan S. Katz wrote: > The last time this came up, I think we discussed linking to the wiki page > from the docs, vs. trying to keep the docs up-to-date with all of the drivers > available. Perhaps it's worth seeing if we want to make any changes to the > docs page prior to the v16 GA? The docs page does mention that the list is likely to be incomplete, with the following sentence, but there is no mention of the Wiki page at all: "Table H.1 includes a list of some of these projects." That being said, a lot of readers will likely skim over and immediately look at the table, missing the small disclaimer. I wonder if we aren't serving our users better by removing the table and only referring to the Wiki page? Having two lists will prompt the discussion of what to include where over and over again, which isn't helping anyone. -- Daniel Gustafsson
Re: In docs there is no "Installation from Binaries" section
> On 20 Aug 2023, at 18:52, David G. Johnston > wrote: > On Sun, Aug 20, 2023 at 8:56 AM PG Doc comments form <mailto:nore...@postgresql.org>> wrote: > Installing software from ZIP archive is a common practice, pgsql provides > such archive, but doesn't provide instructions on what to do with it. > > Where are you seeing such a zip archive? I'm familiar with us producing tar > gzip archives of the source code for compiling, but we don't produce binaries > that I know of. > > https://www.postgresql.org/docs/current/install-getsource.html > <https://www.postgresql.org/docs/current/install-getsource.html> The Windows and macOS installers provided by EDB are also available as ZIP archives of the binaries, these might be ones referred to? We have the below on the website: "Advanced users can also download a zip archive of the binaries, without the installer. This download is intended for users who wish to include PostgreSQL as part of another application installer." That being said, since the installer and ZIP archives are provided by a third- party I don't think we should attempt to describe them in more detail than what we currently do. -- Daniel Gustafsson
Re: Include PostgresNIO Swift client in the Documentation
> On 22 Aug 2023, at 05:23, Jonathan S. Katz wrote: > > On 8/21/23 10:55 AM, Jonathan S. Katz wrote: >> On 8/21/23 7:58 AM, Daniel Gustafsson wrote: >>>> On 11 Aug 2023, at 02:23, Jonathan S. Katz wrote: >>> >>>> The last time this came up, I think we discussed linking to the wiki page >>>> from the docs, vs. trying to keep the docs up-to-date with all of the >>>> drivers available. Perhaps it's worth seeing if we want to make any >>>> changes to the docs page prior to the v16 GA? >>> >>> The docs page does mention that the list is likely to be incomplete, with >>> the >>> following sentence, but there is no mention of the Wiki page at all: >>> >>> "Table H.1 includes a list of some of these projects." >>> >>> That being said, a lot of readers will likely skim over and immediately >>> look at >>> the table, missing the small disclaimer. I wonder if we aren't serving our >>> users better by removing the table and only referring to the Wiki page? >>> Having >>> two lists will prompt the discussion of what to include where over and over >>> again, which isn't helping anyone. >> This is what I was saying. I was waiting on attempting a patch to see if >> there was consensus. There's now a couple of threads now with similar >> suggestions, I'll work on getting patches ready. > > Suggested patch attached. Notes: > > 1. Replaced language to reference the wiki page > 2. Replaced table with the URL > 3. Changed the "licenses" comment to be more affirmative, i.e., there are > language interfaces that are released under licenses different than the > PostgreSQL Licence. This is in line with what I imagined as well, so unless anyone thinks otherwise I will apply this and backpatch it to all branches. -- Daniel Gustafsson
Re: Include rust as an externally maintained procedural language
> On 22 Aug 2023, at 05:35, Jonathan S. Katz wrote: > > On 8/12/23 12:45 PM, Bruce Momjian wrote: >> On Fri, Aug 11, 2023 at 05:05:48PM -0400, Jonathan Katz wrote: >>> On 8/11/23 2:46 PM, PG Doc comments form wrote: > >>>> Considering the increasing support and stability for PL/Rust, it should be >>>> referenced within Postgresql's docs [1]. >>> >>> There's an up-to-date list of the different PL's in on this page in the >>> wiki: >>> >>> https://wiki.postgresql.org/wiki/PL_Matrix >>> >>> Similar to this thread[1], I wonder if we just link to the wiki from the >>> documentation, given it will be easier to maintain the list from there. >> Makes sense. > > Please see attached patch that does exactly this. It follows similar > semantics as [1]. LGTM, let's apply it along with the patch in [1] to all branches. -- Daniel Gustafsson
Re: Include PostgresNIO Swift client in the Documentation
> On 22 Aug 2023, at 16:25, Jonathan S. Katz wrote: > > On 8/22/23 3:10 AM, Daniel Gustafsson wrote: > >> This is in line with what I imagined as well, so unless anyone thinks >> otherwise >> I will apply this and backpatch it to all branches. > > I could argue it both ways on whether or not to backpatch. However, given the > list of drivers should work with all supported PG releases, and it expands on > the current known list, I'd +1 backpatching. I opted for backpatching as the table is equally incomplete for all branches, and the wiki equally applicable. -- Daniel Gustafsson
Re: file-fdw and force_null
> On 11 Sep 2023, at 16:28, Boshomi Phenix wrote: > I tried to create a file-fdw foreign table with force_null for some columns. > FORCE_NULL syntax differs from COPY. For me it was not clear that the > "OPTIONS" keyword by the column was necessary, so it would be nice to add > this to the example. Considering that we don't really have the OPTIONS syntax documented in an example, and that we reference COPY heavily on this page, I tend to agree. How about the attached? Looking at this it's a bit odd that we use here which is very infrequently used. It might be worth replacing this to make the docs more uniform, but that's for another patch (and thread), for now it's using the same syntax already present here. -- Daniel Gustafsson file_fdw_options.diff Description: Binary data
Re: file-fdw and force_null
> On 13 Sep 2023, at 22:10, Boshomi Phenix wrote: > > Am Di., 12. Sept. 2023 um 12:25 Uhr schrieb Daniel Gustafsson > mailto:dan...@yesql.se>>: > > Considering that we don't really have the OPTIONS syntax documented in an > example, and that we reference COPY heavily on this page, I tend to agree. > How about the attached? > > Yes, this looks good to me. I've applied this today, thanks for the report. -- Daniel Gustafsson
Re: Typo/wording on https://www.postgresql.org/docs/current/catalog-pg-class.html
> On 20 Sep 2023, at 07:23, PG Doc comments form wrote: > > The following documentation comment has been logged on the website: > > Page: https://www.postgresql.org/docs/16/catalog-pg-class.html > Description: > > I've just read this: > > "catalogs tables and most everything else that has columns or is otherwise > similar to a table" > > It seems that it should be: > > "catalogs tables and almost everything else that has columns or is otherwise > similar to a table" > > So, "most" becomes "almost". While I'm not a native english speaker I do believe this wording is correct (although I guess your version would be semantically the same or very close to it). It was done in commit 83501ef4ca some 20+ years ago. -- Daniel Gustafsson
Re: Typo/wording on https://www.postgresql.org/docs/current/catalog-pg-class.html
> On 22 Sep 2023, at 19:04, Tom Lane wrote: > > I wrote: >> "Most" here is good English, although I concede it's a slightly >> old-fashioned usage. Maybe it'd be clearer to just remove the >> word altogether. > >> If we were going to touch this sentence I'd worry about some other >> things too. Use of "catalogs" as a verb is probably not the greatest >> choice right here, since one could easily think that the verb is >> missing and what was meant was "pg_class lists catalogs, [user] >> tables, and ...". Also, I think that the reference to special >> relations is obsolete --- we don't list any relkind for that anymore. >> What probably does deserve to be called out in place of those is >> composite types, since their appearance in pg_class might be pretty >> surprising to newbies. > > Hmm, I must have been looking at some old version of the docs, because > when I went to prepare a draft patch I found that those last couple of > points were addressed some time ago. I think we just need some slightly > better wording here rather than any change of technical content. > I propose the attached. (I also modified the para's last sentence to > speak of "kind" not "type", for consistency with the relkind field name > and the rest of the para.) LGTM. -- Daniel Gustafsson
Hyperlinks for source file references
Commit b73c3a11963 introduced xyz hyperlinks for files in the postgres source tree by linking to the gitweb interface at git.postgresql.org. This, IMO, makes the content referred to more accessible, and is especially interesting for README files. The links in question can be found here: https://www.postgresql.org/docs/devel/tableam.html Right now we have ~85 references to source files using in the docs, should we convert them to hyperlinks like the ones in the Table AM docs? I would be happy to make a patch that implements this, but I wanted to check here before making the effort to make sure it's not immediately nayed. This does of course present a question for the backbranches, pointing to the HEAD version in the docs for a previous major release isn't entirely accurate. On the other hand, we already do that today in the above tableam page so if we don't like that we might as well sort out now what to do about that. -- Daniel Gustafsson
Re: Hyperlinks for source file references
> On 25 Sep 2023, at 14:22, Alvaro Herrera wrote: > > On 2023-Sep-25, Daniel Gustafsson wrote: > >> This does of course present a question for the backbranches, pointing to the >> HEAD version in the docs for a previous major release isn't entirely >> accurate. >> On the other hand, we already do that today in the above tableam page so if >> we >> don't like that we might as well sort out now what to do about that. > > I think you can just change the ;hb=HEAD parameter in the URL to the > current branch. > > https://git.postgresql.org/gitweb/?p=postgresql.git;a=blob;f=src/include/access/tableam.h;hb=REL_12_STABLE > https://git.postgresql.org/gitweb/?p=postgresql.git;a=blob;f=src/include/access/tableam.h;hb=master > > It should be easy to add a line to version.sgml that expands to the > current branch. That's a good idea, it would remove any backpatching issues since all links would be hb=&gitbranch; -- Daniel Gustafsson
Re: pg_upgrade doc uses inconsistent versions within the doc.
> On 26 Sep 2023, at 22:26, Bruce Momjian wrote: > On Tue, Sep 26, 2023 at 10:56:27AM -0700, David G. Johnston wrote: >> I would get rid of any mentions of our old pre-v10 versioning scheme in the >> current documentation. For content such as this, a very big +1. > Good point, how is this attached patch? LGTM. -- Daniel Gustafsson
Re: Hyperlinks for source file references
> On 27 Sep 2023, at 15:18, Peter Eisentraut wrote: > > On 25.09.23 13:09, Daniel Gustafsson wrote: >> Commit b73c3a11963 introduced xyz >> hyperlinks for files in the postgres source tree by linking to the gitweb >> interface at git.postgresql.org. This, IMO, makes the content referred to >> more >> accessible, and is especially interesting for README files. The links in >> question can be found here: >> https://www.postgresql.org/docs/devel/tableam.html >> Right now we have ~85 references to source files using in the >> docs, should we convert them to hyperlinks like the ones in the Table AM >> docs? >> I would be happy to make a patch that implements this, but I wanted to check >> here before making the effort to make sure it's not immediately nayed. > > A slightly fancier variant that avoids having to hardcode the git web URL > pattern in a bunch of places: > > You mark it up like > > > > and then write a bit of XSL to process that into whatever form you want. Ah yes, thats a neater version. Since noone objected to the idea I will go hack up an attempt at this to share. -- Daniel Gustafsson
Re: Typo in PL/pgSQL trigger Example 43.4?
> On 7 Oct 2023, at 22:22, Tom Lane wrote: > > "David G. Johnston" writes: >> On Sat, Oct 7, 2023 at 11:11 AM Kirk Parker wrote: >>> INSERT INTO emp_audit SELECT 'D', now(), user, OLD.*; -- <= ARGUMENT IN >>> QUESTION >>> The emp_audit table has a column named 'userid', which in actual usage >>> (next-to-last line quoted) is populated by 'user' which seems undefined in >>> the context. Was that intended to be 'current_user', or am I missing >>> something? > >> user is a valid pseudo-function: >> https://www.postgresql.org/docs/current/functions-info.html#FUNCTIONS-INFO-SESSION > > Yeah, either way has the same result. However, I wonder if we should > change this example to use current_user for clarity. It does look > more like it's intended to be a variable or column reference than > a built-in function. Agreed, and "user" is a hard search term to use for discovering what it is. +1 for changing to current_user. -- Daniel Gustafsson
Re: Wrong link in the documentation for versions 11, 12
> On 24 Oct 2023, at 16:24, Maxim Yablokov wrote: > > Hello! > > Our team have noticed that the link in the field "References" for data_type > on the following pages > (https://www.postgresql.org/docs/12/view-pg-sequences.html, > https://www.postgresql.org/docs/11/view-pg-sequences.html) is incorrect, so > I've fixed it. Patches are attached, please have a look. Thanks for the report, this is indeed incorrect. I've applied this patch to 11 and 12. -- Daniel Gustafsson
Re: Example 43.6. A PL/pgSQL Trigger Function for Maintaining a Summary Table
> On 26 Oct 2023, at 09:33, Maxim Yablokov wrote: > Example 43.6 on the page > https://www.postgresql.org/docs/16/plpgsql-trigger.html has two tables called > main. But it seems that the table time_dimension is not used any further, > it's a bit strange for one of main tables of the example. Am I missing > something, or should this example be extended (or reduced)? Interesting catch, time_dimension has been unused since introduced with commit a294726bc1d (in 2005), and the archives doesn't provide any further insights. While I don't have access to the book referred to for the example, we don't expect our readers to either so it seems to me that we could remove it from the example to avoid risk of confusion. Would you like to propose a patch for this? -- Daniel Gustafsson
Re: pg_isready --dbname option is broken. So it should not be in the manual
> On 26 Oct 2023, at 14:20, David G. Johnston > wrote: > > On Thursday, October 26, 2023, PG Doc comments form <mailto:nore...@postgresql.org>> wrote: > The following documentation comment has been logged on the website: > > Page: https://www.postgresql.org/docs/16/app-pg-isready.html > <https://www.postgresql.org/docs/16/app-pg-isready.html> > Description: > > the --dbname option in pg_isready seems not to work propperly. the tool > returns 'ok' as long as the cluster itselft is running, no matter how wrong > the bdname might be. > > as this seems to be a ~10 year old misbehaviour as per the below thread I > think it should be removed from the manual. > > https://www.postgresql.org/message-id/flat/52840D38.9070604%40agliodbs.com > <https://www.postgresql.org/message-id/flat/52840D38.9070604%40agliodbs.com> > > Read the notes section. The notes section is pretty hidden though, I can sympathize with anyone missing it and maybe making the info a bit more visible would be good? -- Daniel Gustafsson
Re: Example 43.6. A PL/pgSQL Trigger Function for Maintaining a Summary Table
> On 26 Oct 2023, at 12:31, Maxim Yablokov wrote: > > I believe that the attached patch should fix this problem. Please have a look. Thanks, I'll await pushing and backpatching if Tom who committed it has insights into whether it was missed or if it indeed serves a purpose. If not I think it should be backpatched all the way since it exists for all supported versions. -- Daniel Gustafsson
Re: add new acronym "AM"
> On 12 Nov 2023, at 00:08, PG Doc comments form wrote: > > The following documentation comment has been logged on the website: > > Page: https://www.postgresql.org/docs/16/acronyms.html > Description: > > while reading the progres codebase, i could find you're using the acronym > "AM" which denotes "Access Method". it's be nice to add it to the list of > acronyms That's a fair point. It's sort of hard to refer back from the acronym list though since we don't have a single Access Method section but instead one for Indexes and one for Relations. In the attached diff I propose that we add a glossary entry for Access Method (suggested better wording much appreciated) which the acronym can refer to. Being such a core concept it doesn't seem like a bad idea to explain it. -- Daniel Gustafsson am_acronym.diff Description: Binary data
Re: Missing ;
> On 10 Nov 2023, at 22:00, PG Doc comments form wrote: > > The following documentation comment has been logged on the website: > > Page: https://www.postgresql.org/docs/16/sql-select.html > Description: > > Hi, > > To be consistent, the "with" example should end in a ";". > > WITH t AS ( >SELECT random() as x FROM generate_series(1, 3) > ) > SELECT * FROM t > UNION ALL > SELECT * FROM t; Thats absolutely right, it should end with a semicolon. > Possibly the most pathetic contribution ever? > Apologies. No need for an apology. *All* contributions are valuable, big and small. I'll go ahead and fix this, thanks for the report! -- Daniel Gustafsson
Re: add new acronym "AM"
> On 13 Nov 2023, at 12:20, Alvaro Herrera wrote: > > On 2023-Nov-13, Daniel Gustafsson wrote: > >> That's a fair point. It's sort of hard to refer back from the acronym list >> though since we don't have a single Access Method section but instead one for >> Indexes and one for Relations. In the attached diff I propose that we add a >> glossary entry for Access Method (suggested better wording much appreciated) >> which the acronym can refer to. Being such a core concept it doesn't seem >> like >> a bad idea to explain it. > > +1 for a glossary entry. > > + Access methods are the interfaces which > + PostgreSQL use in order to access relations > + and indexes. This abstraction allows for adding support for new > + types of tuple storage. For more information, see linkend="indexam" /> > + and . > > We don't start the glossary definition with the term we're defining. > For example, we say > Atomicity > The property of a transaction that ... > we don't say > Atomicity > Atomicity is the property of ... > > So you would want your definition to be something like > "Interfaces which PostgreSQL use to ..." > > I'd say "data in tables and indexes" rather than "relations and > indexes", and "data storage" instead of "tuple storage". > > "For more information" should be its own . Thanks, that makes it a lot better. v2 with the above changes attached. -- Daniel Gustafsson v2-0001-doc-Add-acronym-and-glossary-term-for-Access-Meth.patch Description: Binary data
Re: Restore to a new database from a backup (.tar) generated from
> On 29 Nov 2023, at 23:18, PG Doc comments form wrote: > > The following documentation comment has been logged on the website: > > Page: https://www.postgresql.org/docs/15/app-pgrestore.html > Description: > > After creating a new database in postgreSQL : This form is not intended to be used for general questions about postgres, please use the appropriate mailinglist for this. In your case I would recomment pgsql-general. https://www.postgresql.org/list/ -- Daniel Gustafsson
Re: 'bar' shouldn't be a string in example
> On 18 Dec 2023, at 19:06, PG Doc comments form wrote:
> ALTER FOREIGN DATA WRAPPER dbi OPTIONS (ADD foo '1', DROP 'bar');
>
> I think "bar" is akin to "foo" and therefore should be similarly an option?
> (i.e. not a string value)?
Nice catch, "DROP 'bar'" is considered to be unqualified and thus ADD is
assumed, generating the below options:
postgres=# alter foreign data wrapper dummy options (add foo '1', drop 'bar');
ALTER FOREIGN DATA WRAPPER
postgres=# select fdwoptions from pg_foreign_data_wrapper where fdwname='dummy';
fdwoptions
--
{foo=1,drop=bar}
(1 row)
This has been incorrect since forever so I will backpatch this into all
supported versions.
--
Daniel Gustafsson
Re: 37.10.5 - outdated compiler for FreeBSD
> On 30 Dec 2023, at 12:20, Digital Dog wrote: > Therefore please update compilation instructions for FreeBSD for future > PostgreSQL versions by replacing "gcc" with "cc" and changing version > information from FreeBSD 3.0 to 13.0. Thanks for your report, the attached diff updates the compiler and comment as per the above. Unless there are objections I'll go ahead with that. -- Daniel Gustafsson freebsd_compiler.diff Description: Binary data
Re: Missing information on '-X' in section 26.3.6.1.
> On 23 Jan 2024, at 21:43, David G. Johnston > wrote: > > On Tue, Jan 23, 2024 at 1:30 PM PG Doc comments form <mailto:nore...@postgresql.org>> wrote: > The following documentation comment has been logged on the website: > > Page: https://www.postgresql.org/docs/16/continuous-archiving.html > <https://www.postgresql.org/docs/16/continuous-archiving.html> > Description: > > I noticed, that in section 26.3.6.1. it's not specified, what the -X > parameter should be set to (stream or fetch, or whether it even matters). I > could continue with trial and error, but it confused me a bit. > > The -X parameter is documented to have a default; but since both fetch and > stream are documented to give you the same end result it doesn't matter. Of > course you cannot specify the none method. Agreed. Still, it doesn't hurt to spell out what we take for granted but a newcomer have to figure out in order to make the documentation easy to follow for new users. Something like the attached would be enough I think. -- Daniel Gustafsson pg_basebackup_X.diff Description: Binary data
Re: SQL command : ALTER DATABASE OWNER TO
> On 24 Jan 2024, at 15:23, Laurenz Albe wrote: > > On Wed, 2024-01-24 at 11:08 +0100, gp...@free.fr wrote: >> for this "ALTER DATABASE" form, it should be mentioned that after execution >> of the command, >> the old database owner loses all his privileges on it (even connection) >> although it might >> still owns schemas or objects (tables, index,...) inside it. >> >> Thanks in advance to add this important precision. > > How about this: > > diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml > index 4044f0908f..44042f863c 100644 > --- a/doc/src/sgml/ddl.sgml > +++ b/doc/src/sgml/ddl.sgml > @@ -1891,6 +1891,8 @@ ALTER TABLE table_name OWNER > TO new_owne >Superusers can always do this; ordinary roles can only do it if they are >both the current owner of the object (or inherit the privileges of the >owning role) and able to SET ROLE to the new owning > role. > + All object privileges of the old owner are transferred to the new owner > + along with the ownership. > Doesn't seem unreasonable to me, it won't make the docs harder to read and use for experienced users while it may make them easier to follow for new users. -- Daniel Gustafsson
Incorrect grammar on ALTER EVENT TRIGGER
The ALTER EVENT TRIGGER .. page has an extra TRIGGER in the parameters section for ENABLE/DISABLE parameters which isn't supported in the grammar: https://www.postgresql.org/docs/devel/sql-altereventtrigger.html postgres=# alter event trigger on_login_trigger disable trigger; ERROR: syntax error at or near "trigger" LINE 1: alter event trigger on_login_trigger disable trigger; ^ postgres=# alter event trigger on_login_trigger enable trigger; ERROR: syntax error at or near "trigger" LINE 1: alter event trigger on_login_trigger enable trigger; ^ postgres=# alter event trigger on_login_trigger enable always trigger; ERROR: syntax error at or near "trigger" LINE 1: alter event trigger on_login_trigger enable always trigger; ^ The attached trivial patch removes the extra keyword, which needs to be backpatched all the way down. -- Daniel Gustafsson alter_evt.diff Description: Binary data
Re: ERROR: plpython3u
> On 25 Jan 2024, at 05:58, PG Doc comments form wrote:
>
> The following documentation comment has been logged on the website:
>
> Page: https://www.postgresql.org/docs/16/tutorial-join.html
> Description:
>
> CREATE EXTENSION plpython3u;
>
> [2024-01-25 05:56:50] [58P01] ERROR: could not load library "C:/Program
> Files/PostgreSQL/16/lib/plpython3.dll": The specified module could not be
> found.
The documentation comments is for reporting errors in the documentation. For
general help with postgres, please subscribe to the pgsql-general mailinglist
or pgsql-novice list for help getting started:
https://www.postgresql.org/list/
--
Daniel Gustafsson
Re: unknown option --subject
> On 31 Jan 2024, at 18:21, PG Doc comments form wrote: > On this page this command does not work > `openssl x509 -in myclient.crt -noout --subject -nameopt RFC2253` > unknown option --subject > > We should use only one dash `-subject` That's correct, it should be a single dash. Thanks for the report, I'll fix this backpatched down to 14 where it was introduced. -- Daniel Gustafsson
Re: Missed information about clientname=CN option
> On 1 Feb 2024, at 08:35, David G. Johnston wrote: > maybe move the wording to the cert page and replace the content in > pg_hba.conf with a link to there. Leaning toward the later ATM. That sounds like the best option IMHO, care to propose a patch? -- Daniel Gustafsson
Re: Broken link
> On 5 Feb 2024, at 22:23, PG Doc comments form wrote: > This page has a link that says "See the release notes for PostgreSQL 12 for > details on this change." > https://www.postgresql.org/docs/current/recovery-config.html > > The link does not go to the release notes though. While not directly to the v12 release notes, it leads to a page where the release notes are linked from which seems good enough here. This is a note on a change that happened in the oldest still supported version, with the previous behavior EOL. -- Daniel Gustafsson
Re: Broken link
> On 6 Feb 2024, at 11:46, Alvaro Herrera wrote: > > On 2024-Feb-06, Daniel Gustafsson wrote: > >>> On 5 Feb 2024, at 22:23, PG Doc comments form >>> wrote: >> >>> This page has a link that says "See the release notes for PostgreSQL 12 for >>> details on this change." >>> https://www.postgresql.org/docs/current/recovery-config.html >>> >>> The link does not go to the release notes though. >> >> While not directly to the v12 release notes, it leads to a page where the >> release notes are linked from which seems good enough here. This is a note >> on >> a change that happened in the oldest still supported version, with the >> previous >> behavior EOL. > > The release notes for 12.0 [1] say less than the recovery-config.html > page says about the matter. I think a good fix for this complaint is to > remove the whole phrase "See ... for details on this change". > > [1] https://www.postgresql.org/docs/release/12.0/ I'm guessing it's the below entry which is referred to, which I agree isn't likely to be all that helpful to any reader, more reading is required. * Move recovery.conf settings into postgresql.conf (Masao Fujii, Simon Riggs, Abhijit Menon-Sen, Sergei Kornilov) recovery.conf is no longer used, and the server will not start if that file exists. recovery.signal and standby.signal files are now used to switch into non-primary mode. The trigger_file setting has been renamed to promote_trigger_file. The standby_mode setting has been removed. That being said, all the obsolote appendix pages share that very link structure, so I'm not sure if removing one of them is helpful. Maybe removing all of them and instead expanding appendix-obsolete.sgml with an explanation of where to find more information is better? -- Daniel Gustafsson
Re: Pathetic pedantry
> On 7 Feb 2024, at 22:33, PG Doc comments form wrote: > [ STRATEGY [=] strategy ] ] > > ...has a superfluous ], I think? Nice catch, it sure seems like so. Will fix, thanks for the report! -- Daniel Gustafsson
Re: bgwriter_delay
> On 10 Feb 2024, at 01:08, PG Doc comments form wrote: > Would be nice to add the limits to the doc, according to my pg15 instance I > can't set bgwriter_delay more than 1 ms. (I set it to 60 s and got a > FATAL upon startup) We do print the valid range for other bgwriter GUCs so it doesn't seem like an unreasonable idea. It might not help too many, but not printing it at all clearly doesn't really help anyone. -- Daniel Gustafsson
Re: Broken link in pgcrypto documentation
> On 12 Feb 2024, at 13:55, PG Doc comments form wrote: > > The following documentation comment has been logged on the website: > > Page: https://www.postgresql.org/docs/16/pgcrypto.html > Description: > > I was going through the links in pgcrypto documentation and I realized that > one of the links at Useful Reading section do not work. Thanks for the report! However, I wonder if we aren't better off removing the "Useful Reading" section altogether? The field of crypto is continuously advancing and keeping a stale 10+ year old list of links is unlikely to provide more insights than what more curated sites can do. -- Daniel Gustafsson
Re: Broken link in pgcrypto documentation
> On 13 Feb 2024, at 20:42, Tom Lane wrote: > > Magnus Hagander writes: >> On Tue, Feb 13, 2024 at 7:12 PM Daniel Gustafsson wrote: >>> However, I wonder if we aren't better off removing the "Useful Reading" >>> section >>> altogether? The field of crypto is continuously advancing and keeping a >>> stale >>> 10+ year old list of links is unlikely to provide more insights than what >>> more >>> curated sites can do. > >> +1. I don't think it's the job of a postgres contrib module to maintain that. > > +1. We haven't maintained that list in the past and it seems unlikely > that we'll get better at it. > > I'm a little dubious about the "Technical References" list right below > it, too. The RFC references are probably useful and stable, and maybe > the wikipedia ref is OK, but I have little faith in either the > stability or the long-term relevance of the other two links. Not even those are all that stable, while the RFCs' in question haven't been replaced they have all been updated with new RFC's which we don't link to. I think we are better off removing them as well and leaving reading up on security/crypto subject an exercise for the reader. Specifically, I propose the attached. -- Daniel Gustafsson pgcrypto_links.diff Description: Binary data
Re: Broken link in pgcrypto documentation
> On 13 Feb 2024, at 21:24, Magnus Hagander wrote: > > On Tue, Feb 13, 2024 at 9:08 PM Tom Lane wrote: >> >> Daniel Gustafsson writes: >>> On 13 Feb 2024, at 20:42, Tom Lane wrote: >>>> I'm a little dubious about the "Technical References" list right below >>>> it, too. The RFC references are probably useful and stable, and maybe >>>> the wikipedia ref is OK, but I have little faith in either the >>>> stability or the long-term relevance of the other two links. >> >>> Not even those are all that stable, while the RFCs' in question haven't been >>> replaced they have all been updated with new RFC's which we don't link to. >>> I >>> think we are better off removing them as well and leaving reading up on >>> security/crypto subject an exercise for the reader. >> >> Good point. Nuking both lists works for me. > > +1. Alright, sounds good. I'll go ahead with that in the morning then, backpatched all the way down since the links are equally outdated everywhere. -- Daniel Gustafsson
Re: [PATCH] Fix link to pg_ident_file_mappings
> On 21 Feb 2024, at 03:24, Erik Wienhold wrote: > > The docs on pg_reload_conf() in v15, v16, and devel have an incorrect > link to pg_ident_file_mappings. The attached patch fixes that. Nice catch, will fix. -- Daniel Gustafsson
Re: incorrect order? in "D.1. Supported Features" of PostgreSQL 16 manual
> On 23 Feb 2024, at 06:36, PG Doc comments form wrote: > The correct result would be as follows: > > F302 INTERSECT table operator > F302-02 INTERSECT ALL table operator > F303 INTERSECT DISTINCT table operator > F304 EXCEPT ALL table operator This was changed recently in c9f57541d970 which changed subfeatures to top-level features to match the SQL:2023 standard, F303 was previously a sub-feature named F302-01. That being said, I agree that it makes sense to place F303 below F302-02 as per the attached, unless Peter (on cc:) objects. -- Daniel Gustafsson f303.diff Description: Binary data
Re: incorrect order? in "D.1. Supported Features" of PostgreSQL 16 manual
> On 23 Feb 2024, at 12:23, 小泉 悟 wrote: > Upon closer inspection, F305 is also "INTERSECT ALL table operator”. > Perhaps F302-02 would be unnecessary. The list is intended to reflect what's in the SQL:2023 standard, so whatever the standard says we should too. I don't have a copy of the standard though so I'll leave it to someone who does comment. -- Daniel Gustafsson
Re: Fix analyze_sampling docs in postgres-fdw.sgml
> On 4 Mar 2024, at 09:37, Laurenz Albe wrote: > > On Mon, 2024-03-04 at 14:27 +0900, Shinya Kato wrote: >> I fixed analyze_sampling docs in postgres-fdw.sgml. >> - Changed analyze_sampling type 'text' to 'string' > > +1 Agreed, that should be changed, will fix. >> - Add a statement 'The option specified on a table overrides an option >> specified for the server.' > > I think that applies to all options. It would be better to have a general > statement to that effect at the beginning of the "Options" section. Yeah, that might be a good idead. -- Daniel Gustafsson
tools.ietf.org is decommissioned and our links are redirected
The tools.ietf.org server which we use for all RFC/BCP links in the docs has been decommissioned, and our links are 301 redirected to the new locations (datatracker. and rfc-editor.). To avoi another network roundtrip for our readers, the attached patch updates the links to their new respective locations. -- Daniel Gustafsson v1-0001-doc-Update-links-to-RFC-documents-to-avoid-redire.patch Description: Binary data
Re: tools.ietf.org is decommissioned and our links are redirected
> On 3 Apr 2024, at 14:23, Magnus Hagander wrote: > > On Wed, Apr 3, 2024 at 1:18 PM Daniel Gustafsson <mailto:dan...@yesql.se>> wrote: > The tools.ietf.org <http://tools.ietf.org/> server which we use for all > RFC/BCP links in the docs has > been decommissioned, and our links are 301 redirected to the new locations > (datatracker. and rfc-editor.). To avoi another network roundtrip for our > readers, the attached patch updates the links to their new respective > locations. > > +1. Extra round-trips are annoying. Thanks for review. As it's not urgent in any way I'll apply with a back-patch after the freeze to avoid causing extra rebases at this point. -- Daniel Gustafsson
Re: 8.14.5 jsonb subscripting
> On 9 Apr 2024, at 16:02, Arne Sommerfelt wrote: > Thats the documentation for v16, not the version you are running. -- Daniel Gustafsson
Re: 8.14.5 jsonb subscripting
> On 9 Apr 2024, at 16:04, Arne Sommerfelt wrote: > > 12 is in the list of supported versions at the top of chapter 8.14. And the > non-working examples is in subsection 8.14.5 I think you've misunderstood the header of the page. This is the documentation you should be reading for your version if Postgres: https://www.postgresql.org/docs/12/index.html -- Daniel Gustafsson
Re: 8.14.5 jsonb subscripting
> On 9 Apr 2024, at 16:07, Arne Sommerfelt wrote: > > OK, sorry if am making unnecessary noise. Since my version was listed as > supported I assumed the docs was valid for me. No worries, we're all here to learn. The "supported version" means that 12 is a version which the project still supports with bugfixes. -- Daniel Gustafsson
Re: psql option
> On 9 Apr 2024, at 16:05, PG Doc comments form wrote: > > The following documentation comment has been logged on the website: > > Page: https://www.postgresql.org/docs/16/app-psql.html > Description: > > option -X, > > the specified comma after the letter X > > https://www.postgresql.org/docs/current/app-psql.html Nice catch, will fix. -- Daniel Gustafsson
Re: psql option
> On 9 Apr 2024, at 18:33, Daniel Gustafsson wrote: > >> On 9 Apr 2024, at 16:05, PG Doc comments form wrote: >> >> The following documentation comment has been logged on the website: >> >> Page: https://www.postgresql.org/docs/16/app-psql.html >> Description: >> >> option -X, >> >> the specified comma after the letter X >> >> https://www.postgresql.org/docs/current/app-psql.html > > > Nice catch, will fix. Committed, turns out the stray comma has been there since 7.3, so backpatched it all the way. Thanks for the report! -- Daniel Gustafsson
Re: tools.ietf.org is decommissioned and our links are redirected
> On 4 Apr 2024, at 12:41, Daniel Gustafsson wrote: > >> On 3 Apr 2024, at 14:23, Magnus Hagander wrote: >> >> On Wed, Apr 3, 2024 at 1:18 PM Daniel Gustafsson > <mailto:dan...@yesql.se>> wrote: >> The tools.ietf.org <http://tools.ietf.org/> server which we use for all >> RFC/BCP links in the docs has >> been decommissioned, and our links are 301 redirected to the new locations >> (datatracker. and rfc-editor.). To avoi another network roundtrip for our >> readers, the attached patch updates the links to their new respective >> locations. >> >> +1. Extra round-trips are annoying. > > Thanks for review. As it's not urgent in any way I'll apply with a back-patch > after the freeze to avoid causing extra rebases at this point. Now that the tree has settled down post-freeze, I've committed it. Thanks! -- Daniel Gustafsson
Re: pg_createsubscriber: A more precise link to the initial data sync
> On 16 Apr 2024, at 12:42, Pavel Luzanov wrote: > > Please consider a small correction of the link to the initial data > synchronization section on the pg_createsubscriber page. Agreed, that makes sense. Applied. -- Daniel Gustafsson
Re: The prompt is not displayed correctly in the example on psql page
> On 21 Apr 2024, at 12:57, PG Doc comments form wrote: > > The following documentation comment has been logged on the website: > > Page: https://www.postgresql.org/docs/16/app-psql.html > Description: > > On this page https://www.postgresql.org/docs/current/app-psql.html > > where is? >> `( if there is an unmatched left parenthesis` > > ```sql > testdb=> SELECT t1.first as "A", t2.first+100 AS "B", > t1.first*(t2.first+100) as "AxB", > testdb(> row_number() over(order by t2.first) AS ord > testdb(> FROM my_table t1 CROSS JOIN my_table t2 ORDER BY 1 DESC > testdb(> \crosstabview "A" "B" "AxB" ord > ``` That's an impressively eagle-eyed observation, it is indeed showing an open parenthesis where none is. Will fix. -- Daniel Gustafsson
Re: No documentation on how pg_ctl is installed
> On 23 Apr 2024, at 14:40, PG Doc comments form wrote: > > The following documentation comment has been logged on the website: > > Page: https://www.postgresql.org/docs/15/app-pg-ctl.html > Description: > > I have used postgresql@14 for several years and have always used pg_ctl to > start the postgres server, check status etc. > > I tried upgrading to postgresql@15 with the command brew install > postgresql@15 on a Mac from Terminal and pg_ctl is apparently not installed. > The Documentation page for pg_ctl goes into all kinds of detail about the > utility, the options to use, etc. but NOTHING about how it is installed, > troubleshooting when it doesn't work or when it is not found. Google > searches yield very little information also. > > Fairly new to postgres - apologies for the newbie comments but a little more > documentation is needed here. This sounds like a question for the Homebrew maintainers, the postgres project is not packaging postgres for Homebrew and have no insight into how they do it. -- Daniel Gustafsson
Re: The prompt is not displayed correctly in the example on psql page
> On 22 Apr 2024, at 10:45, Daniel Gustafsson wrote: > >> On 21 Apr 2024, at 12:57, PG Doc comments form >> wrote: >> >> The following documentation comment has been logged on the website: >> >> Page: https://www.postgresql.org/docs/16/app-psql.html >> Description: >> >> On this page https://www.postgresql.org/docs/current/app-psql.html >> >> where is? >> `( if there is an unmatched left parenthesis` >> >> ```sql >> testdb=> SELECT t1.first as "A", t2.first+100 AS "B", >> t1.first*(t2.first+100) as "AxB", >> testdb(> row_number() over(order by t2.first) AS ord >> testdb(> FROM my_table t1 CROSS JOIN my_table t2 ORDER BY 1 DESC >> testdb(> \crosstabview "A" "B" "AxB" ord >> ``` > > That's an impressively eagle-eyed observation, it is indeed showing an open > parenthesis where none is. Will fix. Done, thanks for the report! -- Daniel Gustafsson
Re: Avoid too prominent use of "backup" on pg_dump man page
> On 30 May 2024, at 01:11, Peter Eisentraut wrote: > Suggestions for word-smithing welcome. No objections to using export over backup, but it does make the use of "restore" feel awkward as that's generally an operation on a backup and not an export. -least one schema/table in the backup file. +least one schema/table in the file to be restored. Would it make sense to use "import" in some cases instead? -- Daniel Gustafsson
Document when ssl_prefer_server_ciphers went in
In the documentation for ssl_prefer_server_ciphers we only say it's not in "older version" but we omit to specify it further. Since it's a fairly important setting for security I think it makes sense to add the version to help users, as in the small attached diff (which also adds proper markup in the paragraph while in there). -- Daniel Gustafsson ssl_prefer_cipher.diff Description: Binary data
Re: Document when ssl_prefer_server_ciphers went in
> On 3 Jul 2024, at 18:22, Tom Lane wrote: > > Daniel Gustafsson writes: >> In the documentation for ssl_prefer_server_ciphers we only say it's not in >> "older version" but we omit to specify it further. Since it's a fairly >> important setting for security I think it makes sense to add the version to >> help users, as in the small attached diff (which also adds proper markup in >> the >> paragraph while in there). > > This could be shortened perhaps: > > -Older PostgreSQL versions do not have this setting and always use the > +PostgreSQL versions before 9.4 do not > have this setting and always use the Good idea, that reads better. -- Daniel Gustafsson
Re: Joe Hellerstein's "Looking Back at Postgres" paper
> On 4 Jul 2024, at 07:40, Tom Lane wrote: > > I happened to come across this: > > https://arxiv.org/pdf/1901.01973 > > I found this to be really interesting reading, so I wonder if > we shouldn't cite it in history.sgml or some such place. It's a really good read, +1 for referencing it in history.sgml. I would probably have placed it at the tail end of 2.1 to wrap up that section or at the very end. Unrelated to that, but reading history.sgml I found this sentend at the end of the page to be sort of misleading: "Details about what has happened in PostgreSQL since then can be found in Appendix E." While technically true, it seems a bit overpromising in a history section to refer to the release notes which are written in a very different way from the prose here (and the release notes are not even in Appendix E anymore). -- Daniel Gustafsson
Re: Document when ssl_prefer_server_ciphers went in
> On 3 Jul 2024, at 11:49, Peter Eisentraut wrote: > > On 03.07.24 11:23, Daniel Gustafsson wrote: >> In the documentation for ssl_prefer_server_ciphers we only say it's not in >> "older version" but we omit to specify it further. Since it's a fairly >> important setting for security I think it makes sense to add the version to >> help users, as in the small attached diff (which also adds proper markup in >> the >> paragraph while in there). > > Looks reasonable to me. Thanks, pushed with the wording suggested to Tom downthread. > Would it make sense to remove the setting altogether? I wouldn't be opposed to it, I can't think of any legitimate usecase for it outside of testing (it's very similar to ssl_max_protocol_version in that sense). On the other hand, it's very little code to carry and removing it would cause churn for anyone who has it in their configuration management system for provisioning. Maybe it would make sense to remove it from the sample config? -- Daniel Gustafsson
Re: Bibliography reference redirects to a Forbiden page.
> On 11 Jun 2024, at 11:00, PG Doc comments form wrote: > > The following documentation comment has been logged on the website: > > Page: https://www.postgresql.org/docs/16/biblio.html > Description: > > "Serializable Snapshot Isolation in PostgreSQL" by D. Ports, in the > bibliography leads to a forbidden page. Does it still do that? Clicking the link leads me to the referenced paper. -- Daniel Gustafsson
Re: Joe Hellerstein's "Looking Back at Postgres" paper
> On 4 Jul 2024, at 17:12, Tom Lane wrote: > > Daniel Gustafsson writes: >> Unrelated to that, but reading history.sgml I found this sentend at the end >> of >> the page to be sort of misleading: > >> "Details about what has happened in PostgreSQL since then can be found >> in Appendix E." > >> While technically true, it seems a bit overpromising in a history section to >> refer to the release notes which are written in a very different way from the >> prose here (and the release notes are not even in Appendix E anymore). > > Well, it made sense with our old practice of including all the notes > back to 1996 in appendix E. Yup, and I'm glad we don't anymore. > But now, not so much. The simplest fix would be to change this text to point > to > > https://www.postgresql.org/docs/release/ Agreed. I would probably reword that to say "Details about what has happened in each PostgreSQL release since.." while at it. -- Daniel Gustafsson
Re: Joe Hellerstein's "Looking Back at Postgres" paper
> On 4 Jul 2024, at 22:22, Tom Lane wrote: > > Daniel Gustafsson writes: >> On 4 Jul 2024, at 07:40, Tom Lane wrote: >>> I happened to come across this: >>> https://arxiv.org/pdf/1901.01973 >>> I found this to be really interesting reading, so I wonder if >>> we shouldn't cite it in history.sgml or some such place. > >> It's a really good read, +1 for referencing it in history.sgml. I would >> probably have placed it at the tail end of 2.1 to wrap up that section or at >> the very end. > > After thinking for awhile, that seemed like burying the lede. > It's an independent telling of the tale, and could reasonably > go near the top, as in the attached draft. Agreed, good idea. > (I'm not too sure how to cite book chapters in DocBook, so feel > free to critique that. Also, I noticed that the ports12 item > was not in alphabetical order, so I moved it.) Reading the docbook reference I wasn't able to figure out a better way than what you have done so +1 on going ahead with this version. >> Unrelated to that, but reading history.sgml I found this sentend at the end >> of >> the page to be sort of misleading: >> "Details about what has happened in PostgreSQL since then can be found >> in Appendix E." > > Fixed that too. Thanks. > BTW, I contacted Hellerstein to make sure he's okay with this, > and he is. +1 -- Daniel Gustafsson
Re: A minor bug in doc. Hovering over heading shows # besides it.
> On 18 Jul 2024, at 07:18, Tom Lane wrote: > Yeah. I've found this new feature useful multiple times already, > but the '#' icon is as non-mnemonic and unobvious as could possibly > be. OTOH, I don't know of a standard icon for this feature. While not a standard the pilcrow [0] is, AFAICT from a bit of looking at other docs, commonly used for this. There is a lot of variability though so whichever we choose it will be wrong one for someone. -- Daniel Gustafsson [0] https://en.wikipedia.org/wiki/Pilcrow
Re: A minor bug in doc. Hovering over heading shows # besides it.
> On 18 Jul 2024, at 15:49, Tom Lane wrote:
>
> Daniel Gustafsson writes:
>> While not a standard the pilcrow [0] is, AFAICT from a bit of looking at
>> other
>> docs, commonly used for this. There is a lot of variability though so
>> whichever we choose it will be wrong one for someone.
>
> I like this suggestion better because that's U+00B6, ie part of
> LATIN-1, so it's *far* more likely to render correctly everywhere
> than U+01F517 is. We could also consider the section sign §
> (U+00A7).
>
> In any case, a tooltip would help reduce confusion.
Looking a bit closer, the Python documentation does just this, a pilcrow with a
tool-tip ("Link to this heading") when hovering over it
--
Daniel Gustafsson
Re: Typo in 15.3.4
On 25 Jul 2024, at 19:07, David G. Johnston wrote:On Thu, Jul 25, 2024 at 9:50 AM PG Doc comments form <nore...@postgresql.org> wrote:The following documentation comment has been logged on the website: Page: https://www.postgresql.org/docs/16/parallel-plans.html Description: In section 15.3.4, I believe "multiple results sets" is a typo for "multiple result sets". It says: > Plans that involve appending multiple results sets can therefore achieve coarse-grained parallelism even when efficient partial plans are not available. It's also possible this should say "multiple results" rather than "multiple result sets".Good catch, and an acceptable solution.However, I'm inclined to write: "multiple inputs" at that spot:Plans that involve appending multiple inputs can therefore achieve...Using the term "result set" here just feels off, though that is a mostly uninformed (as to precedent) opinion.I think result sets the correct term since the Append node is combining partialresults made by other parallel nodes. Doing some reading it seems to me that"results sets" isn't incorrect (though I might have misunderstood the grammarfrom not being a native speaker), but I'm still inclined to change since weconsistently use "result sets" in the rest of the documentation. --Daniel Gustafsson 0001-doc-Consistent-use-result-set-in-documentation.patch Description: Binary data
Re: Examples Missing
> On 26 Aug 2024, at 22:16, PG Doc comments form wrote: > > The following documentation comment has been logged on the website: > > Page: https://www.postgresql.org/docs/16/app-pgdump.html > Description: > > Examples should be added for every option available for pg_dump. I was > looking for example for on-conflict-do-nothing, and rows-per-insert and what > does nrows do? Even with examples for every option we are unlikely to cover all combinations that anyone would like to see. I do think it would be good if we made sure to mention the parameter name in the description to avoid any confusion. Something like: -INSERT command. The value specified must be a +INSERT command to be nrows. The value specified must be a There are many more options without parameters named in the description though. -- Daniel Gustafsson
Re: pg_upgrade -c cannot be run if old cluster is running
> On 5 Sep 2024, at 15:39, Tom Lane wrote: > > Alain Bourgeois writes: >> /usr/lib/systemd/system/postgresql-10.service has >> PGDATA=/var/lib/pgsql/10/data/, /var/lib/pgsql/10/data/postgtresql.conf >> holds data_directory = '/mnt/pgdata/pgdir' > > This is probably the source of your problem. IIRC, pg_upgrade > needs to be pointed at the actual old data directory, not > PGDATA=/var/lib/pgsql/10/data. Correct, pg_upgrade use the PGDATANEW and PGDATAOLD env variables for the cluster data directories. -- Daniel Gustafsson
Re: Documentation improvement patch
> On 5 Sep 2024, at 11:33, Oleg Sibiryakov wrote: > > Dear all, > I have prepared a patch containing some minor inconsistencies in the > documentation. Please, take a look. > The inconsistencies were noticed by: Ekaterina Kiryanova, Elena Indrupskaya, > Maxim Yablokov, Anna Uraskova, Elena Karavaeva, and me. > We will be looking forward to your feedback. > The patch shall be applied to the REL_17_STABLE branch. Most of these seem fine, but I need another read-through to digest them fully. Just a few small comments: -Specifies the builtin provider locale for the database default -collation order and character classification, overriding the setting -. The builtin provider locale for the database +default collation order and character classification, overriding the +setting . The . +Specifies the locale name when the builtin provider +is used. Locale support is described in . I don't think this use of "builtin" refers to the config value but rather the type of locale, so I think it's correct to not use here. -for not-null constraints at all, so they are not +for NOT NULL constraints at all, so they are not This seems mostly to be a question of taste, I don't think not-null is incorrect here. -- Daniel Gustafsson
Re: Documentation improvement patch
> On 10 Sep 2024, at 13:46, Oleg Sibiryakov wrote: > 1. Since we do not want to use here, I suggest we hyphenate it as > "built-in". What's your take on it? I think that's the right choice given the hyphenation used in the rest of the docs. There are a few more places on that same page which should be built-in rather than builtin to separate the concept from the parameter value. -- Daniel Gustafsson
PARALLEL in old syntax for CREATE AGGREGATE
When looking at review comments on one of my patches, I noticed that commit 41ea0c23761 didn’t include the PARALLEL keyword for the old style CREATE AGGREGATE syntax. Since it is supported, and commit 59b71c6fe6c use it in a testcase, it seems reasonable to add something along the lines of the attached patch to the docs. cheers ./daniel create_agg_parallel.patch Description: Binary data
Re: PARALLEL in old syntax for CREATE AGGREGATE
> On 24 Jan 2018, at 03:52, Bruce Momjian wrote: > > Robert, can you review the attached patch since it references your > commit? Thanks. Another approach is the patch in 62991614-9673-4276-99cc-6754e7a05...@yesql.se which contains a fix which allows for PARALLEL to be unquoted in the old syntax. cheers ./daniel
Trailing semicolons on partitioning example commands
Is there a reason for not ending all partitioning commands with semicolons in the declarative partitioning example? https://www.postgresql.org/docs/devel/static/ddl-partitioning.html The two last commands with TABLESPACE clauses are ended with semicolons, the first three arent. Attached patch adds semicolons such that all are properly ended. cheers ./daniel partcmd_semicolon.patch Description: Binary data
Re: A simple question
> On 01 Feb 2018, at 13:09, PG Doc comments form wrote: > > The following documentation comment has been logged on the website: > > Page: https://www.postgresql.org/docs/9.3/static/sql-keywords-appendix.html > Description: > > Hello, my client has a plethora of reserved words in their PostgreSQL > database using Greenplum. They don't wish to use the " " to allow for them > to remainmy question is, do you have a parameter I can set to bypass > PostgreSQL from flagging the reserved word all together? If your question concerns Greenplum and not PostgreSQL, the gpdb mailing lists are probably a better fit: https://greenplum.org/mailing-lists/ cheers ./daniel
Document WaitForBackgroundWorkerShutdown and fix bgworker typo
WaitForBackgroundWorkerShutdown() was added in 924bcf4f16d, but never documented which seems like an oversight for such a useful function. The attached patch adds this to bgworker.sgml, and also fixes what I believe are typos in the WaitForBackgroundWorkerStartup paragraph. cheers ./daniel bgworker.patch Description: Binary data
Re: https://www.postgresql.org/download/linux/ubuntu/
> On 26 Feb 2018, at 16:18, Indrek K wrote: > Please upgrade PostgreSQL document to latest version > https://www.postgresql.org/download/linux/ubuntu/ > Change apt-get install postgresql-9.6 > postgresql-10 The download pages are not guaranteed to always be up to date with the current release version, hence the "substitute the version number as required” mentioned on the page. That being said, there is no reason not to update the page, it’s just not highly prioritized. I’m happy to do the legwork unless there are objections, cc:ing the -www list as it's a better place to discuss this. cheers ./daniel
Re: Document WaitForBackgroundWorkerShutdown and fix bgworker typo
> On 01 Mar 2018, at 17:46, Andres Freund wrote: > > On 2018-02-09 23:43:26 +0100, Daniel Gustafsson wrote: >> WaitForBackgroundWorkerShutdown() was added in 924bcf4f16d, but never >> documented which seems like an oversight for such a useful function. The >> attached patch adds this to bgworker.sgml, and also fixes what I believe are >> typos in the WaitForBackgroundWorkerStartup paragraph. > > Pushed, after s/pass/passing/. Right, that reads a lot better, thanks! cheers ./daniel
