pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedDocumentation - chapter 52, system catalogs
4+ messages / 3 participants
[nested] [flat]
* Documentation - chapter 52, system catalogs
@ 2020-05-04 15:23 PG Doc comments form <noreply@postgresql.org>
2020-05-05 10:20 ` Re: Documentation - chapter 52, system catalogs Jürgen Purtz <juergen@purtz.de>
0 siblings, 1 reply; 4+ messages in thread
From: PG Doc comments form @ 2020-05-04 15:23 UTC (permalink / raw)
To: pgsql-docs@lists.postgresql.org; +Cc: daelhithe@hotmail.com
The following documentation comment has been logged on the website:
Page: https://www.postgresql.org/docs/11/catalogs-overview.html
Description:
The documentation for chapter 52 does not clearly identify the schema
associated with the system catalogs in either the chapter header or overview
sections; had I not stumbled across a reference in the documentation for the
postgres_fdw to the pg_catalog search path, I would have been unable to
reference the content in those catalogs via foreign data wrappers, and
although the majority of the content has been exposed via the
information_schema views and tables, there remain a few elements of interest
that appear to only exist in the pg_catalog qualified content.
^ permalink raw reply [nested|flat] 4+ messages in thread
* Re: Documentation - chapter 52, system catalogs
2020-05-04 15:23 Documentation - chapter 52, system catalogs PG Doc comments form <noreply@postgresql.org>
@ 2020-05-05 10:20 ` Jürgen Purtz <juergen@purtz.de>
2020-05-05 22:01 ` Re: Documentation - chapter 52, system catalogs Tom Lane <tgl@sss.pgh.pa.us>
0 siblings, 1 reply; 4+ messages in thread
From: Jürgen Purtz @ 2020-05-05 10:20 UTC (permalink / raw)
To: pgsql-docs@lists.postgresql.org; daelhithe@hotmail.com
On 04.05.20 17:23, PG Doc comments form wrote:
> The following documentation comment has been logged on the website:
>
> Page: https://www.postgresql.org/docs/11/catalogs-overview.html
> Description:
>
> The documentation for chapter 52 does not clearly identify the schema
> associated with the system catalogs in either the chapter header or overview
> sections; had I not stumbled across a reference in the documentation for the
> postgres_fdw to the pg_catalog search path, I would have been unable to
> reference the content in those catalogs via foreign data wrappers, and
> although the majority of the content has been exposed via the
> information_schema views and tables, there remain a few elements of interest
> that appear to only exist in the pg_catalog qualified content.
I think that the topic "fdw" is only a symptom, not the real reason for
the confusion. We can improve the chapters "System Catalog" and
"Information Schema" in general by centralizing some already existing
paragraphs in the "Overview" chapter and adding some more explanations.
The attached patch contains:
- for "System Catalog": moving paragraphs from bottom of 51. to top of
51.1. (in PG 11 it is chapter 52); explanation that "System Catalog" is
a synonym for a concrete schema and its tables.
- for "Information Schema": moving paragraphs from bottom of 36. to
middle of 36.1. ; an explanation that it relies on the system catalog;
change the title of 36.1. to "Overview" in correlation with "System
Catalog".
--
Jürgen Purtz
Attachments:
0001-catalog.patch (text/x-patch, 6.0K) download
diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml
index ce33df9e58..8854bda05f 100644
--- a/doc/src/sgml/catalogs.sgml
+++ b/doc/src/sgml/catalogs.sgml
@@ -6,6 +6,23 @@
<chapter id="catalogs">
<title>System Catalogs</title>
+ <sect1 id="catalogs-overview">
+ <title>Overview</title>
+
+ <para>
+ The term <firstterm>system catalog</firstterm> is a widely used
+ synonym for the schema <firstterm>pg_catalog</firstterm> and
+ its tables. They are listed in <xref linkend="catalog-table"/>
+ with links to more detailed documentation.
+ </para>
+
+ <para>
+ Most system catalogs are copied from the template database during
+ database creation and are thereafter database-specific. A few
+ catalogs are physically shared across all databases in a cluster;
+ these are noted in the descriptions of the individual catalogs.
+ </para>
+
<para>
The system catalogs are the place where a relational database
management system stores schema metadata, such as information about
@@ -23,21 +40,6 @@
of the system catalogs is ever decreasing.
</para>
- <sect1 id="catalogs-overview">
- <title>Overview</title>
-
- <para>
- <xref linkend="catalog-table"/> lists the system catalogs.
- More detailed documentation of each catalog follows below.
- </para>
-
- <para>
- Most system catalogs are copied from the template database during
- database creation and are thereafter database-specific. A few
- catalogs are physically shared across all databases in a cluster;
- these are noted in the descriptions of the individual catalogs.
- </para>
-
<table id="catalog-table">
<title>System Catalogs</title>
diff --git a/doc/src/sgml/information_schema.sgml b/doc/src/sgml/information_schema.sgml
index 7a995a1b64..ea8561d9e5 100644
--- a/doc/src/sgml/information_schema.sgml
+++ b/doc/src/sgml/information_schema.sgml
@@ -7,46 +7,8 @@
<primary>information schema</primary>
</indexterm>
- <para>
- The information schema consists of a set of views that contain
- information about the objects defined in the current database. The
- information schema is defined in the SQL standard and can therefore
- be expected to be portable and remain stable — unlike the system
- catalogs, which are specific to
- <productname>PostgreSQL</productname> and are modeled after
- implementation concerns. The information schema views do not,
- however, contain information about
- <productname>PostgreSQL</productname>-specific features; to inquire
- about those you need to query the system catalogs or other
- <productname>PostgreSQL</productname>-specific views.
- </para>
-
- <note>
- <para>
- When querying the database for constraint information, it is possible
- for a standard-compliant query that expects to return one row to
- return several. This is because the SQL standard requires constraint
- names to be unique within a schema, but
- <productname>PostgreSQL</productname> does not enforce this
- restriction. <productname>PostgreSQL</productname>
- automatically-generated constraint names avoid duplicates in the
- same schema, but users can specify such duplicate names.
- </para>
-
- <para>
- This problem can appear when querying information schema views such
- as <literal>check_constraint_routine_usage</literal>,
- <literal>check_constraints</literal>, <literal>domain_constraints</literal>, and
- <literal>referential_constraints</literal>. Some other views have similar
- issues but contain the table name to help distinguish duplicate
- rows, e.g., <literal>constraint_column_usage</literal>,
- <literal>constraint_table_usage</literal>, <literal>table_constraints</literal>.
- </para>
- </note>
-
-
<sect1 id="infoschema-schema">
- <title>The Schema</title>
+ <title>Overview</title>
<para>
The information schema itself is a schema named
@@ -57,6 +19,44 @@
the space savings achieved by that are minuscule).
</para>
+ <para>
+ The information schema consists of a set of views to tables
+ in the schema <firstterm>pg_catalog</firstterm>, so it contains
+ information about the objects defined in the current database. The
+ information schema is defined in the SQL standard and can therefore
+ be expected to be portable and remain stable — unlike the system
+ catalogs, which are specific to
+ <productname>PostgreSQL</productname> and are modeled after
+ implementation concerns. The information schema views do not,
+ however, contain information about
+ <productname>PostgreSQL</productname>-specific features; to inquire
+ about those you need to query the system catalogs or other
+ <productname>PostgreSQL</productname>-specific views.
+ </para>
+
+ <note>
+ <para>
+ When querying the database for constraint information, it is possible
+ for a standard-compliant query that expects to return one row to
+ return several. This is because the SQL standard requires constraint
+ names to be unique within a schema, but
+ <productname>PostgreSQL</productname> does not enforce this
+ restriction. <productname>PostgreSQL</productname>
+ automatically-generated constraint names avoid duplicates in the
+ same schema, but users can specify such duplicate names.
+ </para>
+
+ <para>
+ This problem can appear when querying information schema views such
+ as <literal>check_constraint_routine_usage</literal>,
+ <literal>check_constraints</literal>, <literal>domain_constraints</literal>, and
+ <literal>referential_constraints</literal>. Some other views have similar
+ issues but contain the table name to help distinguish duplicate
+ rows, e.g., <literal>constraint_column_usage</literal>,
+ <literal>constraint_table_usage</literal>, <literal>table_constraints</literal>.
+ </para>
+ </note>
+
<para>
By default, the information schema is not in the schema search
path, so you need to access all objects in it through qualified
@@ -65,6 +65,7 @@
should be careful if you want to put the information schema in the
path.
</para>
+
</sect1>
<sect1 id="infoschema-datatypes">
* Re: Documentation - chapter 52, system catalogs
2020-05-04 15:23 Documentation - chapter 52, system catalogs PG Doc comments form <noreply@postgresql.org>
2020-05-05 10:20 ` Re: Documentation - chapter 52, system catalogs Jürgen Purtz <juergen@purtz.de>
@ 2020-05-05 22:01 ` Tom Lane <tgl@sss.pgh.pa.us>
2020-05-06 07:57 ` Re: Documentation - chapter 52, system catalogs Jürgen Purtz <juergen@purtz.de>
0 siblings, 1 reply; 4+ messages in thread
From: Tom Lane @ 2020-05-05 22:01 UTC (permalink / raw)
To: Jürgen Purtz <juergen@purtz.de>; +Cc: pgsql-docs@lists.postgresql.org; daelhithe@hotmail.com
=?UTF-8?Q?J=c3=bcrgen_Purtz?= <juergen@purtz.de> writes:
> The attached patch contains:
> - for "System Catalog": moving paragraphs from bottom of 51. to top of
> 51.1. (in PG 11 it is chapter 52); explanation that "System Catalog" is
> a synonym for a concrete schema and its tables.
> - for "Information Schema": moving paragraphs from bottom of 36. to
> middle of 36.1. ; an explanation that it relies on the system catalog;
> change the title of 36.1. to "Overview" in correlation with "System
> Catalog".
I don't like this patch much; it seems to me that from a semantic
standpoint, it's making things worse not better. Text that's ahead
of the first <sect1> is more important than the text after it,
or should be.
I don't deny that we have a problem here: in the website rendering,
that text tends to be pushed down out of sight by the chapter's
sub-table-of-contents. But that issue exists for every chapter
that's got more than a couple of sections. We shouldn't hack
around it for just these two chapters. Chapter 9 and Appendix F
are additional examples where this is a fairly urgent issue.
I wonder if we should just drop the sub-table-of-contents material.
(I'm assuming DocBook can be coerced to do that; but since the PDF
output has no such material, it seems like it ought to be possible.)
Or ... is there a way to postpone it to the bottom of the page,
ie just before the first <sect1>, instead of having it in front
of the chapter preface?
The same issue exists for the sub-sub-tables-of-contents for <sect1>s,
though it's less bad because few of those have grown enormous lists
of <sect2>'s.
regards, tom lane
^ permalink raw reply [nested|flat] 4+ messages in thread
* Re: Documentation - chapter 52, system catalogs
2020-05-04 15:23 Documentation - chapter 52, system catalogs PG Doc comments form <noreply@postgresql.org>
2020-05-05 10:20 ` Re: Documentation - chapter 52, system catalogs Jürgen Purtz <juergen@purtz.de>
2020-05-05 22:01 ` Re: Documentation - chapter 52, system catalogs Tom Lane <tgl@sss.pgh.pa.us>
@ 2020-05-06 07:57 ` Jürgen Purtz <juergen@purtz.de>
0 siblings, 0 replies; 4+ messages in thread
From: Jürgen Purtz @ 2020-05-06 07:57 UTC (permalink / raw)
To: pgsql-docs@lists.postgresql.org; +Cc: daelhithe@hotmail.com
On 06.05.20 00:01, Tom Lane wrote:
> I don't deny that we have a problem here: in the website rendering,
> that text tends to be pushed down out of sight by the chapter's
> sub-table-of-contents. But that issue exists for every chapter
> that's got more than a couple of sections. We shouldn't hack
> around it for just these two chapters. Chapter 9 and Appendix F
> are additional examples where this is a fairly urgent issue.
Generic solutions are always better than individual ones.
> I wonder if we should just drop the sub-table-of-contents material.
> (I'm assuming DocBook can be coerced to do that; but since the PDF
> output has no such material, it seems like it ought to be possible.)
If we drop TOCs, we loose the automatically created links. As a
substitute we would need tables like in example 51.1. So it's again an
individual solution.
> Or ... is there a way to postpone it to the bottom of the page,
> ie just before the first <sect1>, instead of having it in front
> of the chapter preface?
>
> The same issue exists for the sub-sub-tables-of-contents for <sect1>s,
> though it's less bad because few of those have grown enormous lists
> of <sect2>'s.
Swapping TOC and content may work in such cases, but for me it seems to
be a hard work with xslt.
A real generic solution would be an adaption of the HTML output to the
PDF output: two columns with a collapsible menu containing all TOC
information in the left one ('outline' in PDF) and nothing than content
in the right one. But this is a huge change of the look-and-feel as well
as for all technical stuff: HTML, CSS, bootstrap, Javascript, Ajax(?), ... .
--
Jürgen Purtz
^ permalink raw reply [nested|flat] 4+ messages in thread
end of thread, other threads:[~2020-05-06 07:57 UTC | newest]
Thread overview: 4+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2020-05-04 15:23 Documentation - chapter 52, system catalogs PG Doc comments form <noreply@postgresql.org>
2020-05-05 10:20 ` Jürgen Purtz <juergen@purtz.de>
2020-05-05 22:01 ` Tom Lane <tgl@sss.pgh.pa.us>
2020-05-06 07:57 ` Jürgen Purtz <juergen@purtz.de>
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox