Make argument names of pg_get_object_address consistent, and fix docs.

pg_get_object_address and pg_identify_object_as_address are supposed
to be inverses, but they disagreed as to the names of the arguments
representing the textual form of an object address.  Moreover, the
documented argument names didn't agree with reality at all, either
for these functions or pg_identify_object.

In HEAD and v11, I think we can get away with renaming the input
arguments of pg_get_object_address to match the outputs of
pg_identify_object_as_address.  In theory that might break queries
using named-argument notation to call pg_get_object_address, but
it seems really unlikely that anybody is doing that, or that they'd
have much trouble adjusting if they were.  In older branches, we'll
just live with the lack of consistency.

Aside from fixing the documentation of these functions to match reality,
I couldn't resist the temptation to do some copy-editing.

Per complaint from Jean-Pierre Pelletier.  Back-patch to 9.5 where these
functions were introduced.  (Before v11, this is a documentation change
only.)

Discussion: https://postgr.es/m/CANGqjDnWH8wsTY_GzDUxbt4i=y-85SJreZin4Hm8uOqv1vzRQA@mail.gmail.com

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index df847c0df6c531195106daaa0f2b81b34d371855..335900a86ef10d2a77dba8a8829b741a97681187 100644 (file)
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -17700,24 +17700,24 @@ SELECT collation for ('foo' COLLATE "de_DE");
 
      
       
-       pg_describe_object(catalog_id, object_id, object_sub_id>)
+       pg_describe_object(classid oid, objid oid, objsubid integer>)
        text
        get description of a database object
       
       
-       pg_identify_object(catalog_id oid, object_id oid, object_sub_id integer)
+       pg_identify_object(classid oid, objid oid, objsubid integer)
        type text, schema text, name text, identity text
        get identity of a database object
       
       
-       pg_identify_object_as_address(catalog_id oid, object_id oid, object_sub_id integer)
-       type text, name text[], args text[]
+       pg_identify_object_as_address(classid oid, objid oid, objsubid integer)
+       type text, object_names text[], object_args text[]
        get external representation of a database object's address
       
       
-       pg_get_object_address(type text, name text[], args text[])
-       catalog_id oid, object_id oid, object_sub_id int32
-       get address of a database object, from its external representation
+       pg_get_object_address(type text, object_names text[], object_args text[])
+       classid oid, objid oid, objsubid integer
+       get address of a database object from its external representation
       
      
     
@@ -17725,7 +17725,9 @@ SELECT collation for ('foo' COLLATE "de_DE");
 
   
    pg_describe_object returns a textual description of a database
-   object specified by catalog OID, object OID and a (possibly zero) sub-object ID.
+   object specified by catalog OID, object OID, and sub-object ID (such as
+   a column number within a table; the sub-object ID is zero when referring
+   to a whole object).
    This description is intended to be human-readable, and might be translated,
    depending on server configuration.
    This is useful to determine the identity of an object as stored in the
@@ -17734,29 +17736,30 @@ SELECT collation for ('foo' COLLATE "de_DE");
 
   
    pg_identify_object returns a row containing enough information
-   to uniquely identify the database object specified by catalog OID, object OID and a
-   (possibly zero) sub-object ID.  This information is intended to be machine-readable,
+   to uniquely identify the database object specified by catalog OID, object OID and
+   sub-object ID.  This information is intended to be machine-readable,
    and is never translated.
    type identifies the type of database object;
    schema is the schema name that the object belongs in, or
    NULL for object types that do not belong to schemas;
-   name is the name of the object, quoted if necessary, only
-   present if it can be used (alongside schema name, if pertinent) as a unique
-   identifier of the object, otherwise NULL;
-   identity is the complete object identity, with the precise format
-   depending on object type, and each part within the format being
-   schema-qualified and quoted as necessary.
+   name is the name of the object, quoted if necessary,
+   if the name (along with schema name, if pertinent) is sufficient to
+   uniquely identify the object, otherwise NULL;
+   identity is the complete object identity, with the
+   precise format depending on object type, and each name within the format
+   being schema-qualified and quoted as necessary.
   
 
   
    pg_identify_object_as_address returns a row containing
    enough information to uniquely identify the database object specified by
-   catalog OID, object OID and a (possibly zero) sub-object ID.  The returned
+   catalog OID, object OID and sub-object ID.  The returned
    information is independent of the current server, that is, it could be used
    to identify an identically named object in another server.
    type identifies the type of database object;
-   name and args are text arrays that together
-   form a reference to the object.  These three columns can be passed to
+   object_names and object_args
+   are text arrays that together form a reference to the object.
+   These three values can be passed to
    pg_get_object_address to obtain the internal address
    of the object.
    This function is the inverse of pg_get_object_address.
@@ -17769,10 +17772,10 @@ SELECT collation for ('foo' COLLATE "de_DE");
    ones that would be used in system catalogs such as pg_depend
    and can be passed to other system functions such as
    pg_identify_object or pg_describe_object.
