Re: Documentation Update: Document pg_start_backup checkpoint behavior

I wrote:
> Heikki Linnakangas <heikki(dot)linnakangas(at)enterprisedb(dot)com> writes:
>> Rather than deplore that you can't expedite the checkpoint, why don't we
>> just make it possible?

> +1

>> The first question is what the default behavior should be? We've seen
>> enough complaints and I've been bitten by that myself during development
>> of other stuff often enough that I think we should change the default to
>> immediate. From backwards-compatibility point of view, we shouldn't
>> change the default, but then again an immediate checkpoint was what you
>> got before 8.3.

> I think we shouldn't change the default. Which puts a hole in your
> suggestion for function naming. But then again, I like the extra
> argument better anyway ...

I'm going to go ahead and make this happen, using the arrangement

pg_start_backup('label') -> slow checkpoint (backwards compatible)
pg_start_backup('label', false) -> slow checkpoint
pg_start_backup('label', true) -> immediate checkpoint

Bruce suggested what seemed like an excellent idea, which is to make
this self-documenting using the new default-arguments feature ---
it'll look something like this in \df:

regression=# create function foo (label text, fast bool = false) returns int as $$select 1$$ language sql;
CREATE FUNCTION
regression=# \df foo
List of functions
Schema | Name | Result data type | Argument data types
--------+------+------------------+----------------------------------------
public | foo | integer | label text, fast boolean DEFAULT false
(1 row)

regards, tom lane