pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedRemove name as valid parameter for catalog functions
7+ messages / 2 participants
[nested] [flat]
* Remove name as valid parameter for catalog functions
@ 2011-03-07 13:57 Thom Brown <thom@linux.com>
0 siblings, 1 reply; 7+ messages in thread
From: Thom Brown @ 2011-03-07 13:57 UTC (permalink / raw)
To: pgsql-docs; +Cc: pgadmin-hackers <pgadmin-hackers@postgresql.org>
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
Attachments:
fix_oid_only_catalog_funcs.patch (application/octet-stream, 2.1K) download
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 5ccece2..82e6deb 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -14342,7 +14342,7 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup());
<entry><type>bigint</type></entry>
<entry>
Total disk space used by indexes attached to the table with the
- specified OID or name
+ specified OID
</entry>
</row>
<row>
@@ -14353,7 +14353,7 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup());
<entry>
Disk space used by the specified fork (<literal>'main'</literal>,
<literal>'fsm'</literal> or <literal>'vm'</>)
- of the table or index with the specified OID or name
+ of the table or index with the specified OID
</entry>
</row>
<row>
@@ -14378,7 +14378,7 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup());
</entry>
<entry><type>bigint</type></entry>
<entry>
- Disk space used by the table with the specified OID or name,
+ Disk space used by the table with the specified OID,
excluding indexes (but including TOAST, free space map, and visibility
map)
</entry>
@@ -14403,7 +14403,7 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup());
</entry>
<entry><type>bigint</type></entry>
<entry>
- Total disk space used by the table with the specified OID or name,
+ Total disk space used by the table with the specified OID,
including all indexes and <acronym>TOAST</> data
</entry>
</row>
@@ -14417,7 +14417,7 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup());
</para>
<para>
- <function>pg_total_relation_size</> accepts the OID or name of a
+ <function>pg_total_relation_size</> accepts the OID of a
table or toast table, and returns the total on-disk space used for
that table, including all associated indexes. This function is
equivalent to <function>pg_table_size</function>
* Re: [DOCS] Remove name as valid parameter for catalog functions
@ 2011-03-07 15:19 Tom Lane <tgl@sss.pgh.pa.us>
parent: Thom Brown <thom@linux.com>
0 siblings, 1 reply; 7+ messages in thread
From: Tom Lane @ 2011-03-07 15:19 UTC (permalink / raw)
To: Thom Brown <thom@linux.com>; +Cc: pgsql-docs; pgadmin-hackers <pgadmin-hackers@postgresql.org>
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
^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: [DOCS] Remove name as valid parameter for catalog functions
@ 2011-03-07 17:36 Thom Brown <thom@linux.com>
parent: Tom Lane <tgl@sss.pgh.pa.us>
0 siblings, 1 reply; 7+ messages in thread
From: Thom Brown @ 2011-03-07 17:36 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: pgsql-docs; pgadmin-hackers <pgadmin-hackers@postgresql.org>
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
^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: Remove name as valid parameter for catalog functions
@ 2011-03-07 18:00 Tom Lane <tgl@sss.pgh.pa.us>
parent: Thom Brown <thom@linux.com>
0 siblings, 1 reply; 7+ messages in thread
From: Tom Lane @ 2011-03-07 18:00 UTC (permalink / raw)
To: Thom Brown <thom@linux.com>; +Cc: pgsql-docs
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
^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: Remove name as valid parameter for catalog functions
@ 2011-03-07 18:07 Thom Brown <thom@linux.com>
parent: Tom Lane <tgl@sss.pgh.pa.us>
0 siblings, 1 reply; 7+ messages in thread
From: Thom Brown @ 2011-03-07 18:07 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: pgsql-docs
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
^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: Remove name as valid parameter for catalog functions
@ 2011-03-07 21:24 Tom Lane <tgl@sss.pgh.pa.us>
parent: Thom Brown <thom@linux.com>
0 siblings, 1 reply; 7+ messages in thread
From: Tom Lane @ 2011-03-07 21:24 UTC (permalink / raw)
To: Thom Brown <thom@linux.com>; +Cc: pgsql-docs
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=cfcdc99db67172d46a5e226375fa97e5c5a...
regards, tom lane
^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: Remove name as valid parameter for catalog functions
@ 2011-03-08 03:33 Thom Brown <thom@linux.com>
parent: Tom Lane <tgl@sss.pgh.pa.us>
0 siblings, 0 replies; 7+ messages in thread
From: Thom Brown @ 2011-03-08 03:33 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: pgsql-docs
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
^ permalink raw reply [nested|flat] 7+ messages in thread
end of thread, other threads:[~2011-03-08 03:33 UTC | newest]
Thread overview: 7+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2011-03-07 13:57 Remove name as valid parameter for catalog functions Thom Brown <thom@linux.com>
2011-03-07 15:19 ` Tom Lane <tgl@sss.pgh.pa.us>
2011-03-07 17:36 ` Thom Brown <thom@linux.com>
2011-03-07 18:00 ` Tom Lane <tgl@sss.pgh.pa.us>
2011-03-07 18:07 ` Thom Brown <thom@linux.com>
2011-03-07 21:24 ` Tom Lane <tgl@sss.pgh.pa.us>
2011-03-08 03:33 ` Thom Brown <thom@linux.com>
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox