Re: Improve This Sentence?

[Dave Cramer]

On Sun, 12 Apr 2020 at 20:57, Michael Paquier  wrote:

> On Fri, Apr 10, 2020 at 06:32:05PM +, PG Doc comments form wrote:
> > On Linux and POSIX platforms checkpoint_flush_after allows to force the
> OS
> > that pages written by the checkpoint should be flushed to disk after a
> > configurable number of bytes.
> >
> > I think I have an idea what it says, but saw some discussion to this very
> > issue.  Can it be re-written?
>
> How would you suggest to rewrite it?
>

This is interesting here is the entire paragraph in question from 29.4. WAL
Configuration

On Linux and POSIX platforms checkpoint_flush_after

allows
to force the OS that pages written by the checkpoint should be flushed to
disk after a configurable number of bytes. Otherwise, these pages may be
kept in the OS's page cache, inducing a stall when fsync is issued at the
end of a checkpoint. This setting will often help to reduce transaction
latency, but it also can have an adverse effect on performance;
particularly for workloads that are bigger than shared_buffers
,
but smaller than the OS's page cache.

and here is another paragraph which is much better from 19.5.2. Checkpoints

Whenever more than this amount of data has been written while performing a
checkpoint, attempt to force the OS to issue these writes to the underlying
storage. Doing so will limit the amount of dirty data in the kernel's page
cache, reducing the likelihood of stalls when an fsync is issued at the end
of the checkpoint, or when the OS writes data back in larger batches in the
background. Often that will result in greatly reduced transaction latency,
but there also are some cases, especially with workloads that are bigger
than shared_buffers
,
but smaller than the OS's page cache, where performance might degrade. This
setting may have no effect on some platforms. If this value is specified
without units, it is taken as blocks, that is BLCKSZ bytes, typically 8kB.
The valid range is between 0, which disables forced writeback, and 2MB. The
default is 256kB on Linux, 0 elsewhere. (If BLCKSZ is not 8kB, the default
and maximum values scale proportionally to it.) This parameter can only be
set in the postgresql.conf file or on the server command line.

Ironically the first one above is supposed to be providing more clarity if
you can believe:
For additional information on tuning these settings, see Section 29.4.

Clearly just copying the text from 19.5.2 to 29.4 is an improvement. I'd be
somewhat loathe to be that repetitive but honestly I don't have a better
suggestion

Dave

https://www.postgres.rocks

>
>

Re: Getting our tables to render better in PDF output

[Corey Huinker]

>
>
> I did a quick check by adding id tags to all 700-or-so s in
> func.sgml (don't get excited, it was a perl one-liner that just added
> random id strings).


I did, actually, get excited for a second.


> The runtime difference for building the HTML docs
> seems to be under 1%, and negligible for PDF output.  So it looks like
> we don't have to worry about scalability of tagging all the functions.
>

Ok, so that's the function anchors.

So some references to functions are just the name, and xrefs will work fine
for those.

I was thinking that there were references that included parameters, but I'm
not finding any with actual parameter values, so at most we'd lose the "()"
of a reference.

Assuming we want to make the anchors visible, we need a way for people to
discover the anchors we've made, and my thought there is that we make the
first definition a non-xref link to the indexterm just above it. Any
thoughts on what the best way to do that is?

Re: Getting our tables to render better in PDF output

[Tom Lane]

Corey Huinker  writes:
> I was thinking that there were references that included parameters, but I'm
> not finding any with actual parameter values, so at most we'd lose the "()"
> of a reference.

We could possibly stick the parens into the indexterm text.  Arguably
that's an improvement on its own merits, since it'd become clearer which
index entries are function names.  If you don't want that, another idea is
to put xreflabel options that include the parens into the indexterm tags.
Or we can just standardize on not having parens, but personally I like
them.  Without parens, for clarity you really have to write "function
foo" which is redundant-looking in the XML and hence
easy to get wrong.

> Assuming we want to make the anchors visible, we need a way for people to
> discover the anchors we've made, and my thought there is that we make the
> first definition a non-xref link to the indexterm just above it. Any
> thoughts on what the best way to do that is?

I'm not really buying into that as a requirement.  For one thing, the
anchor name will be 100% predictable.

One thing that I noticed while playing with this last night is that
even though  or  links will take you right to the exact
table entry, the index entries generated from the indexterms only
point to the page.  That seems pretty sad, why isn't it better?

regards, tom lane

Re: Getting our tables to render better in PDF output

[Corey Huinker]

On Mon, Apr 13, 2020 at 12:28 PM Tom Lane  wrote:

> Corey Huinker  writes:
> > I was thinking that there were references that included parameters, but
> I'm
> > not finding any with actual parameter values, so at most we'd lose the
> "()"
> > of a reference.
>
> We could possibly stick the parens into the indexterm text.  Arguably
> that's an improvement on its own merits, since it'd become clearer which
> index entries are function names.  If you don't want that, another idea is
> to put xreflabel options that include the parens into the indexterm tags.
> Or we can just standardize on not having parens, but personally I like
> them.  Without parens, for clarity you really have to write "function
> foo" which is redundant-looking in the XML and hence
> easy to get wrong.
>

