Обсуждение: Remove name as valid parameter for catalog functions

Patch attached which corrects the docs where catalog functions no
longer accept values of type name.  Originally a note submitted by
someone on the docs, but this affects more than just the one they
mentioned.

--
Thom Brown
Twitter: @darkixion
IRC (freenode): dark_ixion
Registered Linux user: #516935

Thom Brown <thom@linux.com> writes:
> Patch attached which corrects the docs where catalog functions no
> longer accept values of type name.  Originally a note submitted by
> someone on the docs, but this affects more than just the one they
> mentioned.

The reason those are phrased as "OID or name" is that what they take is
regclass, which means that things like pg_total_relation_size('table_name')
do in fact work.  I think the proposed wording would leave people with
the idea that they had to supply a numeric OID, which is a PITA and not
by any means the expected usage.  I agree that maybe the original
wording could use some improvement, but I don't think that just removing
"or name" is an improvement.

            regards, tom lane

On 7 March 2011 20:49, Tom Lane <tgl@sss.pgh.pa.us> wrote:
> Thom Brown <thom@linux.com> writes:
>> Patch attached which corrects the docs where catalog functions no
>> longer accept values of type name.  Originally a note submitted by
>> someone on the docs, but this affects more than just the one they
>> mentioned.
>
> The reason those are phrased as "OID or name" is that what they take is
> regclass, which means that things like pg_total_relation_size('table_name')
> do in fact work.  I think the proposed wording would leave people with
> the idea that they had to supply a numeric OID, which is a PITA and not
> by any means the expected usage.  I agree that maybe the original
> wording could use some improvement, but I don't think that just removing
> "or name" is an improvement.

That's fair enough, but it still needs changing, as whilst an OID
won't cause an error, a field with the type of name will.  Is it
reasonable to refer to a parameter as required to be of type regclass?

--
Thom Brown
Twitter: @darkixion
IRC (freenode): dark_ixion
Registered Linux user: #516935

Thom Brown <thom@linux.com> writes:
> On 7 March 2011 20:49, Tom Lane <tgl@sss.pgh.pa.us> wrote:
>> The reason those are phrased as "OID or name" is that what they take is
>> regclass, which means that things like pg_total_relation_size('table_name')
>> do in fact work.  I think the proposed wording would leave people with
>> the idea that they had to supply a numeric OID, which is a PITA and not
>> by any means the expected usage.  I agree that maybe the original
>> wording could use some improvement, but I don't think that just removing
>> "or name" is an improvement.

> That's fair enough, but it still needs changing, as whilst an OID
> won't cause an error, a field with the type of name will.  Is it
> reasonable to refer to a parameter as required to be of type regclass?

Well, the table entries for those functions already show that the
parameter is of type regclass.  I think the purpose of the text
descriptions is to help out people who might not immediately get the
implications of that.

Maybe we could say "the name or OID of a table", or some such phrase,
so as to subtly avoid the expectation that what is being referred to
is the datatype named "name"?

            regards, tom lane

On 7 March 2011 23:30, Tom Lane <tgl@sss.pgh.pa.us> wrote:
> Thom Brown <thom@linux.com> writes:
>> On 7 March 2011 20:49, Tom Lane <tgl@sss.pgh.pa.us> wrote:
>>> The reason those are phrased as "OID or name" is that what they take is
>>> regclass, which means that things like pg_total_relation_size('table_name')
>>> do in fact work.  I think the proposed wording would leave people with
>>> the idea that they had to supply a numeric OID, which is a PITA and not
>>> by any means the expected usage.  I agree that maybe the original
>>> wording could use some improvement, but I don't think that just removing
>>> "or name" is an improvement.
>
>> That's fair enough, but it still needs changing, as whilst an OID
>> won't cause an error, a field with the type of name will.  Is it
>> reasonable to refer to a parameter as required to be of type regclass?
>
> Well, the table entries for those functions already show that the
> parameter is of type regclass.  I think the purpose of the text
> descriptions is to help out people who might not immediately get the
> implications of that.
>
> Maybe we could say "the name or OID of a table", or some such phrase,
> so as to subtly avoid the expectation that what is being referred to
> is the datatype named "name"?

Yes, that would remove the ambiguity. :)

--
Thom Brown
Twitter: @darkixion
IRC (freenode): dark_ixion
Registered Linux user: #516935

Thom Brown <thom@linux.com> writes:
> On 7 March 2011 23:30, Tom Lane <tgl@sss.pgh.pa.us> wrote:
>> Maybe we could say "the name or OID of a table", or some such phrase,
>> so as to subtly avoid the expectation that what is being referred to
>> is the datatype named "name"?

> Yes, that would remove the ambiguity. :)

That wording turned out not to work well in context, at least not
without major surgery on the containing sentences.  I decided that
the best way was to just say "specified table" in the function tables,
and then borrow the paragraph that explains about regclass
arguments from the sequence-functions page.

http://git.postgresql.org/gitweb?p=postgresql.git;a=commitdiff;h=cfcdc99db67172d46a5e226375fa97e5c5a62267

            regards, tom lane

On 8 March 2011 02:54, Tom Lane <tgl@sss.pgh.pa.us> wrote:
> Thom Brown <thom@linux.com> writes:
>> On 7 March 2011 23:30, Tom Lane <tgl@sss.pgh.pa.us> wrote:
>>> Maybe we could say "the name or OID of a table", or some such phrase,
>>> so as to subtly avoid the expectation that what is being referred to
>>> is the datatype named "name"?
>
>> Yes, that would remove the ambiguity. :)
>
> That wording turned out not to work well in context, at least not
> without major surgery on the containing sentences.  I decided that
> the best way was to just say "specified table" in the function tables,
> and then borrow the paragraph that explains about regclass
> arguments from the sequence-functions page.

Thanks Tom.

--
Thom Brown
Twitter: @darkixion
IRC (freenode): dark_ixion
Registered Linux user: #516935