Re: Fix broken event trigger example
On 2022-Dec-23, Laurenz Albe wrote: > The example in > https://www.postgresql.org/docs/current/event-trigger-example.html > stopped compiling since commit 2f9661311b. > > Here is a patch to fix that. Right, thanks. Applied to all the relevant branches. -- Álvaro Herrera PostgreSQL Developer — https://www.EnterpriseDB.com/ "On the other flipper, one wrong move and we're Fatal Exceptions" (T.U.X.: Term Unit X - http://www.thelinuxreview.com/TUX/)
Re: The use "Postgres" in docs
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. -- Álvaro HerreraBreisgau, Deutschland — https://www.EnterpriseDB.com/
Re: some new glossary entries
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. 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. -- Álvaro HerreraBreisgau, Deutschland — https://www.EnterpriseDB.com/ "I'm always right, but sometimes I'm more right than other times." (Linus Torvalds) https://lore.kernel.org/git/pine.lnx.4.58.0504150753440.7...@ppc970.osdl.org/
Re: Postgres 14 documentation suggests range_agg is available, but it's not until Postgres 15
On 2023-May-18, PG Doc comments form wrote: > I noticed that range_agg is listed in the Postgres 14 documentation as an > available aggregate function here: > https://www.postgresql.org/docs/14/functions-aggregate.html > > However, my understanding is that this feature isn't available until > Postgres 15, per the feature matrix here: > https://www.postgresql.org/about/featurematrix/ > > Can the Postgres 14 documentation be updated to reflect this? Thanks! The documentation is correct -- 14 does have range_agg. It's the feature matrix that's in error. -- Álvaro Herrera PostgreSQL Developer — https://www.EnterpriseDB.com/ "The eagle never lost so much time, as when he submitted to learn of the crow." (William Blake)
Re: Postgres 14 documentation suggests range_agg is available, but it's not until Postgres 15
On 2023-May-19, Alvaro Herrera wrote: > On 2023-May-18, PG Doc comments form wrote: > > > I noticed that range_agg is listed in the Postgres 14 documentation as an > > available aggregate function here: > > https://www.postgresql.org/docs/14/functions-aggregate.html > > > > However, my understanding is that this feature isn't available until > > Postgres 15, per the feature matrix here: > > https://www.postgresql.org/about/featurematrix/ > > > > Can the Postgres 14 documentation be updated to reflect this? Thanks! > > The documentation is correct -- 14 does have range_agg. It's the > feature matrix that's in error. I updated the feature matrix. -- Álvaro Herrera PostgreSQL Developer — https://www.EnterpriseDB.com/ "I suspect most samba developers are already technically insane... Of course, since many of them are Australians, you can't tell." (L. Torvalds)
Re: Hyperlinks for source file references
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. -- Álvaro Herrera 48°01'N 7°57'E — https://www.EnterpriseDB.com/
Re: 31.7.1. Initial Snapshot
On 2023-Oct-11, PG Doc comments form wrote: > The following documentation comment has been logged on the website: > > Page: https://www.postgresql.org/docs/16/logical-replication-architecture.html > Description: > > There are dublicated section named "31.7.1. Initial Snapshot" on > https://www.postgresql.org/docs/16/logical-replication-architecture.html Yeah, that looks a bit ugly ... but actually the first line you see with that text is the table-of-contents for the page. Since there's a single section in that chapter, the TOC looks like a section title. You can probably find several pages in the docs where this happens. Maybe a fix for this would be to style chapter TOCs in some way that makes it clear that they are TOCs -- for example, add a (subtly) visible bounding box, or something. Or maybe if a chapter has a single section, just do not print the TOC at all. I have no idea how to implement such a fix, or whether it'd be really acceptable after all. -- Álvaro Herrera PostgreSQL Developer — https://www.EnterpriseDB.com/ "After a quick R of TFM, all I can say is HOLY CR** THAT IS COOL! PostgreSQL was amazing when I first started using it at 7.2, and I'm continually astounded by learning new features and techniques made available by the continuing work of the development team." Berend Tober, http://archives.postgresql.org/pgsql-hackers/2007-08/msg01009.php
Re: 31.7.1. Initial Snapshot
On 2023-Oct-11, David G. Johnston wrote: > Or move 4 paragraphs of introductory material into its own section so that > there are two sections and a brief sentence for an intro. We have lots of other places where this (single-entry TOCs) happens. I don't think we want to add spurious tags in all those places is going to be a good idea. > I don't see a special case for a single section to be a productive use of > time. Well, it's the only case where it's not obvious what is going on, but I agree it's not a great fix -- maybe we have some place where the introductory material is very long and the first section is several pagefuls below, and not having a TOC in that case wouldn't be great. > Improved formatting overall for the chapter ToC has merit. Great ... -- Álvaro Herrera 48°01'N 7°57'E — https://www.EnterpriseDB.com/ "Crear es tan difícil como ser libre" (Elsa Triolet)
Re: SP-GiST confusing introductory paragraph
On 2023-Oct-16, PG Doc comments form wrote: > I'm confused by this paragraph: > > > These popular data structures were originally developed for in-memory > > usage. In main memory, they are usually designed as a set of dynamically > > allocated nodes linked by pointers. This is not suitable for direct storing > > on disk, since these chains of pointers can be rather long which would > > require too many disk accesses. In contrast, disk-based data structures > > should have a high fanout to minimize I/O. The challenge addressed by > > SP-GiST is to map search tree nodes to disk pages in such a way that a > > search need access only a few disk pages, even if it traverses many nodes. > > In particular, "These popular datastructures" is ambiguous -- based on how > the previous paragraph ends, it sounds like the "popular datastructures" or > SP-GiSTs, but then it goes on to say they were designed for in-memory, and > then it mentions that SP-GiST's space partitioning (with high fanout) is > more appropriate to minimize disk access. I think maybe the solution here > would be to replace "These popular data structures" with something like > "Classic Postgres indexes such as B-tree indexes..." or something like > that. Yeah, this paragraph is a rewording of Oleg's[1] SP-GiST is an abbreviation of space-partitioned GiST - the search tree, which allows to implement a wide range of different non-balanced disk-based data structures, such as quadtree, kd-tree, tries - popular data structures, originally developed for memory storage. Main memory access structures usually designed as a set of dynamically allocated nodes linked by pointers, which is not suitable for direct storing on disk, since these chains of pointers can be rather long and require too many disk accesses. In opposite, disk based data structures have a high fanout to minimize I/O. The challenge is to map nodes of tree to disk pages in such a way, so search algorithm accesses only a few disk pages, even if it traverse many nodes. where the point is (IMO) much clearer. [1] http://www.sai.msu.su/~megera/wiki/spgist_dev > Also, I think a short parenthetical definition of "fanout" would be useful > here, something like "high fanout (i.e. where each node has a potentially > large number of child nodes that reside in the same disk page)". Took me > some googling to realize what fanout meant in this context. Hmm. We also use the term (hypenated as fan-out) in the reference to recursive_worktable_factor. Maybe we should list it in the glossary in a way that works for both. -- Álvaro Herrera PostgreSQL Developer — https://www.EnterpriseDB.com/ "La primera ley de las demostraciones en vivo es: no trate de usar el sistema. Escriba un guión que no toque nada para no causar daños." (Jakob Nielsen)
Re: add new acronym "AM"
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 + 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 . -- Álvaro Herrera PostgreSQL Developer — https://www.EnterpriseDB.com/ Si no sabes adonde vas, es muy probable que acabes en otra parte.
Re: [DOCS] Add example about date ISO format
On 2023-Nov-22, Laurenz Albe wrote: > I think the example had best be at "8.5.2. Date/Time Output", in > doc/src/sgml/datatype.sgml around line 2552. Actually, isn't that a strange location? Chapter 8.5.2 is about the datatype itself, and there's already a cross-link to Section 9.8 for to_char() stuff. Since this is to_char() that the example wants to add, I think the to_char reference is a more appropriate place -- probably table "9.31 to_char Examples". (While scrolling the 9.6 version of this page[1] I noticed that, in dark mode, the box becomes unreadable because of white text on yellowish background. Not sure what's an appropriate fix for that, if any; current versions don't have that problem. Maybe it's better to leave it alone.) [1] https://www.postgresql.org/docs/9.6/functions-formatting.html -- Álvaro Herrera 48°01'N 7°57'E — https://www.EnterpriseDB.com/ "Porque francamente, si para saber manejarse a uno mismo hubiera que rendir examen... ¿Quién es el machito que tendría carnet?" (Mafalda)
Re: [DOCS] Add example about date ISO format
On 2023-Nov-27, Erik Wienhold wrote: > Two issues that I fixed in the attached patch: > > * it's called "extended format" not "T format" (the "T" is mandatory > anyway) +1 > * the time zone was missing from the result output This is wrong. Actually, there's no timezone in value, because the use of the AT TIME ZONE operator makes the type be TIMESTAMP WITHOUT TIME ZONE. You would notice this if you were to change the incorrect literal Z in your format string with "TZ" (which expands to empty), with "OF" (which expands to "+00"), or with "TZH:TZM" (which expands to the full timezone shift): # select to_char(current_timestamp at time zone 'America/Santiago', '-MM-DD"T"HH24:MI:SSTZ'); to_char ─ 2023-11-27T11:14:55 =# select to_char(current_timestamp at time zone 'America/Santiago', '-MM-DD"T"HH24:MI:SSOF'); to_char 2023-11-27T11:14:55+00 =# select to_char(current_timestamp at time zone 'America/Santiago', '-MM-DD"T"HH24:MI:SSTZH:TZM'); to_char ─── 2023-11-27T11:14:55+00:00 The final Z in your example just prints a literal Z. (America/Santiago is UTC-3 currently, not 0, which you would see like this: =# set timezone to 'America/Santiago'; =# select to_char(current_timestamp, '-MM-DD"T"HH24:MI:SSOF'); to_char 2023-11-27T11:21:37-03 ) -- Álvaro HerreraBreisgau, Deutschland — https://www.EnterpriseDB.com/ "The Gord often wonders why people threaten never to come back after they've been told never to return" (www.actsofgord.com)
Re: CONCURRENTLY in example of index of partitioned table
On 2023-Nov-27, Nikolay Samokhvalov wrote: > https://www.postgresql.org/docs/current/ddl-partitioning.html provides an > example of using CONCURRENTLY for index creation of partitioned tables; but > it the example itself doesn't have this word; here is a fix: You're right, my mistake. Will push shortly. -- Álvaro Herrera PostgreSQL Developer — https://www.EnterpriseDB.com/
Re: "name" vs "alias" in datatype table
On 2023-Nov-29, Tom Lane wrote: > Eric Hanson writes: > > The larger point being, the "name" vs "alias" paradigm presented in this > > table does not accurately represent PostgreSQL, and conveys an inaccurate > > picture of the relationship between type names. int4 is not an "alias". > > I agree that this could be improved, mainly because it's far from > clear what the internal name of each type is (and there's at least > one case where the internal name is not shown at all). Maybe we could split this into multiple *tables*. The main one would be what we already have except the aliases column is removed, and serial types removed; the second table would list serial pseudo-types, without aliases; the third one would have unofficial names (internal names and other aliases) for types listed in the other two. -- Álvaro Herrera 48°01'N 7°57'E — https://www.EnterpriseDB.com/ "The ability of users to misuse tools is, of course, legendary" (David Steele) https://postgr.es/m/11b38a96-6ded-4668-b772-40f992132...@pgmasters.net
Re: Spam complaint
On 2024-Jan-24, Laurenz Albe wrote: > For months now, I have received this automated reply whenever I post to > this list: Yeah, me too -- the oldest I can find is 27th November last year, but it's quite possible that I deleted older ones without leaving traces. I unsubscribed this address now, thanks. -- Álvaro HerreraBreisgau, Deutschland — https://www.EnterpriseDB.com/ "Las navajas y los monos deben estar siempre distantes" (Germán Poo)
Re: SQL command : ALTER DATABASE OWNER TO
On 2024-Jan-24, Laurenz Albe wrote: > The permissions are transferred to the new owner, so the old owner doesn't > have any privileges on the object (and, in your case, cannot connect to > the database any more). However, if the old owner had a pg_hba.conf line that allowed them in, and the new owner doesn't, then they're now both locked out of the database with no recourse. -- Álvaro Herrera PostgreSQL Developer — https://www.EnterpriseDB.com/ "You don't solve a bad join with SELECT DISTINCT" #CupsOfFail https://twitter.com/connor_mc_d/status/1431240081726115845
Re: Broken link
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/ -- Álvaro Herrera PostgreSQL Developer — https://www.EnterpriseDB.com/ "I think my standards have lowered enough that now I think 'good design' is when the page doesn't irritate the living f*ck out of me." (JWZ)
Re: Non-blocking synchronization in libpq using pipeline mode
On 2024-Mar-06, PG Doc comments form wrote: > The following documentation comment has been logged on the website: > > Page: https://www.postgresql.org/docs/16/libpq-pipeline-mode.html > Description: > > The calls to PQpipelineSync and PQsendFlushRequest may either report failure > or success, but not that data could not be written as of yet because the > request would block. Is this a literal quote? If so, where do you see it? > Does this mean that > > 1. these functions will always block when invoked and the socket is not > ready to accept the number of bytes that need to be written (assuming the > number of bytes required to be written is greater than one byte) No. > 2. the synchronization or flush request need to be flushed manually with > successive PQflush calls Yes. > or > > 3. the functions will return an error condition when the connection is > non-blocking and no data could be written. No. > Any clarification in the documentation would be appreciated. So I checked https://www.postgresql.org/docs/16/libpq-pipeline-mode.html and it has this, under PQsendFlushRequest: The server flushes its output buffer automatically as a result of PQpipelineSync being called, or on any request when not in pipeline mode; this function is useful to cause the server to flush its output buffer in pipeline mode without establishing a synchronization point. Note that the request is not itself flushed to the server automatically; use PQflush if necessary. which I think answers what you are asking. -- Álvaro HerreraBreisgau, Deutschland — https://www.EnterpriseDB.com/ "Just treat us the way you want to be treated + some extra allowance for ignorance."(Michael Brusser)
Re: wal_init_zero / wal_recycle
On 2024-Apr-24, Peter Eisentraut wrote: > On 24.04.24 10:08, Nicolas Seinlet wrote: > > It was not crystal clear to me that when wal_recycle is also ON , the > > recycled files are not filled with zeroes, because they are not > > considered as new. Could we add a sentence stating this? > > It currently says: > > wal_init_zero: "... causes new WAL files to be filled with zeroes ..." > > wal_recycle: "... avoiding the need to create new ones ..." > > I'm not sure where exactly to make that more clear. It may be too subtle. Maybe we could add a note at the end: wal_init_zero (boolean) If set to on (the default), this option causes new WAL files to be filled with zeroes. On some file systems, this ensures that space is allocated before we need to write WAL records. However, Copy-On-Write (COW) file systems may not benefit from this technique, so the option is given to skip the unnecessary work. If set to off, only the final byte is written when the file is created so that it has the expected size. >>Note that recycled WAL files are for these purposes not considered new.<< -- Álvaro Herrera PostgreSQL Developer — https://www.EnterpriseDB.com/ "Pero la cosa no es muy grave ..." (le petit Nicolas -- René Goscinny)
Re: nested tags in glossary entries in html docs
On 2024-Apr-12, Erik Wienhold wrote: > There's this bug[1] in the DocBook XSLT stylesheets. Looks like the > fix[2] landed in 1.79.2 (latest version on Arch, Maybe one of these days we should get going with the migration to Docbook 5.x that Jürgen Purtz proposed. https://postgr.es/m/21ed3fd9-9020-4b53-b04f-a08a831b6...@purtz.de In the meantime, if anyone wants to suggest a XSLT patch to carry in our local definition, we could try that. -- Álvaro HerreraBreisgau, Deutschland — https://www.EnterpriseDB.com/ "The Gord often wonders why people threaten never to come back after they've been told never to return" (www.actsofgord.com)
Re: nested tags in glossary entries in html docs
On 2024-Apr-25, Jürgen Purtz wrote: > Great recommendation. I may have time in the second half of June to > pursue the migration further. There is a performance problem, which > possibly results from our XSLT script that optimizes the > transformation-speed and works well in 4.x. Maybe a way to study this is to time a run with those speedups removed and see if the timing with DocBook 5.2 matches. If it does, that's a sign that forward-porting the speedup tweaks may be worthwhile. -- Álvaro Herrera PostgreSQL Developer — https://www.EnterpriseDB.com/ "On the other flipper, one wrong move and we're Fatal Exceptions" (T.U.X.: Term Unit X - http://www.thelinuxreview.com/TUX/)
Re: nchar is undocumented
On 2024-May-05, David Rowley wrote: > On Sun, 5 May 2024 at 12:41, Erik Wienhold wrote: > > So, I think we should either remove that one nchar instance (because it > > doesn't add any real value) or document it properly. The attached patch > > does the latter. > > It seems easier to do the former, that way we don't need to reconsider > Peter's concerns about not having enough confidence that it matches > the standard. > > I've included Alvaro and Peter to see what they think. Yeah, I too am inclined to remove it. This text was initially written by Mantrova, Bartunov and Glukhov and posted in [1] without further explanation, from where it was copied by Glukhov into [2]; the one I committed is a direct derivate from that. There was no discussion about nchar specifically that I can see, and at least I simply failed to realize that nchar was not something that we talk about. I'll remove it from the list, and backpatch to 16. [1] https://postgr.es/m/732208d3-56c3-25a4-8f08-3be1d54ad...@postgrespro.ru [2] https://postgr.es/m/8c1ba295-fa42-d4f2-a155-76cf3327d...@postgrespro.ru % If you, Erik, want to spend some time thinking through the standard definition of NCHAR and whether we conform, perhaps we can document it more fully. -- Álvaro Herrera 48°01'N 7°57'E — https://www.EnterpriseDB.com/ "Java is clearly an example of money oriented programming" (A. Stepanov)
Re: nchar is undocumented
By the way, this neighboring sentence is a bit awkward " It must be ... or a type for which there is a cast from json to that type." Would it be better to say " It must be ... or a type to which a cast from json exists." ? -- Álvaro Herrera 48°01'N 7°57'E — https://www.EnterpriseDB.com/ "La espina, desde que nace, ya pincha" (Proverbio africano)
Re: 28.4.4. Progress Reporting phase status
On 2024-Jun-03, Euler Taveira wrote: > On Thu, May 30, 2024, at 12:50 PM, PG Doc comments form wrote: > > I noticed that in "28.4.4. Progress Reporting" chapter for > > `pg_stat_progress_create_index`, the "Table 28.43. CREATE INDEX Phases" may > > be misleading as phase displayed for "building index" is often more > > detailed. > > I found in this presentation[1] (slide 20) what seems to be the exact status > > displayed by the table while creating the index. > > Maybe documentation table displaying all status could be extended to display > > the following status: > > The description is accurate. Since this step (building index) is AM-specific, > it > shouldn't contain the additional information (after the semicolon). However, maybe Eve is right that we should have these steps: > > - building index: initializing [2] > > - building index: scanning table > > - building index: sorting live tuples > > - building index: sorting dead tuples > > - building index: loading tuples in tree somewhere in the AM-specific doc pages, https://www.postgresql.org/docs/devel/btree.html and perhaps we can link to that from the progress-report chapter. (Not really related, but: I think the per-index-AM subsections in https://www.postgresql.org/docs/devel/indexes-types.html should have forward-links to the appendix sections on them.) > You can certainly obtain the build phases from all access > methods with a query like: > > WITH amidx AS ( > SELECT oid, amname FROM pg_am WHERE amtype = 'i') > SELECT a.amname, pg_indexam_progress_phasename(a.oid, i) > FROM amidx a, generate_series(0, 100) i > WHERE pg_indexam_progress_phasename(a.oid, i) IS NOT NULL > ORDER BY a.amname, i; Heh, only btrees show up there. Sad. I wonder to what extent would it be useful for the other index AMs to report sub-phases of index creation. It should be pretty simple to implement ... -- Álvaro HerreraBreisgau, Deutschland — https://www.EnterpriseDB.com/ "La gente vulgar sólo piensa en pasar el tiempo; el que tiene talento, en aprovecharlo"
Re: 8.12. UUID Type
On 2024-Jun-13, Laurenz Albe wrote:
> On Thu, 2024-06-13 at 08:59 +, PG Doc comments form wrote:
> > Page: https://www.postgresql.org/docs/16/datatype-uuid.html
> > Description:
> >
> > Is this the right sentence? "use of upper-case digits"
> > > > PostgreSQL also accepts the following alternative forms for input: use
> > > > of upper-case digits
>
> Hexadecimal digits, also known as letters.
Everybody knows that ! is an uppercase 1, right?
/s
--
Álvaro Herrera 48°01'N 7°57'E — https://www.EnterpriseDB.com/
#error "Operator lives in the wrong universe"
("Use of cookies in real-time system development", M. Gleixner, M. Mc Guire)
Re: Incorrect grammar in 15.2
On 2024-Jul-24, Laurenz Albe wrote: > Here is a patch for that; it may be the smallest patch I've ever > written for PostgreSQL. Thanks, applied. -- Álvaro Herrera 48°01'N 7°57'E — https://www.EnterpriseDB.com/ "Investigación es lo que hago cuando no sé lo que estoy haciendo" (Wernher von Braun)
Re: nchar is undocumented
On 2024-May-06, Erik Wienhold wrote: > On 2024-05-06 10:59 +0200, Alvaro Herrera wrote: > > By the way, this neighboring sentence is a bit awkward > > > > " It must be ... or a type for which there is a cast from json to that > > type." > Or maybe just > "[...] or any type that can be cast to json." > ? WFM, thanks, pushed. -- Álvaro Herrera 48°01'N 7°57'E — https://www.EnterpriseDB.com/
Re: remove endterms and title ids
Peter Eisentraut wrote: > The attached patch removes endterm attributes from xref elements and the > associated id attributes on title elements. > > Older documentation toolchains could not automatically generate text for > xrefs into refentries, so we had to use the endterm attribute to tell it > which text to create. This is no longer necessary and can be removed. > In most cases, we can just rely on the automatically generated text. So we had There are several caveats to be aware of when using this option — see _Building Indexes Concurrently_. and with this patch we end up with There are several caveats to be aware of when using this option — see _the section called “Building Indexes Concurrently”_. which looks pretty ugly to me. I think getting rid of the mostly-pointless id attributes is a good motivation, but I wonder if there's a way to retain the text as originally generated. -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: remove endterms and title ids
Can we have it emit something like see section 4.5.3 “Building Indexes Concurrently” by customizing the stylesheets? I tried to figure out where the text is emitted, but 'sectioncalled' does not appear in greps anywhere in the docbooc-xsl dir. -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: Is this still accurate?
Steve Atkins wrote: > It's been useful a few times to reassure people that we can handle "large" > databases operationally, rather than just having large theoretical limits. > > Updating it would be great, or wrapping a little more verbiage around the > 4TB number, but a mild -1 on removing it altogether. I'd just add a 0 to "40TB" and be done with it. We have larger databases but this is a decent enough number. -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: Advice on Contiguous IDs
Brian McKiernan wrote: > My Issue: > My primary keys in a certain table are not contiguous. If you have a need to have values that are contiguous, you need to ask yourself why and then see what mechanism provides the semantics you need. An easy way is to lock the table containing the column, for example, which of course means only one transaction can do it at a time. For many use cases this is good enough. -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: What does "Table rewrite" mean?
Michael Paquier wrote: > On Fri, Jan 19, 2018 at 11:33:43AM -0500, Tom Lane wrote: > > It means reading the whole table and writing it out in some modified > > form (for instance, with some column transformed into a new datatype). > > It's not "dangerous" in any way ... but if you've got many GB of data in > > the table and you can't afford to have the table locked for a long time, > > then it's something to avoid. > > Yeah that can be costly. Note that WAL corresponding to this data needs > to be generated as well. Maybe we need to document this somewhere, particularly now that we have a "table_rewrite" event item. -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: Documentation of EXCEPT ALL may have a bug
PG Doc comments form wrote: > create table t(x int); > create table u(x int); > > insert into t values (1), (2), (2), (3), (3); > insert into u values (1), (2); > > select * from t except all select * from u; > x > --- > 3 > 3 > 2 > (3 rows) I find this pretty odd behavior. Is this not an outright bug? I haven't read the SQL standard on this matter[*], but if they define EXCEPT ALL to work like this, then it seems pretty useless. (Maybe they just didn't intend EXCEPT ALL to be useful?) If this is indeed the case, maybe we should amend the docs not only to explain this behavior but also to warn against the construct. [*] I didn't try terribly hard, but couldn't actually find where the behavior is defined. What I have on hand is a draft of SQL:2011 where this appears to be defined in 7.13 but I was unable to find the rules for set operations. It refers to 9.12 Grouping operations but that defines conformance rules only. -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: Images in the official documentation
Peter Eisentraut wrote: > On 2/26/18 20:02, Craig Ringer wrote: > > If I were maintaining the docs in a vacuum, I'd use graphviz for > > something like that, because it's a figure that does need regular > > updates and changes. And because > > the list of fun things to do in my life definitely does not include > > hand-writing SVG. Not that tweaking GraphViz .dot is fun, but it's the > > default tool for a reason. > > > > I'd be awfully tempted to generate the node-map part of the catalog > > relationship .dot file from a query, too. > > I think graphviz would be a great fit for what we are discussing here. > Certainly more so then some-person-on-github's latest idea for how to > convert ASCII art into diagrams. ... particularly so if said idea involves PHP, Haskell, Go, Python, or any other language that we don't currently have as requirement in our build chain. GraphViz gets my vote, too. It may not produce the most elegant diagrams in the universe, but the source format is as good as we can get. -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: Dead link in ltree documentation
David G. Johnston wrote: > I'm not seeing the value in providing a link, especially one that we don't > control, here. Futhermore, we could probably drop the whole "In > practice..." sentence. But if not at least put a period after "limitation" > and drop the example and link. +1 remove the sentence. -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: Documentation for CommandComplete is incorrect for CREATE TABLE with server version 10.2
PG Doc comments form wrote: > The documentation says: > > For a SELECT or CREATE TABLE AS command, the tag is SELECT rows where rows > is the number of rows retrieved. > > But what I get back from the server is this packet: > > 43 00 00 00 11 43 52 45 41 54 45 20 54 41 42 4c CCREATE TABL > 0010 45 00E. > > The query I sent to the server was: > > create table table1(i int) Yeah, this is not a CREATE TABLE AS. It's a plain CREATE TABLE. Different thing. alvherre=# create table dcm as select 'foo'; SELECT 1 -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: Request: Revive the security-specific section
Peter Eisentraut wrote: > On 5/2/18 18:59, Ian Maddox wrote: > > It appears that the knowledge from that page has been redistributed > > across the manual in versions 8+, making it difficult to point to a > > single authoritative resource. I'm writing to request that a single > > section on security be revived in a future revision of the manual. > > I see where you are coming from. However, I think security concerns > exist in every aspect of the system. So as a user when I'm dealing > with operating system integration, or schema design, or backups, or > replication, or monitoring, etc., then I want to know about the > security concerns on that subject. Curiously enough, we got a request on the Spanish list today https://www.postgresql.org/message-id/calhqua6tay+b+oh10oom24sank43quqovnozppdo5r6yq4e...@mail.gmail.com about a "hardening guide". I think it is not completely out of the question to have a separate slim section listing things to keep in mind in order to harden a PostgreSQL installation. It doesn't have to be terribly thorough -- rather it'd be mostly links to other places in the docs where detailed information about each element can be found. -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: Mistakes between an example and its description
Eugene Wang wrote: > Unique Constraint and Unique Index should be the same in this single-column > case, right? > > Because, according to CONSTRAINT page in Postgres Documentation, Unique > Constraint on single column is realized as Unique B-TREE index. > > I have just realized that it is still a btree index, but I think this > example is not exactly a regular btree example. At least I will put the > example as: CREATE INDEX title_idx ON films USING BTREE(title); Yeah, I see no point for having UNIQUE in that example. -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: Table 28.4. wait_event description typo
On 2018-May-30, Michael Paquier wrote: > > ClientRead Waiting to read data from the client. > > ClientWrite Waiting to write data from the client. > > ... > > ^ > > It should state TO CLIENT. > > Good catch. It seems that this is my fault as what has been done in > 6f3bd98. So let's update the docs as you suggest, the attached does so > FWIW. I do not think that patch does what you think it does. -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: Table 28.4. wait_event description typo
On 2018-May-30, Michael Paquier wrote: > On Wed, May 30, 2018 at 01:30:08PM -0400, Alvaro Herrera wrote: > > I do not think that patch does what you think it does. > > Oops. Sorry another patch got on the way. Here you go. Okay, pushed. Because of the sgml to xml conversion, it didn't apply to pg10 cleanly. -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: [DOCS] XMLTABLE default namespace in docs
On 2017-Sep-11, Daniel Gustafsson wrote: > When reviewing Pavels patch for default namespace in XMLTABLE, I came across > this sentence in the devel (and 10beta) docs in subsection 9.14.3.3. xmltable: > > The following example illustrates how the XMLNAMESPACES clause can be > used to specify the default namespace, and a list of additional > namespaces used in the XML document as well as in the XPath > expressions: > > That seems odd since we don’t support default namespaces (hence the patch for > adding it). Am I reading it wrong, or shouldn’t we apply something like the > attached for now? You're right, we should -- thanks for noticing. I have pushed it now. -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
PDF build warnings
When doing a test run of the PDF docs for beta2 on borka, I noticed that the build finishes with this -- is it expected? [WARN] FOUserAgent - Destination: Unresolved ID reference "ecpg-type-timestamp-date" found. [WARN] FOUserAgent - Destination: Unresolved ID reference "sql-altercollation-notes-title" found. [WARN] FOUserAgent - Destination: Unresolved ID reference "sql-commit-prepared-examples-title" found. [WARN] FOUserAgent - Destination: Unresolved ID reference "sql-createaggregate-notes-title" found. [WARN] FOUserAgent - Destination: Unresolved ID reference "sql-createforeigntable-compatibility-title" found. [WARN] FOUserAgent - Destination: Unresolved ID reference "sql-createindex-storage-parameters-title" found. [WARN] FOUserAgent - Destination: Unresolved ID reference "sql-createindex-concurrently-title" found. [WARN] FOUserAgent - Destination: Unresolved ID reference "sql-createtable-storage-parameters-title" found. [WARN] FOUserAgent - Destination: Unresolved ID reference "sql-createtable-compatibility-title" found. [WARN] FOUserAgent - Destination: Unresolved ID reference "sql-createview-updatable-views-title" found. [WARN] FOUserAgent - Destination: Unresolved ID reference "sql-declare-notes-title" found. [WARN] FOUserAgent - Destination: Unresolved ID reference "sql-do-examples-title" found. [WARN] FOUserAgent - Destination: Unresolved ID reference "sql-inserting-params-title" found. [WARN] FOUserAgent - Destination: Unresolved ID reference "sql-on-conflict-title" found. [WARN] FOUserAgent - Destination: Unresolved ID reference "sql-prepare-examples-title" found. [WARN] FOUserAgent - Destination: Unresolved ID reference "sql-prepare-transaction-examples-title" found. [WARN] FOUserAgent - Destination: Unresolved ID reference "sql-rollback-prepared-examples-title" found. [WARN] FOUserAgent - Destination: Unresolved ID reference "sql-with-title" found. [WARN] FOUserAgent - Destination: Unresolved ID reference "sql-from-title" found. [WARN] FOUserAgent - Destination: Unresolved ID reference "sql-where-title" found. [WARN] FOUserAgent - Destination: Unresolved ID reference "sql-groupby-title" found. [WARN] FOUserAgent - Destination: Unresolved ID reference "sql-having-title" found. [WARN] FOUserAgent - Destination: Unresolved ID reference "sql-window-title" found. [WARN] FOUserAgent - Destination: Unresolved ID reference "sql-select-list-title" found. [WARN] FOUserAgent - Destination: Unresolved ID reference "sql-distinct-title" found. [WARN] FOUserAgent - Destination: Unresolved ID reference "sql-union-title" found. [WARN] FOUserAgent - Destination: Unresolved ID reference "sql-intersect-title" found. [WARN] FOUserAgent - Destination: Unresolved ID reference "sql-except-title" found. [WARN] FOUserAgent - Destination: Unresolved ID reference "sql-orderby-title" found. [WARN] FOUserAgent - Destination: Unresolved ID reference "sql-limit-title" found. [WARN] FOUserAgent - Destination: Unresolved ID reference "sql-for-update-share-title" found. [WARN] FOUserAgent - Destination: Unresolved ID reference "clusterdb" found. [WARN] FOUserAgent - Destination: Unresolved ID reference "pg-dump-examples-title" found. [WARN] FOUserAgent - Destination: Unresolved ID reference "app-psql-patterns-title" found. [WARN] FOUserAgent - Destination: Unresolved ID reference "app-psql-variables-title" found. [WARN] FOUserAgent - Destination: Unresolved ID reference "app-psql-interpolation-title" found. [WARN] FOUserAgent - Destination: Unresolved ID reference "app-psql-prompting-title" found. [WARN] FOUserAgent - Destination: Unresolved ID reference "app-psql-environment-title" found. [WARN] FOUserAgent - Destination: Unresolved ID reference "app-psql-examples-title" found. [WARN] FOUserAgent - Destination: Unresolved ID reference "reindexdb" found. [WARN] FOUserAgent - Destination: Unresolved ID reference "vacuumdb" found. [WARN] FOUserAgent - Destination: Unresolved ID reference "app-postgres-single-user-title" found. [WARN] FOUserAgent - Destination: Unresolved ID reference "postmaster-ref" found. [WARN] FOUserAgent - Destination: Unresolved ID reference "csvlog-fdw" found. Commit 1d4e5edc1dc22f00a0abb00ed9b56c08c4a1f599 produced US 11 PDF docs pgsql@borka:~$ -- Álvaro Herrera
Re: Dead link to hp docs
On 2018-Jul-02, Michael Paquier wrote: > Here are all the broken links in the source tree: > > doc/src/sgml/libpq.sgml: > Wrong: http://h71000.www7.hp.com/doc/83final/ba554_90007/ch04.html > Correct: http://h41379.www4.hpe.com/doc/83final/ba554_90007/ch04.html > > doc/src/sgml/runtime.sgml: > Wrong: http://h71000.www7.hp.com/doc/83final/ba554_90007/ch04s02.html > Correct: http://h41379.www4.hpe.com/doc/83final/ba554_90007/ch04s02.html I think HP break their site on a regular basis. Maybe we should be looking for some more stable source of similar information? I can't believe that OpenVMS programming manuals are the best possible source of SSL information. -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: Release note trimming: another modest proposal
On 2018-Aug-06, Tom Lane wrote: > OTOH, if we can easily set up a generic redirect rule like "if > https://www.postgresql.org/docs/*/static/release-*.html > doesn't exist, then redirect to > https://www.postgresql.org/docs/old-release-notes/static/release-*.html"; > it might be worth doing. Yeah I'm pretty sure we can do that. I'm not sure how many people rely on this, but it seems useful to keep HTML-rendered relnotes for all versions (rather than require people to read SGML source). I don't think we need PDFs though ... -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
retroactive pg10 relnotes: sequence changes
Hello A customer of ours was taken by surprise by a change in Postgres 10 on a trial upgrade from 9.6. They were using sequences from SERIAL columns a little unorthodoxly, and their stuff stopped working: essentially, they hacked the default expression so that it'd automatically use negative numbers when the sequence reached INT_MAX. Since pg10 changed sequences to stop emitting values at that point, it raised an error rather than emit the negative numbers. (In 9.6 and prior, the sequence would emit values past INT_MAX; it was the column that raised the error. In pg10 things were changed so that it is now the sequence that raises the error.) My proposal now is to document this issue in the Postgres 10 release notes. "It's a little late for that!" I hear you say, but keep this in mind: many users have *not* yet upgraded to 10, and they'll keep doing it for years to come still. So I disagree that now is too late. We failed to warn people that already upgraded, but we're still on time to alert people yet to upgrade. I attach both the patch and a screenshot to show how minor the visual effect of the change is. (If people hate this, another option is to make it a separate bullet point.) -- Álvaro Herrera diff --git a/doc/src/sgml/release-10.sgml b/doc/src/sgml/release-10.sgml index 968ed866c2..f1dc816278 100644 --- a/doc/src/sgml/release-10.sgml +++ b/doc/src/sgml/release-10.sgml @@ -4717,6 +4717,13 @@ Branch: REL_10_STABLE [5159626af] 2017-11-03 14:14:16 -0400 + Also, sequences created for SERIAL columns now + generate positive 32-bit wide values rather than 64-bit, as they + used to. (This has no visible effect if the values are just stored in + the column.) + + + The output of psql's \d command for a sequence has been redesigned, too.
Re: retroactive pg10 relnotes: sequence changes
On 2018-Aug-28, Jonathan S. Katz wrote: > I have attached patch where I suggested some alternate wording and > remove the parenthetical comment, as I don’t believe that should be > an aside. Cool, thanks. I have pushed it with your proposed wording. -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: Incorrect description of autovacuum_vacuum_threshold and autovacuum_vacuum_scale_factor
On 2018-Sep-27, PG Doc comments form wrote: > Page: https://www.postgresql.org/docs/10/static/runtime-config-autovacuum.html > > This page lists the different autovacuum options. Describing > autovacuum_vacuum_threshold and autovacuum_vacuum_scale_factor independently > adds confusion unless you are also reading > https://www.postgresql.org/docs/10/static/routine-vacuuming.html#AUTOVACUUM > where we have a formula for the threshold and scale factor. True. > I suggest adding a reference for each one of the two parameters with a link > to the "Routine Vacuuming" section. I suggest adding "This number is added to the number coming from the autovacuum_vacuum_scale_factor parameter for each table" just before the "This parameter can only be set" phrase. So we'd end up with this: autovacuum_vacuum_threshold (integer) Specifies the minimum number of updated or deleted tuples needed to trigger a VACUUM in any one table. The default is 50 tuples. This number is added to the number coming from the autovacuum_vacuum_scale_factor parameter for each table. This parameter can only be set in the postgresql.conf file or on the server command line; but the setting can be overridden for individual tables by changing table storage parameters. autovacuum_vacuum_scale_factor (floating point) Specifies a fraction of the table size to add to autovacuum_vacuum_threshold when deciding whether to trigger a VACUUM. The default is 0.2 (20% of table size). This number is added to the autovacuum_vacuum_threshold parameter for each table. This parameter can only be set in the postgresql.conf file or on the server command line; but the setting can be overridden for individual tables by changing table storage parameters. Same for the analyze parameters. I suppose we don't need any updates to the section of https://www.postgresql.org/docs/10/static/sql-createtable.html that explains the equivalent reloptions, since those ones are very succint anyway. -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: Proposed HTML Documentation Styles
On 2018-Oct-04, Pavel Stehule wrote: > čt 4. 10. 2018 v 17:50 odesílatel Jonathan S. Katz > napsal: > > When I am going to document, then I see (about 0.5 sec) big PostgreSQL > logo. It is not pleasant effect. > > I don't like table style - middle vertical line is too black > > Used colour palette is maybe too red based. Yeah, it's heavily red and I didn't like that very much either, though I can live with it if everyone else loves it. This TOC looks a bit odd, with those bold black elements amongst all that red: http://174.138.60.30/docs/10/static/ecpg.html I suppose these should just be bold without changing the color. This page http://174.138.60.30/docs/9.4/static/libpq-connect.html has some keywords inside "Warning" and "Note" boxes. Those keywords acquire a gray background instead of inheriting the background color of the box, as in the original stylesheets. Really odd-looking. Cheers -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: Proposed HTML Documentation Styles
On 2018-Oct-22, Liudmila Mantrova wrote: > I have noticed a small rendering issue in the Chrome browser. If you follow > a link to a bookmark in a different page, it's hidden below the website > header. Links within the same page and section-level links appear to work > fine. Yeah, I see this effect too and it's very confusing. -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: effective_cache_size
On 2018-Nov-05, Bruce Momjian wrote:
> Well, here are the lines in guc.c:
>
> gettext_noop("Sets the planner's assumption about the size of the
> data cache."),
> gettext_noop("That is, the size of the cache used for PostgreSQL
> data files. "
> "This is measured in disk pages, which are normally
> 8 kB each."),
I suggest "the size of data caches", plural, in the first line (two
letters shorter, since I lost the article). And in the second line, use
"... the size of the combined caches used for Pg data files, including
both the kernel cache and shared buffers" -- a few words longer, which
seems worth it to me.
--
Álvaro Herrerahttps://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: typo in parallel safety doc
On 2018-Aug-17, Thomas Munro wrote: > On Fri, Aug 17, 2018 at 1:12 PM, Justin Pryzby wrote: > > I dearly hope this was intentional ;) > > > > commit 96e98fa2606b2b12805db99196f468152312af14 > > Author: Thomas Munro > > Date: Fri Aug 17 11:32:55 2018 +1200 > > > > Proof-reading for documentation. > > > > Somebody accidentally a word. Back-patch to 9.6. > > > > Reported-by: Justin Pryzby > > Discussion: https://postgr.es/m/20180816195431.GA23707%40telsasoft.com > > It is not the most advanced form of humour, but yes :-) https://knowyourmeme.com/memes/i-accidentally -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: Documentation for create unique index is insuficient and (because of that) incorrect
On 2018-Nov-20, Jonathan S. Katz wrote: > On 11/19/18 9:05 PM, Bruce Momjian wrote: > > On Tue, Oct 23, 2018 at 06:29:55PM +, PG Doc comments form wrote: > >> The following documentation comment has been logged on the website: > >> > >> Page: https://www.postgresql.org/docs/11/static/indexes-unique.html > >> Description: > >> > >> In https://www.postgresql.org/docs/11/static/indexes-unique.html there are > >> omited clausules > >> > >> For example WHERE clausule is omited. > >> > >> In https://www.postgresql.org/docs/11/static/sql-createindex.html you can > >> see the right sintax with all the clausules. > > > > The first URL is an example and is not intended to be the complete > > syntax. I think the OP should take a lengthier look at the whole of chapter 11 instead of looking at just one individual section within it. It's the whole chapter that should include details about other indexing features -- and indeed the WHERE clause is described in 11.8 Partial Indexes. Describing every feature within the section for every other feature would be disastrous. > In fairness, the "INCLUDE" clause was added, which is new to PostgreSQL > 11, so it could raise the question as to why aren't other clauses there. IMO that's actually a bug -- the INCLUDE clause should have gotten its own section in chapter 11 instead of being mentioned in the section about unique indexes. -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: Documentation for create unique index is insuficient and (because of that) incorrect
On 2018-Nov-20, Tom Lane wrote: > So what I think I should do is reformulate that discussion to talk > about making covering indexes with INCLUDE, and then mention in > passing that you can also do it without that as long as you don't mind > the payload columns being part of the index semantics. That seems sensible. > I'm also wondering whether to move that section someplace earlier > in chapter 11. Right now it's near the end because it's mostly > info about an implementation detail; but it wouldn't be hard to > make the argument that covering indexes are more important than, > say, indexes with custom collations. Should we move it, and if > so to where? I think right next to 11.5, which currently completes the topic of how are indexes used, is a good place. -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: First SVG graphic
On 2018-Nov-28, Bruce Momjian wrote: > On Wed, Nov 28, 2018 at 11:46:33AM -0800, Andres Freund wrote: > > Hi, > > > > On 2018-11-28 18:34:26 +0100, Jürgen Purtz wrote: > > > After one week no response at all? Neither positive nor negative. It seems > > > that the community has little interest in the SVG issue. Or in my > > > suggestion? > > > > I'd suggest describing your proposed workflow in sgml, not a pdf file. > > Well, there were a number of images in the PDF that would be harder to > do in SGML. I think the point is how do you integrate the images from the SVG source into the documentation output. Presumably that won't be PDF, for example the HTML output will not use a PDF as an image embedded in the page. It probably works ok for the PDF output (of the whole documentation) to use the PDF of the image ... I suppose the HTML output will need a PNG or such. -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: Broken link in Appendix H.3
On 2018-Dec-07, PG Doc comments form wrote: > The following documentation comment has been logged on the website: > > Page: https://www.postgresql.org/docs/9.4/external-pl.html > Description: > > At https://www.postgresql.org/docs/9.4/external-pl.html, the link to PL/Py > is broken. Specifically, the link shown is > http://python.projects.postgresql.org/backend/, which redirects to > http://python.projects.pgfoundry.org/backend/ and returns 404. I don't know > what the correct link should be, if any. I think PL/Py doesn't exist anymore. -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: Broken link in Appendix H.3
On 2018-Dec-07, Alvaro Herrera wrote: > On 2018-Dec-07, PG Doc comments form wrote: > > > The following documentation comment has been logged on the website: > > > > Page: https://www.postgresql.org/docs/9.4/external-pl.html > > Description: > > > > At https://www.postgresql.org/docs/9.4/external-pl.html, the link to PL/Py > > is broken. Specifically, the link shown is > > http://python.projects.postgresql.org/backend/, which redirects to > > http://python.projects.pgfoundry.org/backend/ and returns 404. I don't know > > what the correct link should be, if any. > > I think PL/Py doesn't exist anymore. Some digging turns up that James Pye renamed it to pg-python and moved to github https://github.com/python-postgres/be but last commit was 4 years ago to add 9.3 support, so I guess we should just remove it. (Meanwhile his Python driver continues to live.) -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: tickling the lesser contributor's withering ego
On 2018-Nov-04, Erik Rijkers wrote: > I wouldn't mind if this page: > https://www.postgresql.org/community/contributors/ > > contained a link to (contributors v11): > https://www.postgresql.org/docs/11/static/release-11.html#id-1.11.6.5.6 > > and to (contributors v10) > https://www.postgresql.org/docs/current/static/release-11.html#id-1.11.6.5.6 I propose the following patch, which will make those links stable -- then we can add the following links to the contributors page: https://www.postgresql/org/docs/10/release-10.html#RELEASE-10-ACKNOWLEDGEMENTS https://www.postgresql/org/docs/11/release-11.html#RELEASE-11-ACKNOWLEDGEMENTS -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services diff --git a/doc/src/sgml/release-10.sgml b/doc/src/sgml/release-10.sgml index aacdd360e0..c72b4c931e 100644 --- a/doc/src/sgml/release-10.sgml +++ b/doc/src/sgml/release-10.sgml @@ -8990,7 +8990,7 @@ This was disabled in the PG 9.6 branch so there is no commit here. - + Acknowledgments diff --git a/doc/src/sgml/release-11.sgml b/doc/src/sgml/release-11.sgml index f35b0d8cc9..faa5835de4 100644 --- a/doc/src/sgml/release-11.sgml +++ b/doc/src/sgml/release-11.sgml @@ -3617,7 +3617,7 @@ same commits as above - + Acknowledgments
Re: tickling the lesser contributor's withering ego
On 2018-Dec-21, Tom Lane wrote: > Alvaro Herrera writes: > > I propose the following patch, which will make those links stable -- > > then we can add the following links to the contributors page: > > https://www.postgresql/org/docs/10/release-10.html#RELEASE-10-ACKNOWLEDGEMENTS > > https://www.postgresql/org/docs/11/release-11.html#RELEASE-11-ACKNOWLEDGEMENTS > > Seems reasonable, but note the lag time --- unless somebody does > something out of the ordinary, those pages won't actually have > such tags till after the February minor releases. Good point. That seems acceptable to me. Erik, are you willing to propose a patch for the pgweb side of things? -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: Possible edit slip in Architecture Fundamentals.
On 2019-Jan-01, PG Doc comments form wrote: > This line: > The user's client (frontend) application that wants to perform database > operations. > in the Architecture > Fundamentals(https://www.postgresql.org/docs/10/tutorial-arch.html) seems > out of place or incomplete. How so? It's part of this text: A PostgreSQL session consists of the following cooperating processes (programs): * [another process] * The user's client (frontend) application that wants to perform database operations. It seems perfectly well placed to me. -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: Bug reporting guidelines order of instructions
On 2019-Jan-17, Magnus Hagander wrote: > Per the docs comment today, I will remove the notes about majordomo at > https://www.postgresql.org/docs/current/bug-reporting.html. > > However, this one also suggests email to the pgsql-bugs report as the > primary choice "and you can also use the bugs form. Do we perhaps want to > change the order of these and suggest the web form as the primary method, > since that hands out bug ids? +1. -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: First SVG graphic
On 2018-Dec-23, Jürgen Purtz wrote: > b) Is it worth to visualize PG's tree-implementation in a separate graphic - > or is it the same as in every other tree-implementation that you have > learned in your academic studies? If yes: in which chapter? Who's to say that every single reader of the PG documentation has had relevant academic studies? My opinion is that these graphics are worth including even if they're well-known to many. -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: tickling the lesser contributor's withering ego
On 2018-Dec-27, Magnus Hagander wrote: > On Fri, Dec 21, 2018 at 4:17 PM Alvaro Herrera > wrote: > > > On 2018-Dec-21, Tom Lane wrote: > > > > > Alvaro Herrera writes: > > > > I propose the following patch, which will make those links stable -- > > > > then we can add the following links to the contributors page: > > > > https://www.postgresql/org/docs/10/release-10.html#RELEASE-10-ACKNOWLEDGEMENTS > > > > https://www.postgresql/org/docs/11/release-11.html#RELEASE-11-ACKNOWLEDGEMENTS > > > > > > Seems reasonable, but note the lag time --- unless somebody does > > > something out of the ordinary, those pages won't actually have > > > such tags till after the February minor releases. > > > > Good point. That seems acceptable to me. > > Good. While it *can* be worked around, it's a PITA and it risks getting > overwritten by other things, since the normal docs loads are based off > release tarballs. We can make them off a snapshot tarball, but it's a pain > :) > > Oh, and +1 for stable links like that in general. That would be one good > step. Okay, pushed this. There's no need to do any advance publishing I think; we can wait three more weeks. We still need Erik to come up with the patch for pgweb, though :-) -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: Release note trimming: another modest proposal
On 2019-Feb-04, Andres Freund wrote: > Gah, I'd skipped this thread, because I was OK, if not happy, about the > original modest proposal (trimming to supported versions). My fault. > > For the record: I think this is a terrible idea. +1 I don't like it either. The original idea of just removing unsupported ones was fine. -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: First SVG graphic
I think we should first exhaust all options to use the currently
supported formats, before adding a new controversial one. You can use
the {s} qualifier for a box in ditaa and it'll show a disk; this ascii
diagram produces a "similar enough" image to your diagram, for example:
+++-+
| Original | pg_dump, other archive formats | Binary |
| Database |--->| File(s) |
| {s}|| {s} |
+++-+
| |
| pg_dump, script format | pg_restore
| |
v v
++ +--+
| SQL INSERT |psql | Restored |
| commands |-->| Database |
|{s} | | {s}|
++ +--+
It takes more time to write this email than to get the diagram done.
(I say "controversial" about inkscape because it was initially claimed
that the output was going to be clean/readable/diffable, and that's what
got so many upvotes. After the admission that that's not so, I suspect
votes for inkscape have decreased somewhat.)
--
Álvaro Herrerahttps://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: Mark a reloption as indexterm
On 2019-Apr-10, Fujii Masao wrote: > Hi, > > I'd like to propose to mark reloptions as indexterms, like GUC, > so that users can more easily search the pages describing > a reloption in document. Attached is the patch which does this. > Is this helpful? Thought? +1 for adding index entries to all reloptions. I'm not sure what you're achieving by splitting the text for some existing index entries in two and putting two words in the that were part of the , though. I'd just put the whole text in (obviously the option name must be the first word of that). -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: Mark a reloption as indexterm
On 2019-Apr-12, Fujii Masao wrote: > On Wed, Apr 10, 2019 at 4:11 AM Alvaro Herrera > wrote: > > > > On 2019-Apr-10, Fujii Masao wrote: > > > > > Hi, > > > > > > I'd like to propose to mark reloptions as indexterms, like GUC, > > > so that users can more easily search the pages describing > > > a reloption in document. Attached is the patch which does this. > > > Is this helpful? Thought? > > > > +1 for adding index entries to all reloptions. I'm not sure what you're > > achieving by splitting the text for some existing index entries in two > > and putting two words in the that were part of the > > , though. I'd just put the whole text in (obviously > > the option name must be the first word of that). > > Indeed. Attached is the updated version of the patch. Hmm, actually, I now see you were originally proposing the words "storage parameter" for the fillfactor index entries, but for v2 you instead copied the "configuration parameter" words that was in some other of the older entries. I think "configuration parameter" is wrong (we use that for GUCs, and it seems to me that it would be confusing to mix both things), and we should use the words "storage parameter" for all of these, don't you think? -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: Mark a reloption as indexterm
On 2019-Apr-12, Michael Paquier wrote: > On Fri, Apr 12, 2019 at 12:33:45PM +0900, Fujii Masao wrote: > > Indeed. Attached is the updated version of the patch. > > On top of what Alvaro has mentioned, it seems to me that we should > make the difference between table-level configuration parameter and > index-level configuration parameters, and also add markups > to create_index.sgml. If you take the example of fillfactor, it > applies to both indexes and tables, but with your patch you just > define "configuration parameter", and point to only CREATE TABLE. Are you suggesting that it should show "index storage parameters" and "table storage parameters"? I'm not sure about that myself ... particularly considering that certain parameters might apply to some index AMs and not others. BTW what about the index-specific options such as, say, BRIN's pages_per_range? I know other AMs have their own reloptions ... -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: Mark a reloption as indexterm
On 2019-Apr-12, Fujii Masao wrote: > OTOH, originally I thought that the following style is smarter. > > xxx > configuration parameter, XXX > storage parameter, Storage Parameter Ah. Well, I like this style. Let's do that. -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: Mark a reloption as indexterm
On 2019-Apr-16, Fujii Masao wrote: > On Sat, Apr 13, 2019 at 1:30 AM Alvaro Herrera > wrote: > > > > On 2019-Apr-12, Fujii Masao wrote: > > > > > > > OTOH, originally I thought that the following style is smarter. > > > > > > xxx > > > configuration parameter, XXX > > > storage parameter, Storage Parameter > > > > Ah. Well, I like this style. Let's do that. > > So I used tag again for the above style if both reloption > and guc with the same parameter name exist. Attached is the updated > version of the patch. This patch also marks index-reloption as indexterm. I checked the HTML output. For autovacuum it says "configuration parameters" rather than "configuration parameter". Other than that, it looks good to me. (I didn't check that all storage options were covered.) -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: Mark a reloption as indexterm
On 2019-Apr-16, Fujii Masao wrote: > On Tue, Apr 16, 2019 at 12:35 AM Alvaro Herrera > wrote: > > For autovacuum it says "configuration > > parameters" rather than "configuration parameter". Other than that, it > > looks good to me. (I didn't check that all storage options were covered.) > > Good catch! Seems "configuration parameters" had been used for autovacuum > parameter since old version. I agree to replace it with "configuration > parameter" > for the sake of consistency. But I think that it's better to do that by > the separate patch because they are separate things. OK, no objection :-) -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: Documentation for partitioned indexes?
On 2019-Apr-26, Tom Lane wrote: > We appear to have a fair amount of support now for operations like > constructing a partitioned index piecemeal, e.g. adding indexes > to the partitions one at a time and then attaching them to a > parent partitioned index, with the parent ultimately transitioning > from "not valid" to "valid" once all the pieces are attached. > > However, I cannot find any coherent documentation explaining how > to do this (or why you'd want to). Am I just looking in the wrong > places? Hmm. Under Notes for CREATE INDEX there is a paragraph on this: When CREATE INDEX is invoked on a partitioned table, the default behavior is to recurse to all partitions to ensure they all have matching indexes. Each partition is first checked to determine whether an equivalent index already exists, and if so, that index will become attached as a partition index to the index being created, which will become its parent index. If no matching index exists, a new index will be created and automatically attached; the name of the new index in each partition will be determined as if no index name had been specified in the command. If the ONLY option is specified, no recursion is done, and the index is marked invalid. (ALTER INDEX ... ATTACH PARTITION marks the index valid, once all partitions acquire matching indexes.) Note, however, that any partition that is created in the future using CREATE TABLE ... PARTITION OF will automatically have a matching index, regardless of whether ONLY is specified. I suppose I better add something in Chapter 5 (DDL), possibly inside the 5.10 section (Table Partitioning) -- a new 5.10.6 "Indexes for Partitioned Tables" perhaps? -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: Minor improvement for creating directory structure
On 2019-May-09, Bruce Momjian wrote: > On Wed, May 8, 2019 at 07:40:16AM +, PG Doc comments form wrote: > > The following documentation comment has been logged on the website: > > > > Page: https://www.postgresql.org/docs/10/install-short.html > > Description: > > > > 1) > > $ mkdir /usr/local/pgsql/data > > mkdir: cannot create directory ‘/usr/local/pgsql/data’: No such file or > > directory > > My docs say: > >-p, --parents > no error if existing, make parent directories as needed > > While I can see the value of "make parent directories as needed", having > it do "no error if existing" could be bad. Why? initdb is going to fail anyway if it contains anything. -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: Documentation for partitioned indexes?
On 2019-Apr-26, Tom Lane wrote: > Alvaro Herrera writes: > > I suppose I better add something in Chapter 5 (DDL), possibly inside the > > 5.10 section (Table Partitioning) -- a new 5.10.6 "Indexes for > > Partitioned Tables" perhaps? > > I was expecting to find it in "5.11.2.2. Partition Maintenance". Here's a first attempt at doing that. I vote to backpatch this to pg11 (since this functionality is all there). > BTW, is there anything equivalent for unique/pkey constraints? > I tried "add constraint unique ... not valid" and just got a > raspberry. Sure, just "alter table only parent", without explicitly marking it not valid. Then the indexes on children must be attached to the parent indexes; this searches for constraints and does the right thing. On 2019-Apr-26, Jonathan S. Katz wrote: > I'd suggest keeping the title of the section similar to the one with > constraints, i.e. "Partitioning and Indexes" In the end, it seemed material far too short to have its own subsection, but maybe if we redesign the whole section we could lay it out differently? (One idea would be to leave 5.11 for declarative partitioning, and add a new section 5.12 for legacy inheritance. Something to think about for pg13) -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services >From 88204641fce0614551c3b85f921e3cc044650320 Mon Sep 17 00:00:00 2001 From: Alvaro Herrera Date: Thu, 16 May 2019 16:04:29 -0400 Subject: [PATCH] Describe creation of partitioned index piecemeal --- doc/src/sgml/ddl.sgml | 38 ++ 1 file changed, 38 insertions(+) diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml index a0a7435a03d..53e0504ac86 100644 --- a/doc/src/sgml/ddl.sgml +++ b/doc/src/sgml/ddl.sgml @@ -3948,6 +3948,44 @@ ALTER TABLE measurement ATTACH PARTITION measurement_y2008m02 One may then drop the constraint after ATTACH PARTITION is finished, because it is no longer necessary. + + + As explained above, it is possible to create indexes on partitioned tables + and they are applied automatically to the entire hierarchy. This is very + convenient, as not only the existing partitions will become indexed, but + also any partitions that are created in the future do. One limitation is + that it's not possible to use the CONCURRENTLY + qualifier when creating such a partitioned index. To overcome long lock + times, it is possible to use CREATE INDEX ON ONLY + the partitioned table; such an index is marked invalid, and the partitions + do not get the index applied automatically. The indexes on partitions can + be created separately using CONCURRENTLY, and later + attached to the index on the parent using + ALTER INDEX .. ATTACH PARTITION. Once indexes for all + partitions are attached to the parent index, the parent index is marked + valid automatically. Example: + +CREATE INDEX measurement_usls_idx ON ONLY measurement (unitsales); + +CREATE INDEX measurement_usls_200602_idx +ON measurement_y2006m02 (unitsales); +ALTER INDEX measurement_usls_idx +ATTACH PARTITION measurement_usls_200602_idx; +... + + + This technique can be used with UNIQUE and + PRIMARY KEY constraints too; the indexes are created + implicitly when the constraint is created. Example: + +ALTER TABLE ONLY measurement ADD UNIQUE (city_id, logdate); + +ALTER TABLE measurement_y2006m02 ADD UNIQUE (city_id, logdate); +ALTER INDEX measurement_city_id_logdate_key +ATTACH PARTITION measurement_y2006m02_city_id_logdate_key; +... + + -- 2.17.1
Re: Documentation for partitioned indexes?
On 2019-May-16, Alvaro Herrera wrote: > On 2019-Apr-26, Tom Lane wrote: > > > Alvaro Herrera writes: > > > I suppose I better add something in Chapter 5 (DDL), possibly inside the > > > 5.10 section (Table Partitioning) -- a new 5.10.6 "Indexes for > > > Partitioned Tables" perhaps? > > > > I was expecting to find it in "5.11.2.2. Partition Maintenance". > > Here's a first attempt at doing that. I vote to backpatch this to pg11 > (since this functionality is all there). Not hearing any contrary votes, I have backpatched this to pg11. -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: ATTACH/DETACH partitions and locking
On 2019-Jun-13, Pavel Luzanov wrote: > Hello, > > According to patch[1] and after playing with v12 beta1 I think that this > item can be dropped from "5.11.3. Implementation Using Inheritance" section > of v12 docs: > > "Some operations require a stronger lock when using declarative partitioning > than when using table inheritance. For example, adding or removing a > partition to or from a partitioned table requires taking an ACCESS EXCLUSIVE > lock on the parent table, whereas a SHARE UPDATE EXCLUSIVE lock is enough in > the case of regular inheritance." Hmm ... while you're correct that ALTER TABLE ATTACH PARTITION no longer uses AccessExclusive lock, ALTER TABLE DETACH PARTITION continues to. So we could remove the "adding to" bit of the paragraph, but not remove it completely. https://www.postgresql.org/message-id/CA%2BTgmoY13KQZF-%3DHNTrt9UYWYx3_oYOQpu9ioNT49jGgiDpUEA%40mail.gmail.com -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: TOC: List of Figures
On 2019-Jul-02, Daniel Gustafsson wrote: > > On 2 Jul 2019, at 10:13, Jürgen Purtz wrote: > > > The alternative is a downshift of the postings by one level, see attachment > > 2. How to realize this behavior is shown in attachment 3. > > This alternative seems a better idea. I agree -- the other way seems to put too many lines in the overall TOC. As we grow more figures, it'll become unsightly, and scrolling through that list is not something people would do often. -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: Postgres 11: Table Partitioning and Primary Keys
On 2019-Jul-09, Amit Langote wrote: > As mentioned in the docs, defining exclusion constraints on > partitioned tables is not supported. Right. > "While defining a primary key and unique constraints on partitioned > tables is supported, the set of columns being constrained must include > all of the partition key columns. This limitation exists because > PostgreSQL can ensure uniqueness only > across a given partition." I feel that PKs are mostly a special case of UNIQUE keys, so I tend to mention UNIQUE as the central element and let PKs fall out from that. That's a mild personal preference only though. Anyway, based on your proposed wording, I wrote this: Unique constraints on partitioned tables (as well as primary keys) must constrain all the partition key columns. This limitation exists because PostgreSQL can only enforce uniqueness in each partition individually. I'm not really sure about the "must constrain" verbiage. Is that really comprehensible? Also, I chose to place it just above the existing para that mentions FK limitations, which reads: While primary keys are supported on partitioned tables, foreign keys referencing partitioned tables are not supported. (Foreign key references from a partitioned table to some other table are supported.) Your proposed wording seemed to use too many of the same words, which prompted me to change a bit. Maybe I read too many novels and insufficient technical literature. In CREATE TABLE, we already have this: When establishing a unique constraint for a multi-level partition hierarchy, all the columns in the partition key of the target partitioned table, as well as those of all its descendant partitioned tables, must be included in the constraint definition. which may not be the pinnacle of clarity, but took some time to craft and I think is correct. Also it doesn't mention primary keys explicitly; maybe we should patch it by adding "(as well as a primary key)" right after "a unique constraint". Thoughts? -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: Wrong formatting of the word 'executed'
On 2019-Jul-25, PG Doc comments form wrote: > The following documentation comment has been logged on the website: > > Page: https://www.postgresql.org/docs/11/plpgsql-expressions.html > Description: > > In section 43.4, in the sentence "(...) and then this prepared statement is > EXECUTEd (...)", the word executed should be modified to lower case. ISTM that this is intentional, since it refers to the use of the EXECUTE command. It does seem maybe too informal to use command names as verbs and conjugate them ... we don't do it too much, except for "TOASTed". $ git grep 'e\?d' doc/src/sgml/gist.sgml:function should return a pointer to newly palloc()ed doc/src/sgml/lobj.sgml:up to 4 TB in size, whereas TOASTed fields can be at doc/src/sgml/lobj.sgml:done efficiently, while most operations on a TOASTed doc/src/sgml/plpgsql.sgml: and then this prepared statement is EXECUTEd for each doc/src/sgml/storage.sgml:called TOASTed values work by modifying or doc/src/sgml/storage.sgml:handle potentially TOASTed input values: an input might not doc/src/sgml/storage.sgml:the value is an ordinary un-TOASTed value of the data type, and doc/src/sgml/storage.sgml:TOASTed values are kept in the TOAST table, as doc/src/sgml/storage.sgml:identifying the particular TOASTed value), doc/src/sgml/storage.sgml:TOASTed value therefore needs to store the OID of the doc/src/sgml/storage.sgml:of TOASTed attributes will only be pulled out (if selected at all) doc/src/sgml/storage.sgml:pages). There was no run time difference compared to an un-TOASTed We do append "s" to make plurals a lot, though. -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: Make 'Genetic Algorithm' a real figure
On 2019-Jul-19, Jürgen Purtz wrote: > This is an adoption of the genetic-algorithm.gv file to the style of the > gin.gv file: same font, similar header, use of TAB instead of SPACE. I pushed this with trivial changes, thanks. -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: Release notes on "reserved OIDs"
On 2019-Aug-30, Tom Lane wrote: > > > > >Reserve a range of OIDs (9000-) to be used for external >extensions (Andres Freund) > > > > This seems more or less completely misleading. Hmm. I wonder if this item really belongs in the release notes at all. My view is that this was interim policy, not necessarily a permanent thing; and it's oriented strictly towards PG developers rather than end users or even fork-developers. -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: Consolidation of first figures
On 2019-Sep-02, Jürgen Purtz wrote: > We plan to integrate figures into version 12. Currently there are 2 resp. 3 > figures in git (BETA3 / master). This may be intended - or not. Additionally > there are some patches in the mailing list. I purposefully pushed that figure to master only; pg12 is in stabilization period, so a major change such as the addition of a new figure is not welcome. You're welcome to propose minor changes such as a color change in pg12, but that should be a one-line change not a wholesale rewrite of the file. -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: Authentication Methods page is broken on v11 and v12
On 2019-Sep-11, Pavlo Golub wrote: > Trying to view > > https://www.postgresql.org/docs/11/auth-methods.html > https://www.postgresql.org/docs/12/auth-methods.html > https://www.postgresql.org/docs/current/auth-methods.html > > gives me an empty page. Previous versions are not affected. That's because commit 56811e57323f changed each ethod to be . -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: Most-common value docs in PG 12
On 2019-Aug-30, Bruce Momjian wrote: > OK, how is this patch? I didn't mention psql since I think everyone > expects psql to show all information about tables and indexes. Why would you change perform.sgml? It seems unnecessary; the commands shown work fine. This part seems okay: > diff --git a/doc/src/sgml/ref/create_statistics.sgml > b/doc/src/sgml/ref/create_statistics.sgml > index ec23a154d6..5b583aacb4 100644 > --- a/doc/src/sgml/ref/create_statistics.sgml > +++ b/doc/src/sgml/ref/create_statistics.sgml > @@ -98,7 +98,8 @@ CREATE STATISTICS [ IF NOT EXISTS ] class="parameter">statistics_na > > >The name of a table column to be covered by the computed statistics. > - At least two column names must be given. > + At least two column names must be given; the order of the column names > + is insignificant. > > > -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: fixes for typos and tags in REL_12_STABLE
On 2019-Sep-12, Alexander Korotkov wrote: > On Thu, Sep 12, 2019 at 4:58 PM Liudmila Mantrova > wrote: > > Please consider these small patches for REL_12_STABLE that mainly fix > > remaining typos and some tagging issues. The jsonpath-related one also > > improves some wordings, e.g. there seems to be no need to separate Boolean > > operators with spaces in path definitions. > > I'm going to push these two if no objections. Looks good on a quick once-over. -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: Most-common value docs in PG 12
On 2019-Sep-26, Bruce Momjian wrote: > On Wed, Sep 11, 2019 at 06:15:22PM -0300, Alvaro Herrera wrote: > > On 2019-Aug-30, Bruce Momjian wrote: > > > > > OK, how is this patch? I didn't mention psql since I think everyone > > > expects psql to show all information about tables and indexes. > > > > Why would you change perform.sgml? It seems unnecessary; the commands > > shown work fine. > > I realize they work fine, but the ordering in the examples not matching > the defined order suggests that ordering matters, but it does not. Well, I mean exactly the other way around: the fact that the orders don't match illustrates that the order is not important. And that is reinforced by the explanation indicating explicitly that it does not matter: > > > > > >The name of a table column to be covered by the computed > > > statistics. > > > - At least two column names must be given. > > > + At least two column names must be given; the order of the column > > > names > > > + is insignificant. > > > -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: Adding a Column documentation is misleading
On 2019-Nov-06, PG Doc comments form wrote: > Page: https://www.postgresql.org/docs/12/ddl-alter.html > Description: > > In 5.6.1. Adding a Column, there is a kind of example 'ALTER TABLE products > ADD COLUMN description text;' > > The words 'description' and 'text' are misleading -- as according to the > formal documentation of the SQL command > (https://www.postgresql.org/docs/12/sql-altertable.html), they should be > 'column_name' and 'data_type'. Well, it's an example, so "description" is the column name and "text" is its data type. If you had a table called products, you could run that command and it would work just fine (assuming you don't already have a column called description, doh). Maybe the example could be made clearer by using some other column name and some other data type, so that they don't resemble english prose or keywords. Maybe "alter table cities add column year_founded integer". Do you want to propose something better than that? > A similar problem exists for removing a column, and other actions. Let's hear your proposed changes. -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: The word "virgin" used incorrectly and probably better off replaced
On 2019-Nov-07, PG Doc comments form wrote: > Page: https://www.postgresql.org/docs/12/manage-ag-templatedbs.html > Description: > > The use of the word virgin as an adjective is incorrect here and also an > anachronism. It is better off replaced with the word pristine - quotes > unnecessary. Note the word virgin appears in another page of the > documentation (a search will find it). Just because a word has sexual connotations does not imply that it doesn't have non-sexual meanings. Merriam-Webster lists https://www.merriam-webster.com/dictionary/virgin 2: FRESH, UNSPOILED specifically : not altered by human activity 6: free of impurity or stain : UNSULLIED which seems to apply well to all cases at hand. Also: First Known Use of virgin Noun: 13th century, in the meaning defined at sense 2a Adjective: 14th century, in the meaning defined at sense 6 History and Etymology for virgin Noun: Middle English, from Anglo-French virgine, from Latin virgin-, virgo young woman, virgin That said, in two of the three phrases where the word appears, the quoted adjective adds no value. We could remove the quoted word entirely in all three places and nothing would be lost. But if we do that, then the third occurrence of the word would become inintelligible: "This is particularly handy when restoring a pg_dump dump: the dump script should be restored in a virgin database to ensure that one recreates the correct contents of the dumped database, without conflicting with objects that might have been added to template1 later on." because we have not explained what a "virgin database" is. We could say "empty", which seems better suited than both "virgin" and "pristine" anyway. -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: The word "virgin" used incorrectly and probably better off replaced
On 2019-Nov-07, Bruce Momjian wrote: > On Thu, Nov 7, 2019 at 07:55:22PM +0100, Daniel Gustafsson wrote: > > > On 7 Nov 2019, at 16:03, Alvaro Herrera wrote: > > > We could say "empty", which seems better suited than both "virgin" and > > > "pristine" anyway. > > > > empty is a lot better, but still isn't conveying the state of the database > > without there being room for interpretation. (My grasp of the english > > language > > isn't enough to suggest a better alternative however). > > I am thinking "pristine" would be a good word here. But you would have to explain that a database created as a copy of template1 may somehow not be pristine. Maybe we should just use a phrase that describes what we mean, something like "a database that doesn't contain objects other than default system ones." -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: The word "virgin" used incorrectly and probably better off replaced
On 2019-Nov-08, Daniel Gustafsson wrote: > Agreed. I like your suggestion, or the inverse of it: "a database without any > user defined objects". Here's a proposed patch. -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services >From b394a1b2b6227d68e0cd2c32afb75ef3bfd317ef Mon Sep 17 00:00:00 2001 From: Alvaro Herrera Date: Fri, 8 Nov 2019 10:09:05 -0300 Subject: [PATCH] No more virgins --- doc/src/sgml/manage-ag.sgml | 5 +++-- doc/src/sgml/ref/create_database.sgml | 2 +- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/doc/src/sgml/manage-ag.sgml b/doc/src/sgml/manage-ag.sgml index 0154064e50..a939ce8313 100644 --- a/doc/src/sgml/manage-ag.sgml +++ b/doc/src/sgml/manage-ag.sgml @@ -199,11 +199,12 @@ createdb -O rolename dbnameCREATE DATABASE to copy template0 instead - of template1, you can create a virgin user + of template1, you can create a user database that contains none of the site-local additions in template1. This is particularly handy when restoring a pg_dump dump: the dump script should be restored in a - virgin database to ensure that one recreates the correct contents + database without any user-defined objects, to ensure that one recreates + the correct contents of the dumped database, without conflicting with objects that might have been added to template1 later on. diff --git a/doc/src/sgml/ref/create_database.sgml b/doc/src/sgml/ref/create_database.sgml index 4014f6703b..e56aca6d30 100644 --- a/doc/src/sgml/ref/create_database.sgml +++ b/doc/src/sgml/ref/create_database.sgml @@ -54,7 +54,7 @@ CREATE DATABASE name system database template1. A different template can be specified by writing TEMPLATE name. In particular, - by writing TEMPLATE template0, you can create a virgin + by writing TEMPLATE template0, you can create a database containing only the standard objects predefined by your version of PostgreSQL. This is useful if you wish to avoid copying -- 2.20.1
Re: The word "virgin" used incorrectly and probably better off replaced
On 2019-Nov-08, Tom Lane wrote: > Alvaro Herrera writes: > > Here's a proposed patch. > > I don't like this wording much, because "no user-defined objects" > is not a sufficient specification of what we are talking about. > You need to also capture the property that none of the system- > defined objects have been altered. Now that we explicitly support > things like altering the ACLs of system-defined objects, I do not > think it's okay to take that part for granted. Hmm. Maybe we can say "pristine database" and then add this explanation in a parenthical comment: This is particularly handy when restoring a pg_dump dump: the dump script should be restored in a pristine database (one where no user-defined objects exist and where system objects have not been altered), to ensure that one recreates the correct contents of the dumped database, without conflicting with objects that might have been added to template1 later on. -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: The word "virgin" used incorrectly and probably better off replaced
On 2019-Nov-08, Tom Lane wrote: > Alvaro Herrera writes: > > Hmm. Maybe we can say "pristine database" and then add this explanation > > in a parenthical comment: > > > This is particularly handy when restoring a > > pg_dump dump: the dump script should be restored in a > > pristine database (one where no user-defined objects exist and where > > system objects have not been altered), to ensure that one recreates > > the correct contents of the dumped database, without conflicting > > with objects that might have been added to > > template1 later on. > > So the patch becomes s/virgin/pristine/g plus add a parenthetical > definition for the first use? Works for me. Well, there are three uses of the word "virgin". The first is for "virgin user", and the patch turns that into just "user". The second one is for "virgin database" and the patch has the effect you describe. The third one is also s/virgin//. -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services diff --git a/doc/src/sgml/manage-ag.sgml b/doc/src/sgml/manage-ag.sgml index 0154064e50..7e7f0ed00c 100644 --- a/doc/src/sgml/manage-ag.sgml +++ b/doc/src/sgml/manage-ag.sgml @@ -197,15 +197,17 @@ createdb -O rolename dbnamePostgreSQL. template0 should never be changed after the database cluster has been initialized. By instructing CREATE DATABASE to copy template0 instead - of template1, you can create a virgin user + of template1, you can create a user database that contains none of the site-local additions in template1. This is particularly handy when restoring a pg_dump dump: the dump script should be restored in a - virgin database to ensure that one recreates the correct contents + pristine database (one where no user-defined objects exist and where + system objects have not been altered), to ensure that one recreates + the correct contents of the dumped database, without conflicting with objects that might have been added to template1 later on. diff --git a/doc/src/sgml/ref/create_database.sgml b/doc/src/sgml/ref/create_database.sgml index 4014f6703b..e56aca6d30 100644 --- a/doc/src/sgml/ref/create_database.sgml +++ b/doc/src/sgml/ref/create_database.sgml @@ -52,11 +52,11 @@ CREATE DATABASE name By default, the new database will be created by cloning the standard system database template1. A different template can be specified by writing TEMPLATE name. In particular, - by writing TEMPLATE template0, you can create a virgin + by writing TEMPLATE template0, you can create a database containing only the standard objects predefined by your version of PostgreSQL. This is useful if you wish to avoid copying any installation-local objects that might have been added to template1.
Re: The word "virgin" used incorrectly and probably better off replaced
On 2019-Nov-08, Tom Lane wrote: > Alvaro Herrera writes: > > On 2019-Nov-08, Tom Lane wrote: > >> So the patch becomes s/virgin/pristine/g plus add a parenthetical > >> definition for the first use? Works for me. > > > Well, there are three uses of the word "virgin". The first is for > > "virgin user", and the patch turns that into just "user". > > Uh, no, read the next lines. In both cases those are referring > to "virgin user database" or "virgin database", and this patch > is removing an important qualifier. It needs to be s/virgin/pristine/ > in all these places. Doh, right. One problem with doing it that way is that the proposed parenthical comment partly duplicates the text immediately following it, so I'm no longer so sure that adding it is good; I think that changing "local additions" to "local additions and changes" might be sufficient, or maybe that is too obscure for novices? For create_database.sgml it does seem to make a little more sense, but I'm not 100% there either. Maybe "changes" can become "database-local system changes"? i.e., By instructing CREATE DATABASE to copy template0 instead of template1, you can create a pristine user database that contains none of the site-local additions and database-local system changes in template1. ... though, argh, "-local" appearing twice makes that look bad too :-( (I'm not sure that it is clear what a "database-local system change" is.) -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services diff --git a/doc/src/sgml/manage-ag.sgml b/doc/src/sgml/manage-ag.sgml index 0154064e50..00ecc2d843 100644 --- a/doc/src/sgml/manage-ag.sgml +++ b/doc/src/sgml/manage-ag.sgml @@ -199,11 +199,11 @@ createdb -O rolename dbnameCREATE DATABASE to copy template0 instead - of template1, you can create a virgin user - database that contains none of the site-local additions in + of template1, you can create a pristine user + database that contains none of the site-local additions and changes in template1. This is particularly handy when restoring a pg_dump dump: the dump script should be restored in a - virgin database to ensure that one recreates the correct contents + pristine database to ensure that one recreates the correct contents of the dumped database, without conflicting with objects that might have been added to template1 later on. diff --git a/doc/src/sgml/ref/create_database.sgml b/doc/src/sgml/ref/create_database.sgml index 4014f6703b..7b48263364 100644 --- a/doc/src/sgml/ref/create_database.sgml +++ b/doc/src/sgml/ref/create_database.sgml @@ -54,8 +54,10 @@ CREATE DATABASE name system database template1. A different template can be specified by writing TEMPLATE name. In particular, - by writing TEMPLATE template0, you can create a virgin - database containing only the standard objects predefined by your + by writing TEMPLATE template0, you can create a + pristine database (one where no user-defined objects exist and where + system objects have not been altered) + containing only the standard objects predefined by your version of PostgreSQL. This is useful if you wish to avoid copying any installation-local objects that might have been added to
Re: Example not producing shown output
On 2019-Nov-25, Daniel Gustafsson wrote:
> > On 25 Nov 2019, at 13:05, PG Doc comments form
> > wrote:
> > Examples should have specified 'english'.
> >
> > Instead:
> > to_tsvector('fat cats ate rats') @@ to_tsquery('cat & rat')
> >
> > which returns fale on my own blank installation of Postgre (Serbian locale
> > Windows OS) instead of true:
> > to_tsvector('english', 'fat cats ate rats') @@ to_tsquery('cat & rat')
>
> I agree with this complaint, mainly since other examples on the page do
> specify
> english where required AFAICT, this makes it consistent.
Hmm. I'm not sure that it's an improvement to make all the examples
alike; that means we would not provide examples of the simpler syntax.
And because other examples already show that it's possible to indicate
the language, I'm not sure it's strictly necessary to do so here.
Maybe this complaint could be addressed by indicating in a note that
some examples might not work identically if run under a different
locale. Or perhaps we can add a second line in the example cell for the
@@ operator, to make it clear that both forms can be used. Users can be
expected to apply some intuition from that point onwards.
--
Álvaro Herrerahttps://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: Example not producing shown output
On 2019-Nov-27, Daniel Gustafsson wrote: > > On 26 Nov 2019, at 19:28, Alvaro Herrera wrote: > > > Or perhaps we can add a second line in the example cell for the > > @@ operator, to make it clear that both forms can be used. Users can be > > expected to apply some intuition from that point onwards. > > Wouldn't it be more intuitive to add such a second line under to_tsvector, or > expand the Description field to cover a brief discussion covering this? I don't know. The problem is that the line for to_tsvector is a lot further down the page in table 9.42, and it contains a lot of other stuff, so people trying their first examples based on table 9.41 would not see it and will be as surprised as the OP was when it doesn't work under their locale. I think enlarging the description for the @@ entry is not out of the question, but trying to explain too much about the locale there seems a bit out of place. This is why I suggested to add another Note box below the table. If I misunderstood what you meant, please be more specific. -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: client auth docs seem to have devolved
On 2019-Dec-19, Tom Lane wrote: > I wrote: > > Concretely, I propose the attached. Anybody want to editorialize on > > my short descriptions of the auth methods? > > Pushed after a bit more fiddling with the wording. Looks good, thanks. -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: doc: Add anchors in create_table.sgml
On 2020-Jan-02, PG Doc comments form wrote: > The following documentation comment has been logged on the website: > > Page: https://www.postgresql.org/docs/12/sql-createtable.html > Description: > > From 73ad66d721a3f87500857cdc6b1f4d810f2875df Mon Sep 17 00:00:00 2001 > From: =?UTF-8?q?Ivan=20Mas=C3=A1r?= > Date: Thu, 2 Jan 2020 09:15:34 +0100 > Subject: [PATCH] doc: Add anchors in create_table.sgml Can you comment a little on the reason for adding these? I'm not opposed to doing so, but we don't have them in every possible place (we have in 607 of ~4300 varlistentries by my count), so it needs some rationale. -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: doc: Add anchors in create_table.sgml
Hi, On 2020-Jan-02, helix84 wrote: > Hi, I prefer to bookmark docs pointing to the exact term I need and > with pg docs it's often been the case that the exact term doesn't have > an anchor or only has unstable, generated anchors. So I would very > much like to add stable anchors in many more places. I haven't > contributed to pg before, so this patch is me testing the waters. If > there is interest, I'd like to add stable anchors to wherever we'll > agree it makes sense - preferably in an automated or semi-automated > way. > > I read an older thread on this topic [1] which links to a custom SGML > parser in Python for this specific task [2]. I have experience with > XSLT, but not so much with SGML processing, so I would appreciate if > you could point me whether a custom parser is the way to go for this > task or I should look into a more generic SGML processing tool. Ah, https://www.postgresql.org/message-id/aanlktikagiyyfwy_2zj8gafoc7zflgv5icdab1l7v...@mail.gmail.com (We prefer our own archive to GMane's.) That thread is so old that Peter feels the need to point out that the Git mirror was out of date with CVS ... I can no longer even remember the commit process for CVS anymore. We also converted from SGML to XML in the meantime, so you can probably make do with a standard XML parser without having to write a custom SGML one. (Daniele Varrazzo's patch ended up as 477319829c2e.) TBH I've felt the need for anchors for tags in the past also (IIRC the runtime-config page would be improved by them), but I'm not sure about adding them to every single keyword of every single reference page. Is that really useful? > Thanks in advance and let me take this opportunity to thank you all > for this wonderful piece of software. You're welcome. -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: Documentation: 21.5. Default Roles
On 2020-Feb-03, Jonathan S. Katz wrote: > So, if there was something done to redirect people from specific > deprecated documentation pages historically, it was before my time. Most > of the redirects have been as general purposes ones (e.g. /docs/12), the > rules we put in for getting rid of "static", and the release notes, > which still receives some negative feedback towards it for different > reasons (though I think overall the effort was well-received). Anyway, > if we had a redirect in place, I'd want us to do it well. I +1 changing the title and +1 having the redirect. That said, I think people landing in a page titled "predefined roles" when they're looking for a page titled "default roles" would be quite confused for a while and perhaps continue to search for the page they think they're looking for. (I know, it has happened to me.) I suggest we add a very short paragraph --maybe a -- to the effect that feature-X used to be called feature-Y, immediately following the section title. -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: Getting our tables to render better in PDF output
On 2020-Feb-12, Tom Lane wrote: > For amusement's sake, attached is a screenshot of what Table 9-33 > looks like in A4 format, with my one-row-per-example patch of > yesterday plus a few manually-added zero-width spaces to break up > the examples. This is the first PDF rendering of that table that > I've seen that I actually like. I like this. The trick of mkaing the first cell take up two or three rows makes this much clearer and sensible than what I had obtained. > I also attached a screenshot of a segment of Table 9-31, to show > what that layout proposal looks like. It's a little busier, but > it does have the advantage that it's clearer how to apply that > format to operator tables. The "returns " notation isn't used > anywhere in SQL for operators, so I am not in love with the idea of > writing the operator tables that way. Yeah, that's a little less obvious. I just noticed that the operators tables show the operator names but not the input datatypes except in the examples. Perhaps we could use a layout with a cell labelled "signature" (namest=col2 nameend=col3) instead of input types + return types and separate them using → which would look like this: date + integer → date > Also worth noting is that in most function tables, and certainly > in the operator tables, we could make the first column narrower. > The same table with the first column half as wide as the others > is depicted in the last screenshot. (For this particular table, > doing that would require breaking some of the longer function > names such as transaction_timestamp. Not sure whether that's > a net win, but we do have the option.) I like making that column narrower. > One issue that I've found is that the toolchain has no idea that > the table rows are in groups, so it's happy to split a table > across pages with a function's description and/or examples on > a new page. No idea if there's any way around that. Fortunately > it's not an issue in HTML, so maybe we don't have to fix it. My vote goes to postponing a solution to this problem :-) -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: Getting our tables to render better in PDF output
On 2020-Feb-12, Tom Lane wrote: > With a separate argument-types cell it'd likely be > better to just leave the cell empty, but do we want to write > just "→ rettype" in a signature cell? Yeah, it'd look very odd, and certainly the no-parens case makes it worse. I like this end result: > so being consistent with that might suggest including the function name > in function signatures: > > Function Signature > > ageage(timestamp) → interval > > nownow() → timestamp with time zone > > current_timestamp current_timestamp → timestamp with time zone > > I'm a bit suspicious of how much horizontal space that would eat, but > if we're able to get rid of the separate cell for result type, it > might work out OK. Regarding no-parens function signatures, perhaps we can add a footnote indicating that such functions have this strange shape because of the SQL committee, such as "† This function signature uses no parentheses because the SQL standard defines it in that way." -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
