Re: Add exclusive backup deprecation notes to documentation

On 3/18/19 4:33 PM, Peter Eisentraut wrote:
> On 2019-03-07 10:33, David Steele wrote:
>> On 3/1/19 3:14 PM, Laurenz Albe wrote:
>>> Magnus Hagander wrote:
>>>> Maybe have the first note say "This method is deprecated bceause it has serious
>>>> risks (see bellow)" and then list the actual risks at the end?
>>>
>>> Good idea.  That may attract the attention of the dogs among the readers.
>>
>> OK, here's a new version that splits the deprecation notes from the
>> discussion of risks.  I also fixed the indentation.
> 
> The documentation changes appear to continue the theme from the other
> thread that the exclusive backup mode is terrible and everyone should
> feel bad about it.  I don't think there is consensus about that.

I wouldn't characterize documenting the limitations of the method as 
making people feel bad about it.  If you feel my language implies that 
then please let me know where you see it.

> I do welcome a more precise description of the handling of backup_label
> and a better hint in the error message.  I think we haven't gotten to
> the final shape there yet, especially for the latter.  I suggest to
> focus on that.

I was planning to update the error message hint as Magnus and Michael 
have suggested.

I'm not a fan of normalizing the documentation around backup_label, i.e. 
making it seem like a perfectly normal thing that you need to manually 
delete a file to get the cluster to start.  This may still lead users to 
script their way around the problem, with possible corruption as the result.

> The other changes repeat points already made in nearby documentation.

Granted, but in this sense they are meant to concisely describe why the 
feature is deprecated, rather than being instructions in a user guide.

> I think it would be helpful to frame the documentation in a way to
> suggest that the nonexclusive mode is more for automation and more
> sophisticated tools and the exclusive mode is more for manual or simple
> scripted use.

I don't think the features were developed with this in mind and I 
wouldn't want to characterize them this way now.  Non-exclusive mode was 
developed to address the shortcomings of exclusive mode, not as an 
"automate-able" version of it.

Describing any backup method as primarily "manual" in nature seems 
counter-intuitive to me.

> If we do think that the exclusive mode will be removed in PG13, then I
> don't think we need further documentation changes.  It already says it's
> deprecated, and we don't need to justify that at length.  But again, I'm
> not convinced that that will happen.

I think we should remove it entirely in PG13, but I'm not sure if there 
is enough support.  I'll propose it again in the first CF and see where 
it goes.

This patch was intended to be a compromise based on discussion in the 
thread about removing the feature.

If this is now a bridge too far then I'm at a bit of a loss as to how to 
proceed.  If we water it down and normalize it then we are not achieving 
the goals of the patch as I see them -- to steer users away from this 
method when possible and to make it less of a shock if it goes away.

Regards,
-- 
-David
david@pgmasters.net