From cb6eb4a09e8adf3cc25e8eff9fdd43d8d9cd9c86 Mon Sep 17 00:00:00 2001 From: Peter Eisentraut Date: Thu, 3 Sep 2020 13:15:53 +0200 Subject: [PATCH] doc: Add missing cross-links in system catalog documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This makes the first mention of a system catalog or view in each paragraph in the system system catalog and view documentation pages hyperlinks, for easier navigation. Also linkify the first mention of pg_hba.conf in pg_hba_file_rules, as that's more specific and easier to spot than the link to the client authentication chapter. Author: Dagfinn Ilmari Mannsåker Discussion: https://www.postgresql.org/message-id/flat/87mu5xqc11.fsf@wibble.ilmari.org --- doc/src/sgml/catalogs.sgml | 122 ++++++++++++++++++++----------------- 1 file changed, 66 insertions(+), 56 deletions(-) diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml index 1d1b8ce8fb..85084a7c23 100644 --- a/doc/src/sgml/catalogs.sgml +++ b/doc/src/sgml/catalogs.sgml @@ -381,9 +381,10 @@ sum, count, and max. Each entry in pg_aggregate is an extension of an entry - in pg_proc. The pg_proc - entry carries the aggregate's name, input and output data types, and - other information that is similar to ordinary functions. + in pg_proc. + The pg_proc entry carries the aggregate's name, + input and output data types, and other information that is similar to + ordinary functions. @@ -902,7 +903,7 @@ catalog structure for performance reasons). Also, amoplefttype and amoprighttype must match the oprleft and oprright fields of the - referenced pg_operator entry. + referenced pg_operator entry. @@ -1099,7 +1100,8 @@ table columns. There will be exactly one pg_attribute row for every column in every table in the database. (There will also be attribute entries for - indexes, and indeed all objects that have pg_class + indexes, and indeed all objects that have + pg_class entries.) @@ -1270,7 +1272,7 @@ This column has a default expression or generation expression, in which case there will be a corresponding entry in the - pg_attrdef catalog that actually defines the + pg_attrdef catalog that actually defines the expression. (Check attgenerated to determine whether this is a default or a generation expression.) @@ -1402,7 +1404,7 @@ In a dropped column's pg_attribute entry, atttypid is reset to zero, but attlen and the other fields copied from - pg_type are still valid. This arrangement is needed + pg_type are still valid. This arrangement is needed to cope with the situation where the dropped column's data type was later dropped, and so there is no pg_type row anymore. attlen and the other fields can be used @@ -1836,13 +1838,15 @@ SCRAM-SHA-256$<iteration count>:&l The catalog pg_class catalogs tables and most everything else that has columns or is otherwise similar to a - table. This includes indexes (but see also - pg_index), sequences (but see also - pg_sequence), views, materialized - views, composite types, and TOAST tables; see relkind. - Below, when we mean all of these - kinds of objects we speak of relations. Not all - columns are meaningful for all relation types. + table. This includes indexes (but see also pg_index), + sequences (but see also pg_sequence), + views, materialized views, composite types, and TOAST tables; + see relkind. + Below, when we mean all of these kinds of objects we speak of + relations. Not all columns are meaningful for all relation + types.
@@ -2024,7 +2028,7 @@ SCRAM-SHA-256$<iteration count>:&l True if this table is shared across all databases in the cluster. Only - certain system catalogs (such as pg_database) + certain system catalogs (such as pg_database) are shared. @@ -2064,8 +2068,8 @@ SCRAM-SHA-256$<iteration count>:&l Number of user columns in the relation (system columns not counted). There must be this many corresponding entries in - pg_attribute. See also - pg_attribute.attnum. + pg_attribute. See also + pg_attribute.attnum. @@ -2409,7 +2413,8 @@ SCRAM-SHA-256$<iteration count>:&l key, unique, foreign key, and exclusion constraints on tables. (Column constraints are not treated specially. Every column constraint is equivalent to some table constraint.) - Not-null constraints are represented in the pg_attribute + Not-null constraints are represented in the + pg_attribute catalog, not here. @@ -2712,7 +2717,7 @@ SCRAM-SHA-256$<iteration count>:&l For other cases, a zero appears in conkey and the associated index must be consulted to discover the expression that is constrained. (conkey thus has the - same contents as pg_index.indkey for the + same contents as pg_index.indkey for the index.) @@ -2980,7 +2985,7 @@ SCRAM-SHA-256$<iteration count>:&l track whether the database needs to be vacuumed in order to prevent transaction ID wraparound or to allow pg_xact to be shrunk. It is the minimum of the per-table - pg_class.relfrozenxid values. + pg_class.relfrozenxid values. @@ -2994,7 +2999,7 @@ SCRAM-SHA-256$<iteration count>:&l track whether the database needs to be vacuumed in order to prevent multixact ID wraparound or to allow pg_multixact to be shrunk. It is the minimum of the per-table - pg_class.relminmxid values. + pg_class.relminmxid values. @@ -3006,7 +3011,7 @@ SCRAM-SHA-256$<iteration count>:&l The default tablespace for the database. Within this database, all tables for which - pg_class.reltablespace is zero + pg_class.reltablespace is zero will be stored in this tablespace; in particular, all the non-shared system catalogs will be there. @@ -3605,7 +3610,7 @@ SCRAM-SHA-256$<iteration count>:&l (references pg_type.oid) - The OID of the pg_type entry owning this enum value + The OID of the pg_type entry owning this enum value @@ -4100,8 +4105,9 @@ SCRAM-SHA-256$<iteration count>:&l The catalog pg_foreign_table contains auxiliary information about foreign tables. A foreign table is - primarily represented by a pg_class entry, - just like a regular table. Its pg_foreign_table + primarily represented by a + pg_class + entry, just like a regular table. Its pg_foreign_table entry contains the information that is pertinent only to foreign tables and not any other kind of relation. @@ -4127,7 +4133,7 @@ SCRAM-SHA-256$<iteration count>:&l (references pg_class.oid) - OID of the pg_class entry for this foreign table + The OID of the pg_class entry for this foreign table @@ -4165,7 +4171,7 @@ SCRAM-SHA-256$<iteration count>:&l The catalog pg_index contains part of the information about indexes. The rest is mostly in - pg_class. + pg_class.
@@ -4189,7 +4195,7 @@ SCRAM-SHA-256$<iteration count>:&l (references pg_class.oid) - The OID of the pg_class entry for this index + The OID of the pg_class entry for this index @@ -4199,7 +4205,7 @@ SCRAM-SHA-256$<iteration count>:&l (references pg_class.oid) - The OID of the pg_class entry for the table this index is for + The OID of the pg_class entry for the table this index is for @@ -5400,7 +5406,7 @@ SCRAM-SHA-256$<iteration count>:&l (references pg_class.oid) - The OID of the pg_class entry for this partitioned table + The OID of the pg_class entry for this partitioned table @@ -5429,7 +5435,7 @@ SCRAM-SHA-256$<iteration count>:&l (references pg_class.oid) - The OID of the pg_class entry for the default partition + 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. @@ -5609,7 +5615,7 @@ SCRAM-SHA-256$<iteration count>:&l Policies stored in pg_policy are applied only when - pg_class.relrowsecurity is set for + pg_class.relrowsecurity is set for their table. @@ -5634,7 +5640,7 @@ SCRAM-SHA-256$<iteration count>:&l If prokind indicates that the entry is for an aggregate function, there should be a matching row in - pg_aggregate. + pg_aggregate.
@@ -6564,7 +6570,8 @@ SCRAM-SHA-256$<iteration count>:&l The catalog pg_sequence contains information about sequences. Some of the information about sequences, such as the name and - the schema, is in pg_class. + the schema, is in + pg_class
@@ -6588,7 +6595,7 @@ SCRAM-SHA-256$<iteration count>:&l (references pg_class.oid) - The OID of the pg_class entry for this sequence + The OID of the pg_class entry for this sequence @@ -7347,13 +7354,14 @@ SCRAM-SHA-256$<iteration count>:&l The catalog pg_statistic_ext_data - holds data for extended planner statistics defined in pg_statistic_ext. + holds data for extended planner statistics defined in + pg_statistic_ext. Each row in this catalog corresponds to a statistics object created with . - Like pg_statistic, + Like pg_statistic, pg_statistic_ext_data should not be readable by the public, since the contents might be considered sensitive. (Example: most common combinations of values in columns might be quite @@ -7361,7 +7369,7 @@ SCRAM-SHA-256$<iteration count>:&l pg_stats_ext is a publicly readable view on pg_statistic_ext_data (after joining - with pg_statistic_ext) that only exposes + with pg_statistic_ext) that only exposes information about those tables and columns that are readable by the current user. @@ -7960,7 +7968,7 @@ 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, if any @@ -8058,7 +8066,7 @@ SCRAM-SHA-256$<iteration count>:&l When tgconstraint is nonzero, tgconstrrelid, tgconstrindid, tgdeferrable, and tginitdeferred are - largely redundant with the referenced pg_constraint entry. + largely redundant with the referenced pg_constraint entry. However, it is possible for a non-deferrable trigger to be associated with a deferrable constraint: foreign key constraints can have some deferrable and some non-deferrable triggers. @@ -8205,7 +8213,7 @@ SCRAM-SHA-256$<iteration count>:&l (references pg_ts_config.oid) - The OID of the pg_ts_config entry owning this map entry + The OID of the pg_ts_config entry owning this map entry @@ -8719,11 +8727,11 @@ SCRAM-SHA-256$<iteration count>:&l If this is a composite type (see typtype), then this column points to - the pg_class entry that defines the + the pg_class entry that defines the corresponding table. (For a free-standing composite type, the - pg_class entry doesn't really represent + pg_class entry doesn't really represent a table, but it is needed anyway for the type's - pg_attribute entries to link to.) + pg_attribute entries to link to.) Zero for non-composite types. @@ -10112,8 +10120,9 @@ SCRAM-SHA-256$<iteration count>:&l The view pg_hba_file_rules provides a summary of - the contents of the client authentication configuration - file, pg_hba.conf. A row appears in this view for each + the contents of the client authentication configuration file, + pg_hba.conf. + A row appears in this view for each non-empty, non-comment line in the file, with annotations indicating whether the rule could be applied successfully. @@ -10354,8 +10363,8 @@ SCRAM-SHA-256$<iteration count>:&l individual tuples of relations, transaction IDs (both virtual and permanent IDs), and general database objects (identified by class OID and object OID, - in the same way as in pg_description or - pg_depend). Also, the right to extend a + in the same way as in pg_description or + pg_depend). Also, the right to extend a relation is represented as a separate lockable object, as is the right to update pg_database.datfrozenxid. Also, advisory locks can be taken on numbers that have @@ -10597,7 +10606,7 @@ SCRAM-SHA-256$<iteration count>:&l pg_locks provides a global view of all locks in the database cluster, not only those relevant to the current database. Although its relation column can be joined - against pg_class.oid to identify locked + against pg_class.oid to identify locked relations, this will only work correctly for relations in the current database (those for which the database column is either the current database's OID or zero). @@ -11112,8 +11121,9 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx The view pg_publication_tables provides information about the mapping between publications and the tables they - contain. Unlike the underlying - catalog pg_publication_rel, this view expands + contain. Unlike the underlying catalog + pg_publication_rel, + this view expands publications defined as FOR ALL TABLES, so for such publications there will be a row for each eligible table. @@ -11688,7 +11698,7 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx The pg_rules view excludes the ON SELECT rules of views and materialized views; those can be seen in - pg_views and pg_matviews. + pg_views and pg_matviews. @@ -12517,7 +12527,7 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx the information stored in the pg_statistic catalog. This view allows access only to rows of - pg_statistic that correspond to tables the + pg_statistic that correspond to tables the user has permission to read, and therefore it is safe to allow public read access to this view. @@ -12526,7 +12536,7 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx pg_stats is also designed to present the information in a more readable format than the underlying catalog — at the cost that its schema must be extended whenever new slot types - are defined for pg_statistic. + are defined for pg_statistic.
@@ -12728,7 +12738,7 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx linkend="catalog-pg-statistic-ext">pg_statistic_ext and pg_statistic_ext_data catalogs. This view allows access only to rows of - pg_statistic_ext and pg_statistic_ext_data + pg_statistic_ext and pg_statistic_ext_data that correspond to tables the user has permission to read, and therefore it is safe to allow public read access to this view. @@ -12737,7 +12747,7 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx pg_stats_ext is also designed to present the information in a more readable format than the underlying catalogs — at the cost that its schema must be extended whenever new types - of extended statistics are added to pg_statistic_ext. + of extended statistics are added to pg_statistic_ext.