Re: Additional Chapter for Tutorial
On 29.04.20 21:12, Peter Eisentraut wrote: I don't see this really as belonging into the tutorial. The tutorial should be hands-on, how do you get started, how do you get some results. Yes, the tutorial should be a short overview and give instructions how to start. IMO the first 4 sub-chapters fulfill this expectation. Indeed, the fifth (VACUUM) is extensive and offers many details. During the inspection of the existing documentation I recognized that there are many details about VACUUM, AUTOVACUUM, all of their parameters as well as their behavior. But the information is spread across many pages: Automatic Vacuuming, Client Connection Defaults, Routine Vacuuming, Resource Consumption, VACUUM. Even for a person with some pre-knowledge it is hard to get an overview how this fits together and why things are solved in exactly this way. In the end we have very good descriptions of all details but I miss the 'big picture'. Therefore I summarized central aspects and tried to give an answer to the question 'why is it done in this way?'. I do not dispute that the current version of the page is not adequate for beginners. But at some place we should have such a summary about vacuuming and freezing. How to proceed? - Remove the page and add a short paragraph to the MVCC page instead. - Cut down the page to a tiny portion. - Divide it into two parts: a) a short introduction and b) the rest after a statement like 'The following offers more details and parameters that are more interesting for an experienced user than for a beginner. You can easily skip it.' Your material is more of an overview of the whole system. What's a new user supposed to do with that? When I dive into a new subject, I'm more interested in its architecture than in its details. We shall offer an overview about the major PG components and strategies to beginners. -- Jürgen Purtz
adding a TOC to the psql reference page
The following documentation comment has been logged on the website: Page: https://www.postgresql.org/docs/12/app-psql.html Description: Since https://www.postgresql.org/docs/current/app-psql.html is quite long, it would be nice to add a detailed table of contents at its beginning, in order to: - allow for easier browsing - allow to reference individual psql options, meta-commands, variables, prompts and environment variables by using their respective id attribute Thank you!!!
Re: adding a TOC to the psql reference page
On Thu, Apr 30, 2020 at 08:48:09PM +, PG Doc comments form wrote: > The following documentation comment has been logged on the website: > > Page: https://www.postgresql.org/docs/12/app-psql.html > Description: > > Since https://www.postgresql.org/docs/current/app-psql.html is quite long, > it would be nice to add a detailed table of contents at its beginning, in > order to: > > - allow for easier browsing > > - allow to reference individual psql options, meta-commands, variables, > prompts and environment variables by using their respective id attribute Yes, I can see the value in that, but I don't think we do that for any other SQL comments. Would doing it just for psql make sense? -- Bruce Momjian https://momjian.us EnterpriseDB https://enterprisedb.com + As you are, so once was I. As I am, so you will be. + + Ancient Roman grave inscription +
Re: adding a TOC to the psql reference page
Bruce Momjian writes: > On Thu, Apr 30, 2020 at 08:48:09PM +, PG Doc comments form wrote: >> Since https://www.postgresql.org/docs/current/app-psql.html is quite long, >> it would be nice to add a detailed table of contents at its beginning, > Yes, I can see the value in that, but I don't think we do that for any > other SQL comments. Would doing it just for psql make sense? psql's reference page is so much longer than any other command's that I think this is perfectly reasonable. However, we do have to worry about what will happen in man-page-format output. regards, tom lane
Re: adding a TOC to the psql reference page
On Thu, Apr 30, 2020 at 3:17 PM Bruce Momjian wrote: > On Thu, Apr 30, 2020 at 08:48:09PM +, PG Doc comments form wrote: > > > Since https://www.postgresql.org/docs/current/app-psql.html is quite > long, > > it would be nice to add a detailed table of contents at its beginning, in > > order to: > > > > - allow for easier browsing > > > > - allow to reference individual psql options, meta-commands, variables, > > prompts and environment variables by using their respective id attribute > > Yes, I can see the value in that, but I don't think we do that for any > other SQL comments. Would doing it just for psql make sense? > > Yes. Other parts of the documentation have TOC sections so its not like we don't do it ever. And even if by general rule the applications don't get a TOC (there isn't one that I'm aware of) psql would still warrant an exception given its position as the primary user interface to the system and the extensiveness of the documentation itself (a byproduct of being the primary user interface). David J.
Re: adding a TOC to the psql reference page
For SQL commands that are: - heavily used, and - structurally involved i'd say yes (`CREATE TABLE` comes to mind); otherwise, don't bother. The above selection criteria are subjective, so consensus should be gathered. On Fri, May 1, 2020 at 12:16 AM Bruce Momjian wrote: > On Thu, Apr 30, 2020 at 08:48:09PM +, PG Doc comments form wrote: > > The following documentation comment has been logged on the website: > > > > Page: https://www.postgresql.org/docs/12/app-psql.html > > Description: > > > > Since https://www.postgresql.org/docs/current/app-psql.html is quite > long, > > it would be nice to add a detailed table of contents at its beginning, in > > order to: > > > > - allow for easier browsing > > > > - allow to reference individual psql options, meta-commands, variables, > > prompts and environment variables by using their respective id attribute > > Yes, I can see the value in that, but I don't think we do that for any > other SQL comments. Would doing it just for psql make sense? > > -- > Bruce Momjian https://momjian.us > EnterpriseDB https://enterprisedb.com > > + As you are, so once was I. As I am, so you will be. + > + Ancient Roman grave inscription + > -- All work and no play makes George go astray.
Re: Roles for pg_basebackup
On 2020/04/28 17:15, Daniel Gustafsson wrote: On 28 Apr 2020, at 07:22, Fujii Masao wrote: On 2020/04/28 13:37, Michael Paquier wrote: On Mon, Apr 27, 2020 at 12:16:41PM +0200, Daniel Gustafsson wrote: Based on a recent conversation about backups I had I propose a small tweak to the pg_basebackup documentation. Listing the user types in the reverse order from today, putting superuser last, makes it IMO a little clearer that a REPLICATION role is preferrable to using a superuser for running backups. Makes sense to me. We do that in logical-replication.sgml as well as pg_rewind.sgml (the latter outlines superuser rights last). Seems there are other documentations having the similar description, for example, pg_receivewal.sgml, func.sgml and high-availability.sgml. Isn't it better to update also them at the same time? That doe make sense. I've updated the places where I think a user configuring the system might conceivably infer a preference from the order, but have left the other ones as is. Thanks for updating the patch! It looks good to me. Regards, -- Fujii Masao Advanced Computing Technology Center Research and Development Headquarters NTT DATA CORPORATION
