Re: doc: Add anchors in create_table.sgml

[Jürgen Purtz]

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.


Use XML tools with care! Some of our XML files are not well formed 
because they contain more than one root element.


Kind regards, Jürgen Purtz.

Argument 'week' not supported in date_trunc function with intervals

[PG Doc comments form]

The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/12/functions-datetime.html
Description:

In the documentation of the date_trunc function (9.9.2), the first argument
(field) cannot be 'week' if the second argument (source) is an interval:

csauer=# SELECT DATE_TRUNC('week', INTERVAL '7 days');  



ERROR:  interval units "week" not supported because months usually have
fractional weeks
csauer=# SELECT DATE_TRUNC('week', INTERVAL '1 week');  


   
ERROR:  interval units "week" not supported because months usually have
fractional weeks

The documentation should state that explicitly.

I also think the error message could be improved, because in the cases above
there are no months involved and the result should be 1.

Re: doc: Add anchors in create_table.sgml

[Alvaro Herrera]

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: Link to "Upgrading a PostgreSQL Cluster" in Release Notes

[Magnus Hagander]

On Fri, Jan 3, 2020 at 9:57 AM Peter Eisentraut <
peter.eisentr...@2ndquadrant.com> wrote:

> On 2019-12-30 00:03, Vik Fearing wrote:
> > Following a complaint on IRC about the dearth of information on how to
> > migrate to a new major version in the release notes, the attached
> > trivial patch was determined to be sufficient for the OP.
> >
> > This patch applies to REL_12_STABLE.  I don't know how far it should be
> > backpatched (the OP was trying to upgrade to v10), and I didn't see any
> > place to put it for 13 and future versions.
>
> I think this change is sensible.  But to what extent do we want to edit
> around in old release notes?  Should we just keep it for PG13?
>

I think it makes sense to backpatch it. Lots of people still upgrade to at
least 12 and 11, and that's a likely place for them to start reading. And
if we're already covering 12 and 11, it is probably no big extra effort to
do other supported branches as well.


I think we should also extend the blurb in the release notes to mention
> the option of using logical replication to upgrade.  Otherwise, if you
> follow the link you propose, then one might think that logical
> replication upgrading is not applicable since only pg_dump and
> pg_upgrade were mentioned in the place the link came from.
>
>
+1.

-- 
 Magnus Hagander
 Me: https://www.hagander.net/ 
 Work: https://www.redpill-linpro.com/ 

Re: Link to "Upgrading a PostgreSQL Cluster" in Release Notes

[Peter Eisentraut]

On 2019-12-30 00:03, Vik Fearing wrote:

Following a complaint on IRC about the dearth of information on how to
migrate to a new major version in the release notes, the attached
trivial patch was determined to be sufficient for the OP.

This patch applies to REL_12_STABLE.  I don't know how far it should be
backpatched (the OP was trying to upgrade to v10), and I didn't see any
place to put it for 13 and future versions.


I think this change is sensible.  But to what extent do we want to edit 
around in old release notes?  Should we just keep it for PG13?


I think we should also extend the blurb in the release notes to mention 
the option of using logical replication to upgrade.  Otherwise, if you 
follow the link you propose, then one might think that logical 
replication upgrading is not applicable since only pg_dump and 
pg_upgrade were mentioned in the place the link came from.


--
Peter Eisentraut  http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

Re: the concept of a database cluster

[David G. Johnston]

On Thursday, January 2, 2020, PG Doc comments form 
wrote:

> The following documentation comment has been logged on the website:
>
> Page: https://www.postgresql.org/docs/12/creating-cluster.html
> Description:
>
> In 18.2, a database cluster is said to be "a database storage area on
> disk",
> and then shortly afterward is is defined as "a collection of databases that
> is managed by a single instance of a running database server". Those seem
> very different things. Sometimes in the manual I can't tell which usage is
> intended.
>

A garage is a “car storage area for a house”. A garage can (typically)
store multiple cars just as a database cluster can store multiple
databases.  The files are only useful if there is a running instance and
all databases stored in the cluster are managed by a single shared
instance.  You will need to better explain your confusion because the
documentation is describing a complex system accurately but in parts that
are related - two sides of the same coin, if you will.

David J.

Put cluster in the hierarchy in 22.1

[PG Doc comments form]

The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/12/manage-ag-overview.html
Description:

22.1 says "So the full hierarchy is: server, database, schema, table (or
some other kind of object, such as a function)." Could "cluster" be added in
there for completeness sake?  "So the full hierarchy is: server, cluster,
database, schema, table (or some other kind of object, such as a function)."
It might be nice to have a graphic showing the relationships, adding other
things as well: columns, constraints, triggers, etc.

the concept of a database cluster

[PG Doc comments form]

The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/12/creating-cluster.html
Description:

In 18.2, a database cluster is said to be "a database storage area on disk",
and then shortly afterward is is defined as "a collection of databases that
is managed by a single instance of a running database server". Those seem
very different things. Sometimes in the manual I can't tell which usage is
intended.