-   catalog_id is the OID of the system catalog containing the
+   classid is the OID of the system catalog containing the
    object;
-   object_id is the OID of the object itself, and
-   object_sub_id is the object sub-ID, or zero if none.
+   objid is the OID of the object itself, and
+   objsubid is the sub-object ID, or zero if none.
    This function is the inverse of pg_identify_object_as_address.
   
 
@@ -20661,23 +20664,23 @@ FOR EACH ROW EXECUTE FUNCTION suppress_redundant_updates_trigger();
       
        
         classid
-        Oid
+        oid
         OID of catalog the object belongs in
        
        
         objid
-        Oid
-        OID of the object in the catalog
+        oid
+        OID of the object itself
        
        
         objsubid
         integer
-        Object sub-id (e.g. attribute number for columns)
+        Sub-object ID (e.g. attribute number for a column)
        
        
         command_tag
         text
-        command tag
+        Command tag
        
        
         object_type
@@ -20696,14 +20699,14 @@ FOR EACH ROW EXECUTE FUNCTION suppress_redundant_updates_trigger();
         object_identity
         text
         
-         Text rendering of the object identity, schema-qualified. Each and every
-         identifier present in the identity is quoted if necessary.
+         Text rendering of the object identity, schema-qualified. Each
+         identifier included in the identity is quoted if necessary.
         
        
        
         in_extension
         bool
-        whether the command is part of an extension script
+        True if the command is part of an extension script
        
        
         command
@@ -20748,29 +20751,29 @@ FOR EACH ROW EXECUTE FUNCTION suppress_redundant_updates_trigger();
       
        
         classid
-        Oid
+        oid
         OID of catalog the object belonged in
        
        
         objid
-        Oid
-        OID the object had within the catalog
+        oid
+        OID of the object itself
        
        
         objsubid
-        int32
-        Object sub-id (e.g. attribute number for columns)
+        integer
+        Sub-object ID (e.g. attribute number for a column)
        
        
         original
         bool
-        Flag used to identify the root object(s) of the deletion
+        True if this was one of the root object(s) of the deletion
        
        
         normal
         bool
         
-         Flag indicating that there's a normal dependency relationship
+         True if there was a normal dependency relationship
          in the dependency graph leading to this object
         
        
@@ -20778,7 +20781,7 @@ FOR EACH ROW EXECUTE FUNCTION suppress_redundant_updates_trigger();
         is_temporary
         bool
         
-         Flag indicating that the object was a temporary object.
+         True if this was a temporary object
         
        
        
@@ -20807,8 +20810,8 @@ FOR EACH ROW EXECUTE FUNCTION suppress_redundant_updates_trigger();
         object_identity
         text
         
-         Text rendering of the object identity, schema-qualified. Each and every
-         identifier present in the identity is quoted if necessary.
+         Text rendering of the object identity, schema-qualified. Each
+         identifier included in the identity is quoted if necessary.
         
        
        
@@ -20816,17 +20819,17 @@ FOR EACH ROW EXECUTE FUNCTION suppress_redundant_updates_trigger();
         text[]
         
          An array that, together with object_type and
-         address_args,
-         can be used by the pg_get_object_address() to
+         address_args, can be used by
+         the pg_get_object_address() function to
          recreate the object address in a remote server containing an
-         identically named object of the same kind.
+         identically named object of the same kind
         
        
        
         address_args
         text[]
         
-         Complement for address_names above.
+         Complement for address_names
         
        
       

diff --git a/src/include/catalog/catversion.h b/src/include/catalog/catversion.h
index a365807dab173c3846c1293ab2ea6023cb38d01f..f898a2225fef6ebe302cc6e832ac7fb840129076 100644 (file)
--- a/src/include/catalog/catversion.h
+++ b/src/include/catalog/catversion.h
@@ -53,6 +53,6 @@
  */
 
 /*                         yyyymmddN */
-#define CATALOG_VERSION_NO 201809042
+#define CATALOG_VERSION_NO 201809052
 
 #endif

diff --git a/src/include/catalog/pg_proc.dat b/src/include/catalog/pg_proc.dat
index a14651010f273587654f3d8f9af1104ac8a07d35..860571440a57c2364ade9e4fd0ae4c81201cfa92 100644 (file)
--- a/src/include/catalog/pg_proc.dat
+++ b/src/include/catalog/pg_proc.dat
@@ -5907,7 +5907,7 @@
   prorettype => 'record', proargtypes => 'text _text _text',
   proallargtypes => '{text,_text,_text,oid,oid,int4}',
   proargmodes => '{i,i,i,o,o,o}',
-  proargnames => '{type,name,args,classid,objid,objsubid}',
+  proargnames => '{type,object_names,object_args,classid,objid,objsubid}',
   prosrc => 'pg_get_object_address' },
 
 { oid => '2079', descr => 'is table visible in search path?',