Re: crosstab documentation should add a note about use in materialized views
On Tue, Oct 18, 2022 at 08:30:13AM +, PG Doc comments form wrote: > The following documentation comment has been logged on the website: > > Page: https://www.postgresql.org/docs/15/tablefunc.html > Description: > > When using a crosstab in a materialized view, if the SQL is not qualified > with a schema, that restoring a database from a dump may fail. See the > discussion in > https://www.postgresql.org/message-id/16202-b6b345c9d2819409%40postgresql.org I am trying to understand the scope of this breakage. I think it is because crosstab specifies queries as strings, and a materialized view has to run the query during restore to populate the materialized view. Is this the only combination of pg_dump restore breakage? -- Bruce Momjian https://momjian.us EDB https://enterprisedb.com Indecision is a decision. Inaction is an action. Mark Batterson
Re: crosstab documentation should add a note about use in materialized views
Bruce Momjian writes: >> When using a crosstab in a materialized view, if the SQL is not qualified >> with a schema, that restoring a database from a dump may fail. See the >> discussion in >> https://www.postgresql.org/message-id/16202-b6b345c9d2819409%40postgresql.org > I am trying to understand the scope of this breakage. I think it is > because crosstab specifies queries as strings, and a materialized view > has to run the query during restore to populate the materialized view. > Is this the only combination of pg_dump restore breakage? It doesn't sound like this is in any way unique to crosstab. Any underqualified reference to a user-defined object can cause problems during dump/restore, because of the restricted search_path we use during restore. regards, tom lane
Re: nextval parameter is not clear
On Tue, Oct 18, 2022 at 08:17:12AM +, PG Doc comments form wrote:
> The following documentation comment has been logged on the website:
>
> Page: https://www.postgresql.org/docs/14/functions-sequence.html
> Description:
>
> https://www.postgresql.org/docs/14/functions-sequence.html
>
> I don't see here any hints about how to use this function, and what the
> regclass means.
> How should I understand that sequence_name should be passed as string in
> nextval('sequence_name') ?
>
> Maybe add some links to other topics or clarify examples for nextval here.
Uh, the last sentence in that section says:
The sequence to be operated on by a sequence function is specified by a
regclass argument, which is simply the OID of the sequence in the
pg_class system catalog. You do not have to look up the OID by hand,
however, since the regclass data type's input converter will do the work
for you. See Section 8.19 for details.
--
Bruce Momjian https://momjian.us
EDB https://enterprisedb.com
Indecision is a decision. Inaction is an action. Mark Batterson
Re: nextval parameter is not clear
On Tue, Nov 22, 2022 at 2:10 PM Bruce Momjian wrote:
> On Tue, Oct 18, 2022 at 08:17:12AM +, PG Doc comments form wrote:
> > The following documentation comment has been logged on the website:
> >
> > Page: https://www.postgresql.org/docs/14/functions-sequence.html
> > Description:
> >
> > https://www.postgresql.org/docs/14/functions-sequence.html
> >
> > I don't see here any hints about how to use this function, and what the
> > Maybe add some links to other topics or clarify examples for nextval
> here.
>
> Uh, the last sentence in that section says:
>
> The sequence to be operated on by a sequence function is specified
> by a
> regclass argument, which is simply the OID of the sequence in the
> pg_class system catalog. You do not have to look up the OID by
> hand,
> however, since the regclass data type's input converter will do
> the work
> for you. See Section 8.19 for details.
>
> As someone who is "newer", I'd like to point out that a "clarifying
example" as
simple as *SELECT nextval("your_seq"::regclass); *
is about 100 times more CLEAR about the essence than that paragraph.
And, yes, I read the page, and I've seen the examples just one paragraph
lower.
A huge majority of us are hyper-visual, and learn by example. But that
example
below does not translate to this example... Unless you already know it!
I've been frustrated many times to find the documentation, and then struggle
trying to envision how the ultimate code/syntax truly reads.
I've thought about this, and I believe having a GIGANTIC page of PG SQL
code,
that could be referenced and linked, would be a WONDERFUL thing.
Then a page like this could literally have a link: "see example".
Everyone who NORMALLY reads these emails are not typically struggling
with the syntax. But the people going to documentation often are!
Regards
PS: I am willing to help create that gigantic page, if we can standardize a
way to link to it.
PPS: Even to the point of successive refinement. Over time, we may add "do
this / not this"
Re: nextval parameter is not clear
On Tue, Nov 22, 2022 at 8:42 PM Kirk Wolak wrote:
>
>
> On Tue, Nov 22, 2022 at 2:10 PM Bruce Momjian wrote:
>
>> On Tue, Oct 18, 2022 at 08:17:12AM +, PG Doc comments form wrote:
>> > The following documentation comment has been logged on the website:
>> >
>> > Page: https://www.postgresql.org/docs/14/functions-sequence.html
>> > Description:
>> >
>> > https://www.postgresql.org/docs/14/functions-sequence.html
>> >
>> > I don't see here any hints about how to use this function, and what the
>> > Maybe add some links to other topics or clarify examples for nextval
>> here.
>>
>> Uh, the last sentence in that section says:
>>
>> The sequence to be operated on by a sequence function is
>> specified by a
>> regclass argument, which is simply the OID of the sequence in the
>> pg_class system catalog. You do not have to look up the OID by
>> hand,
>> however, since the regclass data type's input converter will do
>> the work
>> for you. See Section 8.19 for details.
>>
>> As someone who is "newer", I'd like to point out that a "clarifying
> example" as
> simple as *SELECT nextval("your_seq"::regclass); *
> is about 100 times more CLEAR about the essence than that paragraph.
>
We've only fairly recently made incorporating useful and expansive examples
into the reference part of the documentation generally doable. I agree
that this particular one warrants such an example. If you are willing to
do the harder work you describe below, submit a patch for this. It's
specific, small, an improvement, and nothing Bruce said indicates it isn't
wanted, he just focused on a different aspect of the complaint.
> And, yes, I read the page, and I've seen the examples just one paragraph
> lower.
> A huge majority of us are hyper-visual, and learn by example. But that
> example
> below does not translate to this example... Unless you already know it!
>
>
Sure, and the decades old documentation written for the book era, not
YouTube and interactive tutorials, doesn't cater for that audience. That
isn't going to change at this point, and that is a good thing. But that
doesn't mean specific improvements cannot be made.
>
> Regards
> PS: I am willing to help create that gigantic page, if we can standardize
> a way to link to it.
> PPS: Even to the point of successive refinement. Over time, we may add
> "do this / not this"
>
The wiki is an excellent place to prototype and coordinate. Beyond that,
this idea falls outside what should be discussed on this thread. Here,
let's either patch the docs with some examples, or not.
David J.