That makes sense to me. There may be some hope for the font via the
xrefstyle attribute, but I'm not educated well enough on docbook to know
for sure.


> > Assuming we want to make the anchors visible, we need a way for people to
> > discover the anchors we've made, and my thought there is that we make the
> > first definition a non-xref link to the indexterm just above it. Any
> > thoughts on what the best way to do that is?
>
> I'm not really buying into that as a requirement.  For one thing, the
> anchor name will be 100% predictable.
>

The anchor name is deterministic (or I intend it to be) but
the existence of the link is not predictable. So while having no visible
link is fine for internal links which we create, I'm envisioning a
not-very-experienced reader wanting to help an even-less-experienced
person. If they find the date_part function, and they see that the word
"date_part" is itself clickable, they'll probably click it once, see that
it's a link, and send the less-experienced person the anchored link instead
of the broader page link. They're very unlikely to try to forge their own
anchor link in the hopes that it already exists.

One thing that I noticed while playing with this last night is that
> even though  or  links will take you right to the exact
> table entry, the index entries generated from the indexterms only
> point to the page.  That seems pretty sad, why isn't it better?
>

As you've described it it does seem very odd, but maybe I'm just
misunderstanding.

Re: Getting our tables to render better in PDF output

[Tom Lane]

Corey Huinker  writes:
> On Mon, Apr 13, 2020 at 12:28 PM Tom Lane  wrote:
>> I'm not really buying into that as a requirement.  For one thing, the
>> anchor name will be 100% predictable.

> The anchor name is deterministic (or I intend it to be) but
> the existence of the link is not predictable. So while having no visible
> link is fine for internal links which we create, I'm envisioning a
> not-very-experienced reader wanting to help an even-less-experienced
> person. If they find the date_part function, and they see that the word
> "date_part" is itself clickable, they'll probably click it once, see that
> it's a link, and send the less-experienced person the anchored link instead
> of the broader page link. They're very unlikely to try to forge their own
> anchor link in the hopes that it already exists.

Meh.  I think people are going to think that a link that points at
itself is pretty silly.

Now, if the link appearing in the index were precise, people might
copy that one and use it ...

BTW, I just noticed that the way that the index is rendered on the website
is beyond awful.  The sub-items of an index entry are left-justified
instead of being indented as they ought to be (and are, if you build
the docs locally without using the website style).  This makes it look
like the sub-entries are main entries which is totally confusing.
Can somebody fix that?

regards, tom lane

Ambiguos statement in wal-async-commit page

[PG Doc comments form]

The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/12/wal-async-commit.html
Description:

In this page:
https://www.postgresql.org/docs/current/wal-async-commit.html

In this paragraph:
Certain utility commands, for instance DROP TABLE, are forced to commit
synchronously regardless of the setting of synchronous_commit. This is to
ensure consistency between the server's file system and the logical state of
the database. The commands supporting two-phase commit, such as PREPARE
TRANSACTION, are also always synchronous.

> This is to ensure consistency between the server's file system and the
logical state of the database.

Here I don't understand how inconsistency is introduced, if  DROP TABLE or
PREPARE transactions is not logged.
Considering drop table is like any other transaction, the user is informed
that the table is dropped, and the system crashed, it didn't actually
perform the action of dropping table nor was it logged in WAL, then how it
would cause inconsistency.
Isn't it similar to losing any other last transaction, if not logged.

Thank you.

Re: Ambiguos statement in wal-async-commit page

[Laurenz Albe]

On Mon, 2020-04-13 at 21:11 +, PG Doc comments form wrote:
> The following documentation comment has been logged on the website:
> 
> Page: https://www.postgresql.org/docs/12/wal-async-commit.html
> Description:
> 
> In this page:
> https://www.postgresql.org/docs/current/wal-async-commit.html
> 
> In this paragraph:
> Certain utility commands, for instance DROP TABLE, are forced to commit
> synchronously regardless of the setting of synchronous_commit. This is to
> ensure consistency between the server's file system and the logical state of
> the database. The commands supporting two-phase commit, such as PREPARE
> TRANSACTION, are also always synchronous.
> 
> > This is to ensure consistency between the server's file system and the
> logical state of the database.
> 
> Here I don't understand how inconsistency is introduced, if  DROP TABLE or
> PREPARE transactions is not logged.
> Considering drop table is like any other transaction, the user is informed
> that the table is dropped, and the system crashed, it didn't actually
> perform the action of dropping table nor was it logged in WAL, then how it
> would cause inconsistency.
> Isn't it similar to losing any other last transaction, if not logged.

Operations *are* logged even if "synchronous_commit" is "off".

The difference is that the log is not flushed out to disk at commit time.

Imagine you run DROP TABLE, and the transaction commits without flushing
WAL.  The file that belongs to the table is removed during the commit.
Now if there is a crash, it could happen that the transaction didn't
happen (because the WAL wasn't persisted yet), but the file is already
gone.  This would be data corruption.

Yours,
Laurenz Albe