On Thu, 2024-01-18 at 15:54 +0100, Peter Eisentraut wrote: > On 27.11.23 03:30, Laurenz Albe wrote: > > True; I don't find it documented that all objects in pg_class share a > > namespace and that constraints are implemented by indexes of the same > > name. But I think that the first part is a property of schemas and had > > better be documented there. > > It is documented prominently on the CREATE INDEX reference page. We > could document it in more places, of course. 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. > > The changes on create_table.sgml seem ok. Although I had actually > expected that the system applies the find-a-unique-name routine rather > than taking the constraint name for the index name unaltered. > > Perhaps taking the create_table.sgml changes and combination with the > existing text on CREATE INDEX is sufficient.
Ah, I didn't see the CREATE INDEX page. (As an aside: too much conceptual stuff is documented in our reference pages, but that's a different issue.) For me, the intuitive place to look for information like that is the "Data Definition" chapter, so I think we should mention it there. I agree that "pg_class" is too advanced for that chapter, even though there is an earlier reference to it under "System Columns". In the attached patch, I have copied the enumeration of relations from the CREATE INDEX page. I think this small redundance is alright, but I wouldn't mind if this gets removed from CREATE INDEX. The rest is unmodified. Yours, Laurenz Albe
From b85ccf59ad0575e5040b17bbed5d2e152217df47 Mon Sep 17 00:00:00 2001 From: Laurenz Albe <laurenz.a...@cybertec.at> Date: Fri, 19 Jan 2024 11:37:32 +0100 Subject: [PATCH v3] Doc: All relations share a namespace This was already documented in the CREATE INDEX reference, but not in the introductory "Data Definition" chapter. Also, document that the index that implements a constraint has the same name as the constraint. Author: Laurenz Albe Reviewed-by: Jian He, Peter Eisentraut, David G. Johnston Discussion: https://postgr.es/m/CACJufxFG682tYcP9aH_F-jrqq5End8MHZR77zcp1%3DDUrEsSu1Q%40mail.gmail.com --- doc/src/sgml/ddl.sgml | 6 +++++- doc/src/sgml/ref/create_table.sgml | 9 +++++---- 2 files changed, 10 insertions(+), 5 deletions(-) diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml index 4044f0908f..13831667fe 100644 --- a/doc/src/sgml/ddl.sgml +++ b/doc/src/sgml/ddl.sgml @@ -3001,7 +3001,11 @@ 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 + objects, including data types, functions, and operators. Within one schema, + two objects of the same type cannot have the same name. All relations + (tables, sequences, indexes, views, materialized views, and foreign tables) + share one name space, so they need to have different names if they are in + a single schema. 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, 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.43.0
