From 479331406e8403cc2e75d1082f8c613e7669c113 Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Tue, 2 Feb 2021 16:15:29 -0500 Subject: [PATCH] Doc: consistently identify OID catalog columns that can be zero. Not all OID-reference columns that can contain zeroes (indicating "no reference") were explicitly marked in catalogs.sgml. Fix that, and try to make the style a little more consistent while at it --- for example, consistently write "zero" not "0" for these cases. Joel Jacobson and Tom Lane Discussion: https://postgr.es/m/4ed9a372-7bf9-479a-926c-ae8e774717a8@www.fastmail.com --- doc/src/sgml/catalogs.sgml | 128 ++++++++++++++++++++----------------- 1 file changed, 70 insertions(+), 58 deletions(-) diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml index 865e826fb0..ea222c0464 100644 --- a/doc/src/sgml/catalogs.sgml +++ b/doc/src/sgml/catalogs.sgml @@ -1150,7 +1150,7 @@ (references pg_type.oid) - The data type of this column + The data type of this column (zero for a dropped column) @@ -1351,7 +1351,7 @@ The defined collation of the column, or zero if the column is - not of a collatable data type. + not of a collatable data type @@ -1899,8 +1899,8 @@ SCRAM-SHA-256$<iteration count>:&l The OID of the data type that corresponds to this table's row type, - if any (zero for indexes, sequences, and toast tables, which have - no pg_type entry) + if any; zero for indexes, sequences, and toast tables, which have + no pg_type entry @@ -1910,7 +1910,7 @@ SCRAM-SHA-256$<iteration count>:&l (references pg_type.oid) - For typed tables, the OID of the underlying composite type, + For typed tables, the OID of the underlying composite type; zero for all other relations @@ -1932,7 +1932,8 @@ SCRAM-SHA-256$<iteration count>:&l If this is a table or an index, the access method used (heap, - B-tree, hash, etc.) + B-tree, hash, etc.); otherwise zero (zero occurs for sequences, + as well as relations without storage, such as views) @@ -2007,7 +2008,7 @@ SCRAM-SHA-256$<iteration count>:&l (references pg_class.oid) - OID of the TOAST table associated with this table, 0 if none. The + OID of the TOAST table associated with this table, zero if none. The TOAST table stores large attributes out of line in a secondary table. @@ -2174,8 +2175,8 @@ SCRAM-SHA-256$<iteration count>:&l For new relations being written during a DDL operation that requires a table rewrite, this contains the OID of the original relation; - otherwise 0. That state is only visible internally; this field should - never contain anything other than 0 for a user-visible relation. + otherwise zero. That state is only visible internally; this field should + never contain anything other than zero for a user-visible relation. @@ -2507,7 +2508,7 @@ SCRAM-SHA-256$<iteration count>:&l (references pg_class.oid) - The table this constraint is on; 0 if not a table constraint + The table this constraint is on; zero if not a table constraint @@ -2517,7 +2518,7 @@ SCRAM-SHA-256$<iteration count>:&l (references pg_type.oid) - The domain this constraint is on; 0 if not a domain constraint + The domain this constraint is on; zero if not a domain constraint @@ -2528,7 +2529,7 @@ SCRAM-SHA-256$<iteration count>:&l The index supporting this constraint, if it's a unique, primary - key, foreign key, or exclusion constraint; else 0 + key, foreign key, or exclusion constraint; else zero @@ -2538,8 +2539,8 @@ SCRAM-SHA-256$<iteration count>:&l (references pg_constraint.oid) - The corresponding constraint in the parent partitioned table, - if this is a constraint in a partition; else 0 + The corresponding constraint of the parent partitioned table, + if this is a constraint on a partition; else zero @@ -2549,7 +2550,7 @@ SCRAM-SHA-256$<iteration count>:&l (references pg_class.oid) - If a foreign key, the referenced table; else 0 + If a foreign key, the referenced table; else zero @@ -3142,7 +3143,7 @@ SCRAM-SHA-256$<iteration count>:&l The OID of the namespace associated with this entry, - or 0 if none + or zero if none @@ -3176,7 +3177,7 @@ SCRAM-SHA-256$<iteration count>:&l A pg_default_acl entry shows the initial privileges to be assigned to an object belonging to the indicated user. There are currently two types of entry: global entries with - defaclnamespace = 0, and per-schema entries + defaclnamespace = zero, and per-schema entries that reference a particular schema. If a global entry is present then it overrides the normal hard-wired default privileges for the object type. A per-schema entry, if present, represents privileges @@ -3236,7 +3237,8 @@ SCRAM-SHA-256$<iteration count>:&l (references pg_class.oid) - The OID of the system catalog the dependent object is in + The OID of the system catalog the dependent object is in, + or zero for a DEPENDENCY_PIN entry @@ -3246,7 +3248,8 @@ SCRAM-SHA-256$<iteration count>:&l (references any OID column) - The OID of the specific dependent object + The OID of the specific dependent object, + or zero for a DEPENDENCY_PIN entry @@ -4687,7 +4690,7 @@ SCRAM-SHA-256$<iteration count>:&l For noninternal languages this references the language handler, which is a special function that is responsible for executing all functions that are written in the particular - language + language. Zero for internal languages. @@ -5189,7 +5192,7 @@ SCRAM-SHA-256$<iteration count>:&l (references pg_type.oid) - Type of the left operand (0 if none) + Type of the left operand (zero for a prefix operator) @@ -5210,6 +5213,7 @@ SCRAM-SHA-256$<iteration count>:&l Type of the result + (zero for a not-yet-defined shell operator) @@ -5219,7 +5223,7 @@ SCRAM-SHA-256$<iteration count>:&l (references pg_operator.oid) - Commutator of this operator, if any + Commutator of this operator (zero if none) @@ -5229,7 +5233,7 @@ SCRAM-SHA-256$<iteration count>:&l (references pg_operator.oid) - Negator of this operator, if any + Negator of this operator (zero if none) @@ -5240,6 +5244,7 @@ SCRAM-SHA-256$<iteration count>:&l Function that implements this operator + (zero for a not-yet-defined shell operator) @@ -5250,6 +5255,7 @@ SCRAM-SHA-256$<iteration count>:&l Restriction selectivity estimation function for this operator + (zero if none) @@ -5260,17 +5266,13 @@ SCRAM-SHA-256$<iteration count>:&l Join selectivity estimation function for this operator + (zero if none) - - Unused columns contain zeroes. For example, oprleft - is zero for a prefix operator. - - @@ -5426,7 +5428,7 @@ SCRAM-SHA-256$<iteration count>:&l partnatts int2 - The number of columns in partition key + The number of columns in the partition key @@ -5438,7 +5440,7 @@ SCRAM-SHA-256$<iteration count>:&l The OID of the pg_class entry for the default partition of this partitioned table, or zero if this partitioned table does not - have a default partition. + have a default partition @@ -5588,7 +5590,9 @@ SCRAM-SHA-256$<iteration count>:&l (references pg_authid.oid) - The roles to which the policy is applied + The roles to which the policy is applied; + zero means PUBLIC + (and normally appears alone in the array) @@ -5744,8 +5748,8 @@ SCRAM-SHA-256$<iteration count>:&l (references pg_proc.oid) - Optional planner support function for this function - (see ) + Planner support function for this function + (see ), or zero if none @@ -6256,7 +6260,7 @@ SCRAM-SHA-256$<iteration count>:&l (references pg_collation.oid) - OID of the collation used for range comparisons, or 0 if none + OID of the collation used for range comparisons, or zero if none @@ -6277,7 +6281,7 @@ SCRAM-SHA-256$<iteration count>:&l OID of the function to convert a range value into canonical form, - or 0 if none + or zero if none @@ -6288,7 +6292,7 @@ SCRAM-SHA-256$<iteration count>:&l OID of the function to return the difference between two element - values as double precision, or 0 if none + values as double precision, or zero if none @@ -6733,6 +6737,7 @@ SCRAM-SHA-256$<iteration count>:&l The OID of the database the dependent object is in, or zero for a shared object + or a SHARED_DEPENDENCY_PIN entry @@ -6742,7 +6747,8 @@ SCRAM-SHA-256$<iteration count>:&l (references pg_class.oid) - The OID of the system catalog the dependent object is in + The OID of the system catalog the dependent object is in, + or zero for a SHARED_DEPENDENCY_PIN entry @@ -6752,7 +6758,8 @@ SCRAM-SHA-256$<iteration count>:&l (references any OID column) - The OID of the specific dependent object + The OID of the specific dependent object, + or zero for a SHARED_DEPENDENCY_PIN entry @@ -7192,6 +7199,7 @@ SCRAM-SHA-256$<iteration count>:&l Nth slot. For example, a histogram slot would show the < operator that defines the sort order of the data. + Zero if the statistics kind does not require an operator. @@ -7836,7 +7844,7 @@ SCRAM-SHA-256$<iteration count>:&l The OID of the function to use when converting the data type for input to the procedural language (e.g., function parameters). Zero is stored - if this operation is not supported. + if the default behavior should be used. @@ -7848,7 +7856,7 @@ SCRAM-SHA-256$<iteration count>:&l The OID of the function to use when converting output from the procedural language (e.g., return values) to the data type. Zero is - stored if this operation is not supported. + stored if the default behavior should be used. @@ -7911,9 +7919,9 @@ SCRAM-SHA-256$<iteration count>:&l (references pg_trigger.oid) - Parent trigger that this trigger is cloned from, zero if not a clone; - this happens when partitions are created or attached to a partitioned - table. + Parent trigger that this trigger is cloned from (this happens when + partitions are created or attached to a partitioned table); + zero if not a clone @@ -7976,6 +7984,7 @@ SCRAM-SHA-256$<iteration count>:&l The table referenced by a referential integrity constraint + (zero if trigger is not for a referential integrity constraint) @@ -7987,6 +7996,7 @@ SCRAM-SHA-256$<iteration count>:&l The index supporting a unique, primary key, referential integrity, or exclusion constraint + (zero if trigger is not for one of these types of constraint) @@ -7996,7 +8006,8 @@ SCRAM-SHA-256$<iteration count>:&l (references pg_constraint.oid) - The pg_constraint entry associated with the trigger, if any + The pg_constraint entry associated with the trigger + (zero if trigger is not for a constraint) @@ -8478,7 +8489,7 @@ SCRAM-SHA-256$<iteration count>:&l (references pg_proc.oid) - OID of the parser's headline function + OID of the parser's headline function (zero if none) @@ -8566,7 +8577,7 @@ SCRAM-SHA-256$<iteration count>:&l (references pg_proc.oid) - OID of the template's initialization function + OID of the template's initialization function (zero if none) @@ -8786,11 +8797,11 @@ SCRAM-SHA-256$<iteration count>:&l (references pg_type.oid) - If typelem is not 0 then it + If typelem is not zero then it identifies another row in pg_type, - defining the type yielded by subscripting. This should be 0 - if typsubscript is 0. However, it can - be 0 when typsubscript isn't 0, if the + defining the type yielded by subscripting. This should be zero + if typsubscript is zero. However, it can + be zero when typsubscript isn't zero, if the handler doesn't need typelem to determine the subscripting result type. Note that a typelem dependency is @@ -8806,7 +8817,7 @@ SCRAM-SHA-256$<iteration count>:&l (references pg_type.oid) - If typarray is not 0 then it + If typarray is not zero then it identifies another row in pg_type, which is the true array type having this type as element @@ -8838,7 +8849,7 @@ SCRAM-SHA-256$<iteration count>:&l (references pg_proc.oid) - Input conversion function (binary format), or 0 if none + Input conversion function (binary format), or zero if none @@ -8848,7 +8859,7 @@ SCRAM-SHA-256$<iteration count>:&l (references pg_proc.oid) - Output conversion function (binary format), or 0 if none + Output conversion function (binary format), or zero if none @@ -8858,7 +8869,7 @@ SCRAM-SHA-256$<iteration count>:&l (references pg_proc.oid) - Type modifier input function, or 0 if type does not support modifiers + Type modifier input function, or zero if type does not support modifiers @@ -8868,7 +8879,7 @@ SCRAM-SHA-256$<iteration count>:&l (references pg_proc.oid) - Type modifier output function, or 0 to use the standard format + Type modifier output function, or zero to use the standard format @@ -8878,7 +8889,8 @@ SCRAM-SHA-256$<iteration count>:&l (references pg_proc.oid) - Custom function, or 0 to use the standard function + Custom function, + or zero to use the standard function @@ -9198,7 +9210,7 @@ SCRAM-SHA-256$<iteration count>:&l (references pg_authid.oid) - OID of the local role being mapped, 0 if the user mapping is public + OID of the local role being mapped, or zero if the user mapping is public @@ -13403,7 +13415,7 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx (references pg_authid.oid) - OID of the local role being mapped, 0 if the user mapping is public + OID of the local role being mapped, or zero if the user mapping is public