Errors in explanation of the --with-libxml configure option.
The following documentation comment has been logged on the website: Page: https://www.postgresql.org/docs/12/install-procedure.html Description: Online doc states [...], or set the variables XML2_CFLAGS and XML2_LIBS. (If pkg-config is installed, then to override its idea of where libxml2 is you must either set XML2_CONFIG or set both XML2_CFLAGS and XML2_LIBS to nonempty strings.) But neither XML2_CFLAGS nor XML2_LIBS appears in the actual configure scripts or makefiles, and so of course setting those env vars does no good. The INSTALL text file bundled in postgresql-12.1.tar.bz2 states instead [...] , you can either set the environment variable XML2_CONFIG to point to the "xml2-config" program belonging to the installation, or use the options "--with-includes" and "--with-libraries". Now *that* advice is correct, and following it leads to success. Therefore suggest sync that part of online doc to corresponding part of INSTALL offline doc. Thank you.
Re: Errors in explanation of the --with-libxml configure option.
> On 7 Oct 2020, at 02:43, PG Doc comments form wrote: > But neither XML2_CFLAGS nor XML2_LIBS appears in the actual configure > scripts or makefiles, and so of course setting those env vars does no good. > The INSTALL text file bundled in postgresql-12.1.tar.bz2 states instead The documentation on the website is always for the latest minor release (which is 12.4 in this case), and the XML2_CFLAGS and XML2_LIBS variables were introduced in 12.3. If you download the latest minor release instead it should just work. The INSTALL file in the archive you downloaded is correctly describing how to set up libxml for that particular version. cheers ./daniel
Re: Possible mistake in backup documentation
Greetings, * Laurenz Albe (laurenz.a...@cybertec.at) wrote: > On Fri, 2020-09-25 at 14:50 +0200, Magnus Hagander wrote: > > On Fri, Sep 25, 2020 at 2:32 PM Laurenz Albe > > wrote: > > > On Tue, 2020-09-22 at 14:17 +, PG Doc comments form wrote: > > > > In "25.3.3.2. Making An Exclusive Low-Level Backup", you said that "The > > > > exclusive backup method is deprecated and should be avoided. Prior to > > > > PostgreSQL 9.6, this was the only low-level method available, but it is > > > > now > > > > recommended that all users upgrade their scripts to use non-exclusive > > > > backups". But in the example in "25.3.6.1. Standalone Hot Backups" you > > > > use > > > > the exclusive version of backup command. Is it a mistake or not? > > > > > > Yes, that's true. > > > > Well, technically it is *correct*. It's just rather silly that we are using > > the deprecated API in the example. > > > > > How about the attached patch? > > > Perhaps that is too complicated, but I have no idea how to make it > > > simpler. > > > > For this example, can't we just show two sessions. That is, "in a psql, run > > pg_start_backup(). > > Then in a different session, copy all the files, and then back in psql run > > pg_stop_backup()" or such? > > > > This is still just an example of a low level operation, where the > > recommendation is (and is there iirc) > > to use a different tool for it already. > > I thought the point of the example is to show a workable script that could > perform a backup and could be used as a starting point to develop your own > backup solution. (I know that there are people who think writing your own > backup solution is evil, but I am not one of them.) That's certainly not actually the case. We don't currently have anywhere close to sufficient documention (unless you are reading the code and understand how PG works) for someone to develop their own backup solution using the low-level API. There's been attempts to fix that, and I suspect there'll be another attempt to improve the situation for v14, but not sure if that'll be successful. > If we replace that with a verbal description of how to do it, the example just > duplicates what is already documented. > > In that case I would opt for simply removing the example. Removing the example, as it really doesn't do what it implies, is probably the best way to address this. I'm not convinced that we could come up with a sufficient verbal description, but I'm happy to take a look and provide feedback if someone wants to try. Thanks, Stephen signature.asc Description: PGP signature
42.6.8.1. Obtaining Information About An Error
The following documentation comment has been logged on the website: Page: https://www.postgresql.org/docs/12/plpgsql-control-structures.html Description: 42.6.8.1. Obtaining Information About An Error This example omits raise notice code: DECLARE text_var1 text; text_var2 text; text_var3 text; BEGIN -- some processing which might cause an exception ... EXCEPTION WHEN OTHERS THEN GET STACKED DIAGNOSTICS text_var1 = MESSAGE_TEXT, text_var2 = PG_EXCEPTION_DETAIL, text_var3 = PG_EXCEPTION_HINT; END;
Re: 42.6.8.1. Obtaining Information About An Error
On Wed, Oct 7, 2020 at 12:57 PM PG Doc comments form wrote: > The following documentation comment has been logged on the website: > > Page: https://www.postgresql.org/docs/12/plpgsql-control-structures.html > Description: > > 42.6.8.1. Obtaining Information About An Error > > This example omits raise notice code: > > Yes, it does. I do not find the example any less useful for the lack. How one chooses to use the error information is not the point of the example, showing how to pull the data out of the error context is. David J.
doc bug for continuous archiving
Quoting the docs: https://www.postgresql.org/docs/13/continuous-archiving.html "As with base backups, the easiest way to produce a standalone hot backup is to use the pg_basebackup tool. If you include the -X parameter when calling it, all the write-ahead log required to use the backup will be included in the backup automatically, and no special action is required to restore the backup." This makes it sound like -X is a switch option, when in fact it demands an argument. The statement made is incorrect if the supplied argument is "none", but is correct for the other two options. Should this be changed to spell out which options it applies to (or maybe which option it does not apply to). I think this has been wrong ever since the capitalized -X was introduced in 9.2. Maybe it was intended to discuss -x, not -X ? Cheers, Jeff
Re: doc bug for continuous archiving
On Wed, Oct 7, 2020 at 2:35 PM Jeff Janes wrote: > Quoting the docs: > > https://www.postgresql.org/docs/13/continuous-archiving.html > > "As with base backups, the easiest way to produce a standalone hot backup > is to use the pg_basebackup tool. If you include the -X parameter when > calling it, all the write-ahead log required to use the backup will be > included in the backup automatically, and no special action is required to > restore the backup." > > This makes it sound like -X is a switch option, when in fact it demands an > argument. The statement made is incorrect if the supplied argument is > "none", but is correct for the other two options. Should this be changed > to spell out which options it applies to (or maybe which option it does not > apply to). > Just reading the doc page for pg_basebackup: "stream" is the default method value for this option. So if you just include "-X" you get "stream" which is indeed a mode that just works and the continuous archiving section you quote is correct. I'm not really sure I like the idea that we don't indicate which pg_basebackup key-value argument values are optional and which are mandatory. David J.
Re: doc bug for continuous archiving
On Wed, Oct 7, 2020 at 5:47 PM David G. Johnston wrote: > On Wed, Oct 7, 2020 at 2:35 PM Jeff Janes wrote: > >> Quoting the docs: >> >> https://www.postgresql.org/docs/13/continuous-archiving.html >> >> "As with base backups, the easiest way to produce a standalone hot backup >> is to use the pg_basebackup tool. If you include the -X parameter when >> calling it, all the write-ahead log required to use the backup will be >> included in the backup automatically, and no special action is required to >> restore the backup." >> >> This makes it sound like -X is a switch option, when in fact it demands >> an argument. The statement made is incorrect if the supplied argument is >> "none", but is correct for the other two options. Should this be changed >> to spell out which options it applies to (or maybe which option it does not >> apply to). >> > > Just reading the doc page for pg_basebackup: "stream" is the default > method value for this option. So if you just include "-X" you get "stream" > which is indeed a mode that just works and the continuous archiving section > you quote is correct. > > I'm not really sure I like the idea that we don't indicate which > pg_basebackup key-value argument values are optional and which are > mandatory. > > David J. > > Stream is the default if you don't specify -X at all. If you specify -X but with no argument for it, you get an error. pg_basebackup: option requires an argument -- 'X' Try "pg_basebackup --help" for more information. (Which is also a bit confusing, I would expect a default to apply when the option is specified without an argument, as opposed to when the option itself it is not specified ) Cheers, Jeff
Re: doc bug for continuous archiving
On 2020/10/08 7:12, Jeff Janes wrote: On Wed, Oct 7, 2020 at 5:47 PM David G. Johnston mailto:david.g.johns...@gmail.com>> wrote: On Wed, Oct 7, 2020 at 2:35 PM Jeff Janes mailto:jeff.ja...@gmail.com>> wrote: Quoting the docs: https://www.postgresql.org/docs/13/continuous-archiving.html "As with base backups, the easiest way to produce a standalone hot backup is to use the pg_basebackup tool. If you include the -X parameter when calling it, all the write-ahead log required to use the backup will be included in the backup automatically, and no special action is required to restore the backup." This makes it sound like -X is a switch option, when in fact it demands an argument. The statement made is incorrect if the supplied argument is "none", but is correct for the other two options. Should this be changed to spell out which options it applies to (or maybe which option it does not apply to). Just reading the doc page for pg_basebackup: "stream" is the default method value for this option. So if you just include "-X" you get "stream" which is indeed a mode that just works and the continuous archiving section you quote is correct. I'm not really sure I like the idea that we don't indicate which pg_basebackup key-value argument values are optional and which are mandatory. David J. Stream is the default if you don't specify -X at all. We should use the description like "Unless -X none is specified when calling it" ? If you specify -X but with no argument for it, you get an error. pg_basebackup: option requires an argument -- 'X' Try "pg_basebackup --help" for more information. (Which is also a bit confusing, I would expect a default to apply when the option is specified without an argument, as opposed to when the option itself it is not specified ) As far as I recall, we discussed that in [1] and gave up doing that. Regards, [1] https://postgr.es/m/1338235863.24935.27.ca...@vanquo.pezone.net -- Fujii Masao Advanced Computing Technology Center Research and Development Headquarters NTT DATA CORPORATION
