Re: [WIP] pg_ping utility

On Wed, Dec 5, 2012 at 8:53 AM, Alvaro Herrera <alvherre@2ndquadrant.com> wrote:
> Phil Sorber escribió:
>> On Mon, Dec 3, 2012 at 11:59 PM, Michael Paquier
>> <michael.paquier@gmail.com> wrote:
>
>> > - Same thing with this example:
>> > +   <para>
>> > +    Standard Usage:
>> > +    <screen>
>> > +     <prompt>$</prompt> <userinput>pg_isready</userinput>
>> > +     <prompt>$</prompt> <userinput>echo $?</userinput>
>> > +     <computeroutput>0</computeroutput>
>> > +    </screen>
>> > +   </para>
>> > For the time being PQPING_OK returns 0 because it is on top of the enum
>> > PGPing, but this might change if for a reason or another the order of
>> > outputs is changed.
>>
>> So I understand what you mean by the ordering might change, but this
>> is actual output from the shell. I'm not sure how to convey that
>> sentiment properly here and still have a real example. Perhaps just
>> remove the example?
>
> No, I think it is the reference docs on the returned value that must be
> fixed.  That is, instead of saying that the return value correspond to
> the enum values, you should be saying that it will return
> <literal>0</literal> if it's okay, 1 in another case and 2 in yet
> another case.  And then next to the PQping() enum, add a comment that
> the values must not be messed around with because pg_isready exposes
> them to users and shell scripts.

+1 I'm on board with this.

>
> --
> Álvaro Herrera                http://www.2ndQuadrant.com/
> PostgreSQL Development, 24x7 Support, Training & Services