Error in 9.6 documentation? checkpoint_flush_after

On Fri, Mar 1, 2019 at 05:58:21AM +0000, PG Doc comments form wrote:

The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/9.6/runtime-config-wal.html
Description:

https://www.postgresql.org/docs/9.6/runtime-config-wal.html
19.5.2

checkpoint_flush_after (integer)

Whenever more than checkpoint_flush_after bytes have been written while
performing a checkpoint, attempt to force the OS to issue these writes to
the ...

bytes or pages? postgresql.conf says pages

You bring up a good point. This problem affects these postgresql.conf
variables:

bgwriter_flush_after
backend_flush_after
checkpoint_flush_after

and probably more. The issue is that the value is in bytes, as opposed
to a value of time, like milliseconds. You can specify the bytes in
terms of the number of pages, e.g., 2 = 16kB, or you can specify it
directly in bytes, e.g., 32kB.

The line in postgresql.conf is saying:

#checkpoint_flush_after = 256kB # measured in pages, 0 disables
-----------------

if you specify a number like:

checkpoint_flush_after = 12

that is 12 * 8kB or 96kB. If you specify an actual byte amount like
256kB, that is the value that is used.

Do you have any suggestions on how this could be made clearer?

--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ As you are, so once was I.  As I am, so you will be. +
+                      Ancient Roman grave inscription +

Hi,

On 2019-03-05 11:05:31 -0500, Bruce Momjian wrote:

On Fri, Mar 1, 2019 at 05:58:21AM +0000, PG Doc comments form wrote:

The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/9.6/runtime-config-wal.html
Description:

https://www.postgresql.org/docs/9.6/runtime-config-wal.html
19.5.2

checkpoint_flush_after (integer)

Whenever more than checkpoint_flush_after bytes have been written while
performing a checkpoint, attempt to force the OS to issue these writes to
the ...

bytes or pages? postgresql.conf says pages

It's bytes, rounded to pages. Describing it as pages is too complicated
because we'd need to reference the block size for it to make sense etc.
What's the problem with describing it in bytes?

You bring up a good point. This problem affects these postgresql.conf
variables:

bgwriter_flush_after
backend_flush_after
checkpoint_flush_after

and probably more. The issue is that the value is in bytes, as opposed
to a value of time, like milliseconds. You can specify the bytes in
terms of the number of pages, e.g., 2 = 16kB, or you can specify it
directly in bytes, e.g., 32kB.

I'm not following? Why is bytes vs time a problem? We have similar
base-unit issues in plenty time based GUCs?

Greetings,

Andres Freund

On Tue, Mar 5, 2019 at 09:11:14AM -0800, Andres Freund wrote:

Hi,

On 2019-03-05 11:05:31 -0500, Bruce Momjian wrote:

On Fri, Mar 1, 2019 at 05:58:21AM +0000, PG Doc comments form wrote:

The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/9.6/runtime-config-wal.html
Description:

https://www.postgresql.org/docs/9.6/runtime-config-wal.html
19.5.2

checkpoint_flush_after (integer)

Whenever more than checkpoint_flush_after bytes have been written while
performing a checkpoint, attempt to force the OS to issue these writes to
the ...

bytes or pages? postgresql.conf says pages

It's bytes, rounded to pages. Describing it as pages is too complicated
because we'd need to reference the block size for it to make sense etc.
What's the problem with describing it in bytes?

Well, if postgrsql.conf has:

checkpoint_flush_after = 2

it is intepreted in pages and output as bytes:

SHOW checkpoint_flush_after;
checkpoint_flush_after
------------------------
16kB

You bring up a good point. This problem affects these postgresql.conf
variables:

bgwriter_flush_after
backend_flush_after
checkpoint_flush_after

and probably more. The issue is that the value is in bytes, as opposed
to a value of time, like milliseconds. You can specify the bytes in
terms of the number of pages, e.g., 2 = 16kB, or you can specify it
directly in bytes, e.g., 32kB.

I'm not following? Why is bytes vs time a problem? We have similar
base-unit issues in plenty time based GUCs?

I am only pointing out that pages and literal bytes are all bytes, while
wal_writer_delay is time, e.g., 200ms.

--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ As you are, so once was I.  As I am, so you will be. +
+                      Ancient Roman grave inscription +