Remove name as valid parameter for catalog functions

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