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
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: 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 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: 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: 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: 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: 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: 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: 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:02, Arne Sommerfelt wrote: > Thats the documentation for v16, not the version you are running. -- Daniel Gustafsson
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
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: 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
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: 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: [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: 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: 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 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: 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: 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: 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: 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: 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: 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: 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
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: 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
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: 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: '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: 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: 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: 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 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: 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: 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 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: 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: 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: 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: 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 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= -- 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: 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
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: 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: 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: 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: 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 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: 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 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: [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: 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
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: 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
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: 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: 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: 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 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 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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
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: Encryption in DataBase level
> On 14 Dec 2022, at 05:57, PG Doc comments form wrote: > Is it recommended for full database-level encryption and decryption? > What are the disadvantages of full DB-level encryption? > If there is no issue with full DB-level encryption, please share the best > option and way of implementing it. The documentation comment form is not intended for discussions. Please use the pgsql-general mailinglist for questions: https://www.postgresql.org/list/ -- Daniel Gustafsson https://vmware.com/
Re: First Person being used (only occurs in 2 other places in all of documentation)
> On 28 Oct 2022, at 12:50, Daniel Gustafsson wrote: > The attached patch rewords the first person form sentences to match the rest > of > the documentation. The "acknowledgment" sections are left as-is as I believe > they are free to have a more personal form. > > I also re-arranged the section on PO file editors a bit to keep the PO file > editor paragraph on editors only and not also contain important translation > information. Hearing no objections I've gone ahead and applied this. -- Daniel Gustafsson https://vmware.com/
Re: Alignment issue at 43.10. Trigger Functions
> On 18 Nov 2022, at 07:21, Laurenz Albe wrote: > > On Thu, 2022-11-17 at 18:14 +, PG Doc comments form wrote: >> Page: https://www.postgresql.org/docs/13/plpgsql-trigger.html >> >> Type alignment issue for salary at "Example 43.4. A PL/pgSQL Trigger >> Function for Auditing": >> >> CREATE TABLE emp_audit( >> operation char(1) NOT NULL, >> stamp timestamp NOT NULL, >> useridtext NOT NULL, >> empname text NOT NULL, >> salary integer >> ); > > Attached is a patch to fix that. There was a second occurrence of the above, as well as one table which had no vertical alignment at all. I fixed these and applied your patch to master. -- Daniel Gustafsson https://vmware.com/
Re: temporary file size clarification
> On 25 Nov 2022, at 21:14, Bruce Momjian wrote: > On Thu, Nov 24, 2022 at 10:14:20AM +0100, Daniel Gustafsson wrote: >> How about something like the attached? > > +1 Pushed, thanks! -- Daniel Gustafsson https://vmware.com/
Re: temporary file size clarification
> On 23 Nov 2022, at 20:43, Bruce Momjian wrote:
>
> On Wed, Nov 16, 2022 at 10:26:38AM +, PG Doc comments form wrote:
>> The following documentation comment has been logged on the website:
>>
>> Page: https://www.postgresql.org/docs/14/runtime-config-logging.html
>> Description:
>>
>> The setting log_temp_files will enable logging of the usage of temporary
>> files, including their size in the log files. The setting is given in
>> kilobytes, which is clearly documented. However, I could not find any clear
>> documentation that describes the unit of size that is used in the logfiles
>> themselves, the log line is something like "profiles@profiles LOG:
>> temporary file: path "base/pgsql_tmp/pgsql_tmp31863.1", size 3137536" but
>> there is no size unit in the logfile or in the settings documentation. Can
>> you add whether the log line is in bytes/kilobytes/megabytes?
>
> Uh, I believe it is simply in bytes.
It is, the relevant code path for the logging is:
if ((size / 1024) >= log_temp_files)
ereport(LOG,
(errmsg("temporary file: path \"%s\", size %lu",
path, (unsigned long) size)));
I don't think it's a bad idea to specify the unit in the documentation though,
as suggested by the OP. Since the setting considers a value without unit as
kb, and the logged value is without unit, there is room for confusion.
How about something like the attached?
--
Daniel Gustafsson https://vmware.com/
log_temp_files.diff
Description: Binary data
Re: Consistency of units (bits vs bytes)
> On 14 Nov 2022, at 20:12, PG Doc comments form wrote: > > The following documentation comment has been logged on the website: > > Page: https://www.postgresql.org/docs/15/datatype-uuid.html > Description: > > One can describe the size of datatypes in the common units of bits or bytes. > It'd be desirable to be consistent. Please reference these two pages... > https://www.postgresql.org/docs/current/datatype-numeric.html (data types > sized in bytes) > and > https://www.postgresql.org/docs/current/datatype-uuid.html (data type sized > in bits) These are different things, the page with numeric types discuss the number of bytes used to store the values. UUIDs are defined in the RFC as 128-bit identifiers, which is related to but not by definition the same as the space used to store them in the database. -- Daniel Gustafsson https://vmware.com/
Re: First Person being used (only occurs in 2 other places in all of documentation)
> On 28 Oct 2022, at 11:30, Daniel Gustafsson wrote: > >> On 28 Oct 2022, at 04:44, PG Doc comments form >> wrote: >> >> The following documentation comment has been logged on the website: >> >> Page: https://www.postgresql.org/docs/15/cube.html >> Description: >> >> I believe the use of First Person (I) is to be avoided in the documentation. >> It is incredibly rare in all of the documentation. > > I agree with this (and the other two emails about the same), these instances > would be better reworded to match the rest of the documentation. The attached patch rewords the first person form sentences to match the rest of the documentation. The "acknowledgment" sections are left as-is as I believe they are free to have a more personal form. I also re-arranged the section on PO file editors a bit to keep the PO file editor paragraph on editors only and not also contain important translation information. -- Daniel Gustafsson https://vmware.com/ first_person.diff Description: Binary data
Re: First Person being used (only occurs in 2 other places in all of documentation)
> On 28 Oct 2022, at 04:44, PG Doc comments form wrote: > > The following documentation comment has been logged on the website: > > Page: https://www.postgresql.org/docs/15/cube.html > Description: > > I believe the use of First Person (I) is to be avoided in the documentation. > It is incredibly rare in all of the documentation. I agree with this (and the other two emails about the same), these instances would be better reworded to match the rest of the documentation. -- Daniel Gustafsson https://vmware.com/
Re: PL/pgSQL casing
> On 2 Sep 2022, at 11:42, Pavel Stehule wrote: > > pá 2. 9. 2022 v 11:38 odesílatel Daniel Gustafsson <mailto:dan...@yesql.se>> napsal: > There are a few instances of PL/PgSQL in the docs, the attached changes the > casing on those to PL/pgSQL which we use consistently otherwise. > > +1 Pushed, thanks for review! -- Daniel Gustafsson https://vmware.com/
Re: DocBook 5.2
> On 5 Sep 2022, at 11:50, Jürgen Purtz wrote: > > On 04.09.22 17:39, Alvaro Herrera wrote: >> What changes? >> I doubt we'll want to adopt a new version immediately after release, >> since we want to stay compatible with older systems. > > The migration isn't a matter of days. It's a huge step because nearly all > files are touched and we have to act carefully to deliver (nearly) identical > HTML, PDF, ... files as before. As a preview of the ongoing the actual > README.md file is attached. Will the markup be similar enough to not carry a significant risk of introducing pain for backpatching doc patches? -- Daniel Gustafsson https://vmware.com/
PL/pgSQL casing
There are a few instances of PL/PgSQL in the docs, the attached changes the casing on those to PL/pgSQL which we use consistently otherwise. -- Daniel Gustafsson https://vmware.com/ plpgsql_casing.diff Description: Binary data
Re: Minor inconsistency in ref/drop_extension.sgml
> On 1 Sep 2022, at 13:49, Ekaterina Kiryanova > wrote: > I noticed a difference between v13 and v14 DROP EXTENSION pages, and v14 > looks better to me so I prepared a small patch to apply to the v13 page. That was done in commit d107e73fa8, which in turn was a fix-up to commit ef9d0cf19c which was backpatched to v13. I agree that the fixup should be backpatched to the same version that the original was, CC:ing John Naylor for a second opinion on that. -- Daniel Gustafsson https://vmware.com/
Re: Should 'sum(mvf)' read 'sum(mcv)'...?
> On 22 Aug 2022, at 12:08, Julien Rouhaud wrote: > That was actually introduced 2 years before in 234d50812c8 by Bruce. Yes, I was unclear, I meant that the second use was by Tom (whom I also missed to CC as I said I would so doing that now). -- Daniel Gustafsson https://vmware.com/
Re: Should 'sum(mvf)' read 'sum(mcv)'...?
> On 22 Aug 2022, at 09:48, Julien Rouhaud wrote: > 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. That seems plausible, but it does seem introduced on purpose in f5678e8e075 so CC:ing Tom for a trip down memory lane. Looking at this I noticed that we mark up MCV and MCF as acronyms but they aren't defined in acronyms.sgml. ISTM it's a good idea to keep a 1:1 mapping between markup and content, so we should probably do that as per the attached? -- Daniel Gustafsson https://vmware.com/ mcx_acronyms.diff Description: Binary data
Re: Typo in description of PROGRAM parameter for the COPY command
> On 21 Aug 2022, at 20:48, Tom Lane wrote: > > Daniel Gustafsson writes: >> On 21 Aug 2022, at 03:31, PG Doc comments form >> wrote: >>> ...so if you need to pass any arguments to shell command that come >>> from an untrusted source... >>> >>> The "to shell command that come" part should be changed so it either reads >>> like this: >>> >>> ...so if you need to pass any arguments to a shell command that comes >>> from an untrusted source... >>> >>> ...or it reads like this: >>> >>> ...so if you need to pass any arguments to shell commands that come >>> from an untrusted source... > >> Not being a native english speaker, but since we're already referring to "the >> command" in the sentence it seems more natural to me to change to "the shell >> command". > > Hmm ... to me the main problem with this fragment is that it's not > entirely clear whether we're speaking of untrusted arguments or an > untrusted shell command, ie which one is the antecedent of "that". > The proposed variants seem to make that worse not better. I suggest > rephrasing like > > ... so if you need to include any shell command arguments that come from > an untrusted source, you must ... > > Or maybe even better, just drop "shell command" from that phrase > altogether. > > Probably also s/passing/including/ in the next sentence. Agreed, those suggestions make it better. Skimming the page I noticed that we wrap CSV in in all but a few places, which seemed randomly "chosen". Another sentence which stood out to me was this one on FREEZE: "This violates the normal rules of MVCC visibility and users specifying should be aware of the potential problems this might cause." The use of "specifying" seems odd to me, removing it makes it read clearer IM-non-native-O. The attached includes all the above suggestions. -- Daniel Gustafsson https://vmware.com/ copy.diff Description: Binary data
Re: Typo in description of PROGRAM parameter for the COPY command
> On 21 Aug 2022, at 03:31, PG Doc comments form wrote: >> ...so if you need to pass any arguments to shell command that come > from an untrusted source... > > The "to shell command that come" part should be changed so it either reads > like this: > >> ...so if you need to pass any arguments to a shell command that comes > from an untrusted source... > > ...or it reads like this: > >> ...so if you need to pass any arguments to shell commands that come > from an untrusted source... Not being a native english speaker, but since we're already referring to "the command" in the sentence it seems more natural to me to change to "the shell command". -- Daniel Gustafsson https://vmware.com/
Re: documentation error
> On 20 Aug 2022, at 12:39, PG Doc comments form wrote: > documentation says " The psql commands \df and \do can be used to list all > available functions and operators, respectively." > > which clearly indicates that those are built in function , please correct me > if I am wrong and I went to the wrong part of the documentation. From the psql documentation https://www.postgresql.org/docs/14/app-psql.html: "By default, only user-created objects are shown; supply a pattern or the S modifier to include system objects. So \dfS is probably what you're looking for. Maybe making a link to the psql page from the text you're referring to could be useful? -- Daniel Gustafsson https://vmware.com/
Re: Update documentation page for translators
> On 17 Aug 2022, at 23:24, Bruce Momjian wrote: > > On Wed, Aug 17, 2022 at 10:58:55PM +0200, Daniel Gustafsson wrote: >>> On 17 Aug 2022, at 22:56, Bruce Momjian wrote: >> >>> Is there a reason this patch was not applied? >> >> Only that it fell of my radar, if you think it's adding value I'm happy to >> get >> it done now. > > Sure, it looked useful to me too. Done, thanks. -- Daniel Gustafsson https://vmware.com/
Re: Update documentation page for translators
> On 17 Aug 2022, at 22:56, Bruce Momjian wrote: > Is there a reason this patch was not applied? Only that it fell of my radar, if you think it's adding value I'm happy to get it done now. -- Daniel Gustafsson https://vmware.com/
Re: Lower or Upper case for F.33. pg_trgm
> On 16 Aug 2022, at 15:53, Tom Lane wrote:
>
> Erik Rijkers writes:
>> (bluntly stating 'similarity comparisons are case-insensitive' -
>> although I'm not really sure..)
>
> Perhaps like "similarity comparisons are case-insensitive in a
> standard build of pg_trgm", if you want to nod to the existence
> of a compile option without going into detail.
Looking at this I'm leaning towards paring down the diff posted upthread with
pretty much this, I think that will provide value while avoid causing
confusion.
As a related side note, there are four instances of "case insensitive{ly}" in
the docs with all other instances using "case-insensitive{ly}". I'm inclined
to fix those four to use a dash while at it to be consistent across all pages.
--
Daniel Gustafsson https://vmware.com/
pg_trgm_case.diff
Description: Binary data
Re: Lower or Upper case for F.33. pg_trgm
> On 16 Aug 2022, at 12:54, Erik Rijkers wrote: > > Op 16-08-2022 om 12:36 schreef Daniel Gustafsson: >>> On 16 Aug 2022, at 12:17, PG Doc comments form >>> wrote: >>> I have a question regarding the trigram algorithm and I can not find any >>> information about it in your documentation: >> Maybe we should add something about this? > > Yeah, it's a bit strange that none of the following strings yield any info on > that page: 'case', 'sensitiv', 'upper', 'lower', and that there is no > mention of the ~ versus ~* difference. > > Maybe worth to (already in pgtrgm.html) give the simple hint: > ~ is case-sensitive > ~* is case-insensitive > > In any case a link to functions-matching.html seems indicated. Yeah, I think there is room for improvements here. Are you up for drafting a patch for this? -- Daniel Gustafsson https://vmware.com/
