Postgres upgrade trouble

[PG Doc comments form]

The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/10/static/pgupgrade.html
Description:

This is a non IT specialist question / comments. I like postgres, except the
current automatic upgrade mechanism working on my server...
On my Ubuntu 16.04 machine, when a postgres upgrade comes and installs
automatically, this creates a real nightmare:  neither pgAdminIII not my
application can access the DB. (connection refused. Is the server running...
...on port 5432?)
Trying to understand in the documentation what to do is very difficult
because there is no clear example on how to retreive the 'old' or 'new'
parameters. So, I wonder why there is no automatic mechanism coming with the
upgrade to change the settings automatically, or alternatively to keep the
'old' version up and running correctly (and in this case the end user should
have an easy way to know that he has to launch an upgrade when he wants to,
and an utility -for instance in pgAdmin- should guide him along this upgrade
mechanism, ensuring I do not loose time nor any data).
Thanks for your efforts to offer Postgres to the IT community!

documentation synopsis grammar

[Peter Korim]

Hallo

I search for it  and did notsucceeded.
Where is exact definition of the grammar used here?

I thing the text "[,...]" is unclear concerning what is to be repeted.

here:
   *https://www.postgresql.org/docs/9.6/static/notation.html
*
you state
   *" Dots (...) mean that the preceding element can be repeated. "*

from that definition  the fragment "[,...]" means zero or more commas.

It is often so that not one element but several elements are repeated  .

Sometimes from the context, one may find out how it is meant.
In other cases it not so clear .

Well do you have a definition or third party standard?



Thank you very much,Peter Korim.

Re: documentation synopsis grammar

[David G. Johnston]

On Friday, May 11, 2018, Peter Korim  wrote:

> Hallo
>
> I search for it  and did notsucceeded.
> Where is exact definition of the grammar used here?
>
> I thing the text "[,...]" is unclear concerning what is to be repeted.
>

Not that I've found,  do you have an example?


>
> here:
>*https://www.postgresql.org/docs/9.6/static/notation.html
> *
> you state
>*" Dots (...) mean that the preceding element can be repeated. "*
>
> from that definition  the fragment "[,...]" means zero or more commas.
>
> It is often so that not one element but several elements are repeated  .
>

In which case each one requires a comma separating it from the previous one.


>
> Sometimes from the context, one may find out how it is meant.
>


> In other cases it not so clear.
>

Again, You will need to point out an example.  But not all options that
allow multiples require commas to separate them.


>
> Well do you have a definition or third party standard?
>
>
You linked to it above...

David J.

Re: documentation synopsis grammar

[David G. Johnston]

On Friday, May 11, 2018, David G. Johnston 
wrote:

> On Friday, May 11, 2018, Peter Korim  wrote:
>
>> Hallo
>>
>> I search for it  and did notsucceeded.
>> Where is exact definition of the grammar used here?
>>
>> I thing the text "[,...]" is unclear concerning what is to be repeted.
>>
>
> Not that I've found,  do you have an example?
>
>
Ok, I think I get your confusion now...

 ANALYZE [ VERBOSE ] [ *table_name* [ ( *column_name* [, ...] ) ] ]

column_name can be repeated. If it is each name is separated from the
previous one by a comma. The brackets indicate optional repetition of the
immediately preceding element. The presence or absence of a comma in the
bracket indicates whether each option repeat needs a comma separator. It's
not the comma that is being repeated.

David J.

Re: documentation synopsis grammar

[David G. Johnston]

Please keep communications on-list.

On Fri, May 11, 2018 at 3:05 PM, Peter Korim  wrote:

> Ok David
>
> by your definition and following synopsis:
> CREATE [ OR REPLACE ] FUNCTION
> name (
> ​​
> [ [ argmode ] [ argname ] argtype [ { DEFAULT | = } default_expr ] [, ...]
> ] )
> (seen here: https://www.postgresql.org/docs/9.6/static/sql-
> createfunction.html)
>
> should be valid this:
> CREATE [ OR REPLACE ] FUNCTION
>  name (   argtype   =  default_expr ,   =  default_expr  ,   =
> default_expr)
>
>
​But it obviously isn't...
​
I suppose the [, ...] could be placed after the "]" to its right...but the
only mandatory element in that [] block is "argtype" so the [, ...] refers
to it (or rather, everything in between the [ ] of which it is a part.

(argtype, argtype, argtype)

Each one of those argtype values can be surrounded by any of the optional
elements surrounding it in the syntax.  The whole part between the ( )
being optional, hence the idiomatic ( [  ] ) syntax.

These are written by humans for humans - and in some cases do take a bit of
thinking (and, sometimes, reading the descriptions about the items in
question) about what ultimately makes sense to understanding exactly what
might or might not be valid.

I'm suspecting that our best bet is leave the notation page a bit vague and
just clear up confusion when it arises.  The example above, while probably
technically incorrect, is, I'm reasonably certain, common and saying its
wrong and fixing it is unlikely to happen given the rarity of questions
like this.  Trying to describe exactly how that [, ...] works in the
presence of mandatory and optional parts is likely to add, not reduce,
confusion.  As its stands "..." means repetition is possible and you, the,
reader, are assumed to figure out what exactly is repeatable.  You'll
likely get a syntax error quickly if you guess wrong and these lists are
very responsive if you get stumped.

You are welcome to suggest corrections to the documentation, and even
better, submit patches, if you find the existing conventions/notations page
unconscionably lacking.

David J.

Re: documentation synopsis grammar

[Tom Lane]

"David G. Johnston"  writes:
> I'm suspecting that our best bet is leave the notation page a bit vague and
> just clear up confusion when it arises.  The example above, while probably
> technically incorrect, is, I'm reasonably certain, common and saying its
> wrong and fixing it is unlikely to happen given the rarity of questions
> like this.

Yeah; a quick grep suggests that there are several hundred occurrences
of this notation in our reference pages alone.  Even if somebody were
initially confused, they'd soon figure it out, I should think.  Certainly
we've had few if any complaints about this point before.

The bigger question though is, if we don't like this notation, what
notation would we replace it with?  We could be formally correct by
rewriting all of these syntax synopses in BNF, but I think most people
are not terribly familiar with that and would be more confused, not less.
Our actual bison grammar, which is BNF-equivalent I think, is certainly
arcane enough to scare off non-experts.

There was a related discussion recently:

https://www.postgresql.org/message-id/flat/152110913499.1223.7026776990975251345%40wrigleys.postgresql.org

The problems discussed there with our description of set-operation syntax
are really a lot worse than this issue, I think.  And yet we still opted
not to change the documentation, because it seemed that anything that's
more formally correct would also be a lot more incomprehensible.

I don't want to sound like I think what we've got now is the peak of
perfection, because it isn't.  But we have to strike a balance between
formal correctness and readability for users who aren't familiar with
formal syntax notations.  It's a difficult problem.

regards, tom lane