Обсуждение: create table explicitly mention that unique|primary key constraint will create an
Hi. minor doc issue. create table s1(a int, constraint s2 PRIMARY key (a)); create table s2(a int); ERROR: relation "s2" already exists https://www.postgresql.org/docs/current/sql-createtable.html#SQL-CREATETABLE-PARMS-UNIQUE maybe for the following 2 sentence "Adding a unique constraint will automatically create a unique btree index on the column or group of columns used in the constraint." "Adding a PRIMARY KEY constraint will automatically create a unique btree index on the column or group of columns used in the constraint." maybe we can mention that: the unique btree index name will be the constraint name. also is "a unique" or "an unique"? I personally thought this part is obscure.
Re: create table explicitly mention that unique|primary key constraint will create an
От
Laurenz Albe
Дата:
On Mon, 2023-11-27 at 08:00 +0800, jian he wrote: > Hi. minor doc issue. > create table s1(a int, constraint s2 PRIMARY key (a)); > create table s2(a int); > ERROR: relation "s2" already exists > > https://www.postgresql.org/docs/current/sql-createtable.html#SQL-CREATETABLE-PARMS-UNIQUE > maybe for the following 2 sentence > "Adding a unique constraint will automatically create a unique btree > index on the column or group of columns used in the constraint." > "Adding a PRIMARY KEY constraint will automatically create a unique > btree index on the column or group of columns used in the constraint." > > maybe we can mention that: the unique btree index name will be the > constraint name. > also is "a unique" or "an unique"? It would be "a unique", because "unique" is pronounced "juneek", which does not start with a vowel. > I personally thought this part is obscure. 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. What do you think of the attached patch? Yours, Laurenz Albe
Вложения
On Mon, Nov 27, 2023 at 10:30 AM Laurenz Albe <laurenz.albe@cybertec.at> wrote: > > What do you think of the attached patch? > > Yours, > Laurenz Albe looks good to me.
Re: create table explicitly mention that unique|primary key constraint will create an
От
Peter Eisentraut
Дата:
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.
Re: create table explicitly mention that unique|primary key constraint will create an
От
"David G. Johnston"
Дата:
On Thu, Jan 18, 2024 at 7:54 AM Peter Eisentraut <peter@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.
Вложения
Re: create table explicitly mention that unique|primary key constraint will create an
От
Laurenz Albe
Дата:
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
Вложения
On Fri, 19 Jan 2024 at 16:16, Laurenz Albe <laurenz.albe@cybertec.at> wrote: > > 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. CFBot shows that the patch does not apply anymore as in [1]: === Applying patches on top of PostgreSQL commit ID d282e88e50521a457fa1b36e55f43bac02a3167f === === applying patch ./v3-0001-Doc-All-relations-share-a-namespace.patch ... patching file doc/src/sgml/ref/create_table.sgml Hunk #1 FAILED at 1001. Hunk #2 FAILED at 1054. Hunk #3 succeeded at 1118 (offset 27 lines). 2 out of 3 hunks FAILED -- saving rejects to file doc/src/sgml/ref/create_table.sgml.rej Please post an updated version for the same. [1] - http://cfbot.cputube.org/patch_46_4747.log Regards, Vignesh
Re: create table explicitly mention that unique|primary key constraint will create an
От
"David G. Johnston"
Дата:
On Fri, Jan 19, 2024 at 3:46 AM Laurenz Albe <laurenz.albe@cybertec.at> wrote:
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.
Tweaking the main paragraph a little.
We use examples elsewhere, it seems one for this makes the point very clear with less description.
I removed it altogether but namespace is a word unto itself, not "name space".
diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml
index e103eddd40..25db985a56 100644
--- a/doc/src/sgml/ddl.sgml
+++ b/doc/src/sgml/ddl.sgml
@@ -3025,10 +3025,11 @@ SELECT * FROM information WHERE group_id = 2 FOR UPDATE;
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. 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
+ two objects of the same type cannot have the same name. The object type
+ of <literal>relations</literal> encompasses all of the following:
+ tables, sequences, indexes, views, materialized views, and foreign tables.
+ Thus, for example, an index and a table must have different names if they
+ are in the same 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,
index e103eddd40..25db985a56 100644
--- a/doc/src/sgml/ddl.sgml
+++ b/doc/src/sgml/ddl.sgml
@@ -3025,10 +3025,11 @@ SELECT * FROM information WHERE group_id = 2 FOR UPDATE;
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. 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
+ two objects of the same type cannot have the same name. The object type
+ of <literal>relations</literal> encompasses all of the following:
+ tables, sequences, indexes, views, materialized views, and foreign tables.
+ Thus, for example, an index and a table must have different names if they
+ are in the same 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,
David J.
Re: create table explicitly mention that unique|primary key constraint will create an
От
Laurenz Albe
Дата:
On Fri, 2024-01-26 at 19:01 +0530, vignesh C wrote: > CFBot shows that the patch does not apply anymore as in [1]: There was a conflict with 46a0cd4cefb. Updated version attached. Yours, Laurenz Albe
Вложения
Re: create table explicitly mention that unique|primary key constraint will create an
От
Peter Eisentraut
Дата:
On 26.01.24 16:52, Laurenz Albe wrote: > On Fri, 2024-01-26 at 19:01 +0530, vignesh C wrote: >> CFBot shows that the patch does not apply anymore as in [1]: > > There was a conflict with 46a0cd4cefb. > Updated version attached. Sprinkled in some of David's suggestions, and pushed. I was hesitant to burden the user with the difference between "relation" and "table" at this point, so I took the former term out of the text.
Re: create table explicitly mention that unique|primary key constraint will create an
От
Peter Eisentraut
Дата:
On 18.01.24 22:21, David G. Johnston wrote: > 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. I think this proposal goes a bit too far into implementation-dependent details. The namespace of tables and indexes is clearly important, but for example, the subdivision of types into range types and multi-range types is really low-level and not usually practically relevant. And you don't mention array types, probably because they are not mentioned in typtype, but they are also relevant for the namespace of types. There are multiple ways to slice all this, but it's not clear why we need to lay this all out in the introductory documentation.
Re: create table explicitly mention that unique|primary key constraint will create an
От
Laurenz Albe
Дата:
On Wed, 2024-01-31 at 12:11 +0100, Peter Eisentraut wrote: > Sprinkled in some of David's suggestions, and pushed. Thanks; your text is great. Yours, Laurenz Albe