On Thu, Jan 18, 2024 at 7:54 AM Peter Eisentraut <pe...@eisentraut.org>
wrote:
>
> I find the specific change
> proposal for ddl.sgml a bit weird, though, because this is a very
> introductory section, and you are referring people to pg_class (what is
> that?!?) for details. If we want to put something there, it should
> respect the order in which that chapter introduces concepts.
>
>
I started looking at this specific item and immediately got the idea to
actually document in user-facing (i.e., not system catalogs) what these
object categories are in which object types share the schema namespace.
The "Other Object Types" section already in the DDL chapter seems to
provide a near-perfect place to put this (not sure I like the word "other"
there being my only complaint). The attached patch replaces Laurenz's v1,
leaving the create_table changes as-is but presenting an alternative
approach to introducing namespacing when we explain why schemas exist.
David J.
From 4ba026d1a42e074df103a769e0f6b71629631c87 Mon Sep 17 00:00:00 2001
From: "David G. Johnston" <david.g.johns...@gmail.com>
Date: Thu, 18 Jan 2024 14:15:33 -0700
Subject: [PATCH] Doc-objects-in-pg_class-share-a-namespace
---
doc/src/sgml/ddl.sgml | 168 +++++++++++++++++++++++++++--
doc/src/sgml/ref/create_table.sgml | 9 +-
2 files changed, 163 insertions(+), 14 deletions(-)
diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml
index fc03a349f0..86f793f724 100644
--- a/doc/src/sgml/ddl.sgml
+++ b/doc/src/sgml/ddl.sgml
@@ -3002,11 +3002,18 @@ SELECT * FROM information WHERE group_id = 2 FOR UPDATE;
<para>
A database contains one or more named <firstterm>schemas</firstterm>, which
- in turn contain tables. Schemas also contain other kinds of named
- objects, including data types, functions, and operators. The same
- object name can be used in different schemas without conflict; for
- example, both <literal>schema1</literal> and <literal>myschema</literal> can
- contain tables named <literal>mytable</literal>. Unlike databases,
+ in turn contain all other database-specific objects (most importantly, tables).
+ The schema name, combined with an object's type category (i.e., tables are relationas),
+ forms a namespace in which any given object's name exists.
+ When writing an object's name the object type category component is inferred from
+ context. The schema name component can be explicitly prepended to the name separated
+ by a period (e.g., schema.object_name). If the schema name is not specified, the system
+ will search for the name in the schemas named in the search_path setting.
+ See ... for a listing of object types grouped by category.
+ </para>
+
+ <para>
+ Unlike databases,
schemas are not rigidly separated: a user can access objects in any
of the schemas in the database they are connected to, if they have
privileges to do so.
@@ -5274,31 +5281,172 @@ EXPLAIN SELECT count(*) FROM measurement WHERE logdate >= DATE '2008-01-01';
that exist in a database. Many other kinds of objects can be
created to make the use and management of the data more efficient
or convenient. They are not discussed in this chapter, but we give
- you a list here so that you are aware of what is possible:
+ you a partial list here so that you are aware of what is possible.
+ The first tier of labels are the object type categories that combine
+ with the schema name to form a namespace. If multiple specific
+ object types share the same category they will be listed in the
+ second tier of labels.
</para>
<itemizedlist>
<listitem>
<para>
- Views
+ Relations
+ </para>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Tables
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Indexes
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Views
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Materialized Views
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Foreign Tables
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Composite Types
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Sequences
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Partitioned Tables
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Partitioned Indexes
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Routines
+ </para>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Functions
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Aggregate Functions
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Window Functions
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Procedures
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Data Types
+ </para>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Base Types
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Composite Types
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Range Types
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Multi-Range Types
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Domains
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Enums
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Operators
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Triggers
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Row-Level Security (RLS) Policies
</para>
</listitem>
<listitem>
<para>
- Functions, procedures, and operators
+ Text Search Dictionaries
</para>
</listitem>
<listitem>
<para>
- Data types and domains
+ Publications (for replication)
</para>
</listitem>
<listitem>
<para>
- Triggers and rewrite rules
+ Subscriptions (for replication)
</para>
</listitem>
</itemizedlist>
diff --git a/doc/src/sgml/ref/create_table.sgml b/doc/src/sgml/ref/create_table.sgml
index e04a0692c4..e334b17672 100644
--- a/doc/src/sgml/ref/create_table.sgml
+++ b/doc/src/sgml/ref/create_table.sgml
@@ -1001,7 +1001,8 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
<para>
Adding a unique constraint will automatically create a unique btree
- index on the column or group of columns used in the constraint.
+ index on the column or group of columns used in the constraint. That
+ index has the same name as the unique constraint.
</para>
<para>
@@ -1054,7 +1055,7 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
<para>
Adding a <literal>PRIMARY KEY</literal> constraint will automatically
create a unique btree index on the column or group of columns used in the
- constraint.
+ constraint. That index has the same name as the primary key constraint.
</para>
<para>
@@ -1091,8 +1092,8 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
<para>
Exclusion constraints are implemented using
- an index, so each specified operator must be associated with an
- appropriate operator class
+ an index that has the same name as the constraint, so each specified
+ operator must be associated with an appropriate operator class
(see <xref linkend="indexes-opclass"/>) for the index access
method <replaceable>index_method</replaceable>.
The operators are required to be commutative.
--
2.34.1
