From 5b114b045a479e584be9252dedac4c357c456311 Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Wed, 5 Sep 2018 13:47:16 -0400 Subject: [PATCH] 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 --- doc/src/sgml/func.sgml | 107 +++++++++++++++++++++-------------------- 1 file changed, 55 insertions(+), 52 deletions(-) diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index 9f2b1d4923..4f4083711b 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -17015,24 +17015,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) - type text, schema text, name text, identity text + 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, name text[], args text[]) + classid oid, objid oid, objsubid integer + get address of a database object from its external representation @@ -17040,7 +17040,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 @@ -17049,30 +17051,31 @@ 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. + 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, + 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 - pg_get_object_address to obtain the internal address + type identifies the type of database object; + 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. @@ -17081,13 +17084,13 @@ SELECT collation for ('foo' COLLATE "de_DE"); pg_get_object_address returns a row containing enough information to uniquely identify the database object specified by its type and object name and argument arrays. The returned values are the - ones that would be used in system catalogs such as pg_depend + 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 + pg_identify_object or pg_describe_object. + 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. @@ -19782,23 +19785,23 @@ FOR EACH ROW EXECUTE PROCEDURE 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 @@ -19817,14 +19820,14 @@ FOR EACH ROW EXECUTE PROCEDURE 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 @@ -19869,29 +19872,29 @@ FOR EACH ROW EXECUTE PROCEDURE 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 @@ -19899,7 +19902,7 @@ FOR EACH ROW EXECUTE PROCEDURE suppress_redundant_updates_trigger(); is_temporary bool - Flag indicating that the object was a temporary object. + True if this was a temporary object @@ -19928,8 +19931,8 @@ FOR EACH ROW EXECUTE PROCEDURE 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. @@ -19937,17 +19940,17 @@ FOR EACH ROW EXECUTE PROCEDURE 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