Re: Documentation Update: Document pg_start_backup checkpoint behavior

I wrote:
> Heikki Linnakangas <heikki.linnakangas@enterprisedb.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 functionsSchema | Name | Result data type |          Argument
datatypes           
 
--------+------+------------------+----------------------------------------public | foo  | integer          | label
text,fast boolean DEFAULT false
 
(1 row)

        regards, tom lane