[HACKERS] Function argument names in pg_catalog

[Mike Toews]

Hi hackers,

I'm curios why argument names (argname) are not used in the DDL for
functions in pg_catalog, while they are are used throughout the
documentation. For example, the documentation for pg_read_file in
Table 9-60[1] has an SQL prototype:
pg_read_file(filename text, offset bigint, length bigint)

then why isn't the DDL for the function instead something like:

CREATE OR REPLACE FUNCTION
  public.pg_read_file(filename text, offset bigint, length bigint)
  RETURNS text AS 'pg_read_file'
  LANGUAGE internal VOLATILE STRICT COST 1;

There are two advantages for using argument names for function
definitions: to add extra documentation for the parameters, and allow
named notation (where applicable).

For the extra documentation[2] point, the SQL prototype is visible
in PgAdmin or psql. For example, with the above example try \df
public.pg_read_file, the fourth column shows 'filename text, offset
bigint, length bigint' in the fourth column. The existing \df
pg_catalog.pg_read_file returns text, bigint, bigint, which sends
the user to look up the function in the documentation to determine
which bigint parameter is for length or offset. Having built-in
extra documentation saves this trip.

For the named notation[3] rational, a user can rearrange the arguments:
select public.pg_read_file(offset := 200, length := 10, filename := 'myfile')
or more practically, if parameters in the function were defined with
default_expr, then the named parameters can be used while omitting
default_expr parameters to accept defaults.

Are there any drawbacks? Performance/bloat? Technical limitations?

Apologies for my ignorance on how the DDL for functions in pg_catalog
are defined. I can only assume they are generated from their internal
C functions, as I can't find a pg_catalog.sql file in the source.

Thanks for your thoughts,
-Mike

[1] http://www.postgresql.org/docs/current/static/functions-admin.html
[2] http://www.postgresql.org/docs/current/static/sql-createfunction.html
[3] http://www.postgresql.org/docs/current/static/sql-syntax-calling-funcs.html

-- 
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

Re: [HACKERS] Function argument names in pg_catalog

[Alvaro Herrera]

Excerpts from Mike Toews's message of mar jul 19 07:23:24 -0400 2011:
 Hi hackers,
 
 I'm curios why argument names (argname) are not used in the DDL for
 functions in pg_catalog, while they are are used throughout the
 documentation. For example, the documentation for pg_read_file in
 Table 9-60[1] has an SQL prototype:
 pg_read_file(filename text, offset bigint, length bigint)
 
 then why isn't the DDL for the function instead something like:
 
 CREATE OR REPLACE FUNCTION
   public.pg_read_file(filename text, offset bigint, length bigint)
   RETURNS text AS 'pg_read_file'
   LANGUAGE internal VOLATILE STRICT COST 1;

Probably mostly historical.  We only got argument names (useful argument
names) recently.

 Apologies for my ignorance on how the DDL for functions in pg_catalog
 are defined. I can only assume they are generated from their internal
 C functions, as I can't find a pg_catalog.sql file in the source.

They are generated from pg_proc.h.  I think we only have argument names
for functions that have OUT arguments.  See the pg_stat_file entry for
an example.

I'm not sure how open we are to adding names to more builtin functions.
If catalog bloat is the only problem it'd cause, my guess is that it
should be OK.  I know that I have personally been bitten by not having
argument names in builtin functions; they are pretty good run-time
documentation.

-- 
Álvaro Herrera alvhe...@commandprompt.com
The PostgreSQL Company - Command Prompt, Inc.
PostgreSQL Replication, Consulting, Custom Development, 24x7 support

-- 
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers