pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedcreate table explicitly mention that unique|primary key constraint will create an
12+ messages / 5 participants
[nested] [flat]
* create table explicitly mention that unique|primary key constraint will create an
@ 2023-11-27 00:00 jian he <jian.universality@gmail.com>
0 siblings, 1 reply; 12+ messages in thread
From: jian he @ 2023-11-27 00:00 UTC (permalink / raw)
To: pgsql-docs@lists.postgresql.org
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.
^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: create table explicitly mention that unique|primary key constraint will create an
@ 2023-11-27 02:30 Laurenz Albe <laurenz.albe@cybertec.at>
parent: jian he <jian.universality@gmail.com>
0 siblings, 2 replies; 12+ messages in thread
From: Laurenz Albe @ 2023-11-27 02:30 UTC (permalink / raw)
To: jian he <jian.universality@gmail.com>; pgsql-docs@lists.postgresql.org
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
Attachments:
[text/x-patch] 0001-Doc-objects-in-pg_class-share-a-namespace.patch (3.2K, ../../24f01200b651ff87311ae0f46b99eaf91fc3ec43.camel@cybertec.at/2-0001-Doc-objects-in-pg_class-share-a-namespace.patch)
download | inline diff:
From dc38339a9348ab4855600f1bbcd79e7712c21780 Mon Sep 17 00:00:00 2001
From: Laurenz Albe <laurenz.albe@cybertec.at>
Date: Mon, 27 Nov 2023 03:25:41 +0100
Subject: [PATCH] Doc: objects in pg_class share a namespace
Explicitly state that tables, indexes, sequences and other relations
share a single namespace. Also, document that the index that
implements a constraint has the same name as the constraint.
---
doc/src/sgml/ddl.sgml | 7 ++++++-
doc/src/sgml/ref/create_table.sgml | 9 +++++----
2 files changed, 11 insertions(+), 5 deletions(-)
diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml
index 4490e82aa5..46df1dd344 100644
--- a/doc/src/sgml/ddl.sgml
+++ b/doc/src/sgml/ddl.sgml
@@ -2884,7 +2884,12 @@ 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. Tables, indexes,
+ sequences (and all other objects stored in
+ <link linkend="catalog-pg-class"><structname>pg_class</structname></link>)
+ 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
^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: create table explicitly mention that unique|primary key constraint will create an
@ 2023-11-27 05:58 jian he <jian.universality@gmail.com>
parent: Laurenz Albe <laurenz.albe@cybertec.at>
1 sibling, 0 replies; 12+ messages in thread
From: jian he @ 2023-11-27 05:58 UTC (permalink / raw)
To: Laurenz Albe <laurenz.albe@cybertec.at>; +Cc: pgsql-docs@lists.postgresql.org
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.
^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: create table explicitly mention that unique|primary key constraint will create an
@ 2024-01-18 14:54 Peter Eisentraut <peter@eisentraut.org>
parent: Laurenz Albe <laurenz.albe@cybertec.at>
1 sibling, 2 replies; 12+ messages in thread
From: Peter Eisentraut @ 2024-01-18 14:54 UTC (permalink / raw)
To: Laurenz Albe <laurenz.albe@cybertec.at>; jian he <jian.universality@gmail.com>; pgsql-docs@lists.postgresql.org
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.
^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: create table explicitly mention that unique|primary key constraint will create an
@ 2024-01-18 21:21 David G. Johnston <david.g.johnston@gmail.com>
parent: Peter Eisentraut <peter@eisentraut.org>
1 sibling, 1 reply; 12+ messages in thread
From: David G. Johnston @ 2024-01-18 21:21 UTC (permalink / raw)
To: Peter Eisentraut <peter@eisentraut.org>; +Cc: Laurenz Albe <laurenz.albe@cybertec.at>; jian he <jian.universality@gmail.com>; pgsql-docs@lists.postgresql.org
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.
Attachments:
[text/x-patch] 0001-Doc-objects-in-pg_class-share-a-namespace-v2.patch (6.9K, ../../CAKFQuwZDggN=qaKt3N5rTaiRuzsWhgvF53cCBe+Bm4vFiyt5fQ@mail.gmail.com/3-0001-Doc-objects-in-pg_class-share-a-namespace-v2.patch)
download | inline diff:
From 4ba026d1a42e074df103a769e0f6b71629631c87 Mon Sep 17 00:00:00 2001
From: "David G. Johnston" <david.g.johnston@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
^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: create table explicitly mention that unique|primary key constraint will create an
@ 2024-01-19 10:46 Laurenz Albe <laurenz.albe@cybertec.at>
parent: Peter Eisentraut <peter@eisentraut.org>
1 sibling, 2 replies; 12+ messages in thread
From: Laurenz Albe @ 2024-01-19 10:46 UTC (permalink / raw)
To: Peter Eisentraut <peter@eisentraut.org>; jian he <jian.universality@gmail.com>; pgsql-docs@lists.postgresql.org
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
Attachments:
[text/x-patch] v3-0001-Doc-All-relations-share-a-namespace.patch (3.4K, ../../207308248667f3364423e4c61a84e267e7860c9c.camel@cybertec.at/2-v3-0001-Doc-All-relations-share-a-namespace.patch)
download | inline diff:
From b85ccf59ad0575e5040b17bbed5d2e152217df47 Mon Sep 17 00:00:00 2001
From: Laurenz Albe <laurenz.albe@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
^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: create table explicitly mention that unique|primary key constraint will create an
@ 2024-01-26 13:31 vignesh C <vignesh21@gmail.com>
parent: Laurenz Albe <laurenz.albe@cybertec.at>
1 sibling, 1 reply; 12+ messages in thread
From: vignesh C @ 2024-01-26 13:31 UTC (permalink / raw)
To: Laurenz Albe <laurenz.albe@cybertec.at>; +Cc: Peter Eisentraut <peter@eisentraut.org>; jian he <jian.universality@gmail.com>; pgsql-docs@lists.postgresql.org
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
^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: create table explicitly mention that unique|primary key constraint will create an
@ 2024-01-26 15:37 David G. Johnston <david.g.johnston@gmail.com>
parent: Laurenz Albe <laurenz.albe@cybertec.at>
1 sibling, 0 replies; 12+ messages in thread
From: David G. Johnston @ 2024-01-26 15:37 UTC (permalink / raw)
To: Laurenz Albe <laurenz.albe@cybertec.at>; +Cc: Peter Eisentraut <peter@eisentraut.org>; jian he <jian.universality@gmail.com>; pgsql-docs@lists.postgresql.org
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,
David J.
^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: create table explicitly mention that unique|primary key constraint will create an
@ 2024-01-26 15:52 Laurenz Albe <laurenz.albe@cybertec.at>
parent: vignesh C <vignesh21@gmail.com>
0 siblings, 1 reply; 12+ messages in thread
From: Laurenz Albe @ 2024-01-26 15:52 UTC (permalink / raw)
To: vignesh C <vignesh21@gmail.com>; +Cc: Peter Eisentraut <peter@eisentraut.org>; jian he <jian.universality@gmail.com>; pgsql-docs@lists.postgresql.org
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
Attachments:
[text/x-patch] v4-0001-Doc-All-relations-share-a-namespace.patch (3.4K, ../../8334989d2db6ae58b54d4d43a73e7419aa920e0d.camel@cybertec.at/2-v4-0001-Doc-All-relations-share-a-namespace.patch)
download | inline diff:
From 193d6d6c20f0c2976e0b63f1896978545def3fe8 Mon Sep 17 00:00:00 2001
From: Laurenz Albe <laurenz.albe@cybertec.at>
Date: Fri, 26 Jan 2024 16:50:11 +0100
Subject: [PATCH v4] 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 | 8 +++++---
2 files changed, 10 insertions(+), 4 deletions(-)
diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml
index fc03a349f0..434e074df1 100644
--- a/doc/src/sgml/ddl.sgml
+++ b/doc/src/sgml/ddl.sgml
@@ -3003,7 +3003,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 079af9126a..bdc3541930 100644
--- a/doc/src/sgml/ref/create_table.sgml
+++ b/doc/src/sgml/ref/create_table.sgml
@@ -1027,7 +1027,8 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
Adding a unique constraint will automatically create a unique B-tree
index on the column or group of columns used in the constraint. But if
the constraint includes a <literal>WITHOUT OVERLAPS</literal> clause, it
- will use a GiST index.
+ will use a GiST index. The created index has the same name as the unique
+ constraint.
</para>
<para>
@@ -1082,6 +1083,7 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
<literal>PRIMARY KEY</literal> constraint will automatically create a
unique B-tree index, or GiST if <literal>WITHOUT OVERLAPS</literal> was
specified, on the column or group of columns used in the constraint.
+ That index has the same name as the primary key constraint.
</para>
<para>
@@ -1118,8 +1120,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
^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: create table explicitly mention that unique|primary key constraint will create an
@ 2024-01-31 11:11 Peter Eisentraut <peter@eisentraut.org>
parent: Laurenz Albe <laurenz.albe@cybertec.at>
0 siblings, 1 reply; 12+ messages in thread
From: Peter Eisentraut @ 2024-01-31 11:11 UTC (permalink / raw)
To: Laurenz Albe <laurenz.albe@cybertec.at>; vignesh C <vignesh21@gmail.com>; +Cc: jian he <jian.universality@gmail.com>; pgsql-docs@lists.postgresql.org
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.
^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: create table explicitly mention that unique|primary key constraint will create an
@ 2024-01-31 11:15 Peter Eisentraut <peter@eisentraut.org>
parent: David G. Johnston <david.g.johnston@gmail.com>
0 siblings, 0 replies; 12+ messages in thread
From: Peter Eisentraut @ 2024-01-31 11:15 UTC (permalink / raw)
To: David G. Johnston <david.g.johnston@gmail.com>; +Cc: Laurenz Albe <laurenz.albe@cybertec.at>; jian he <jian.universality@gmail.com>; pgsql-docs@lists.postgresql.org
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.
^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: create table explicitly mention that unique|primary key constraint will create an
@ 2024-01-31 15:54 Laurenz Albe <laurenz.albe@cybertec.at>
parent: Peter Eisentraut <peter@eisentraut.org>
0 siblings, 0 replies; 12+ messages in thread
From: Laurenz Albe @ 2024-01-31 15:54 UTC (permalink / raw)
To: Peter Eisentraut <peter@eisentraut.org>; vignesh C <vignesh21@gmail.com>; +Cc: jian he <jian.universality@gmail.com>; pgsql-docs@lists.postgresql.org
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
^ permalink raw reply [nested|flat] 12+ messages in thread
end of thread, other threads:[~2024-01-31 15:54 UTC | newest]
Thread overview: 12+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2023-11-27 00:00 create table explicitly mention that unique|primary key constraint will create an jian he <jian.universality@gmail.com>
2023-11-27 02:30 ` Laurenz Albe <laurenz.albe@cybertec.at>
2023-11-27 05:58 ` jian he <jian.universality@gmail.com>
2024-01-18 14:54 ` Peter Eisentraut <peter@eisentraut.org>
2024-01-18 21:21 ` David G. Johnston <david.g.johnston@gmail.com>
2024-01-31 11:15 ` Peter Eisentraut <peter@eisentraut.org>
2024-01-19 10:46 ` Laurenz Albe <laurenz.albe@cybertec.at>
2024-01-26 13:31 ` vignesh C <vignesh21@gmail.com>
2024-01-26 15:52 ` Laurenz Albe <laurenz.albe@cybertec.at>
2024-01-31 11:11 ` Peter Eisentraut <peter@eisentraut.org>
2024-01-31 15:54 ` Laurenz Albe <laurenz.albe@cybertec.at>
2024-01-26 15:37 ` David G. Johnston <david.g.johnston@gmail.com>
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