Questions about 9.0 release note
Hi, I have some questions about 9.0 release note.
I'd like to work for some of them if required. Comments welcome.
* Allow per-tablespace sequential and random page cost variables
(seq_page_cost/(random_page_cost)) via ALTER TABLESPACE ... SET/RESET
^ ^
Are those parentheses around random_page_cost intentional?
They seems to mean just "(seq_page_cost and random_page_cost)".
* EXCLUDE constraints has no tags to be linked.
The item in release note is pointing the following page,
http://developer.postgresql.org/pgdocs/postgres/sql-createtable.html#SQL-CREATETABLE-DESCRIPTION
but the actual description about EXCLUDE constraints are in the subentry
of "Parameters" section. Can we add a tag to <varlistentry> for EXCLUDE?
* "EXCLUDE constraints" is not indexed from the Index page.
Should we have for it? Unique Constraints have a section for them:
http://developer.postgresql.org/pgdocs/postgres/ddl-constraints.html#AEN2431
Regards,
---
Takahiro Itagaki
NTT Open Source Software Center
On Tue, Mar 30, 2010 at 1:37 AM, Takahiro Itagaki
<itagaki.takahiro@oss.ntt.co.jp> wrote:
Hi, I have some questions about 9.0 release note.
I'd like to work for some of them if required. Comments welcome.* Allow per-tablespace sequential and random page cost variables
(seq_page_cost/(random_page_cost)) via ALTER TABLESPACE ... SET/RESET
^ ^
Are those parentheses around random_page_cost intentional?
They seems to mean just "(seq_page_cost and random_page_cost)".* EXCLUDE constraints has no tags to be linked.
The item in release note is pointing the following page,
http://developer.postgresql.org/pgdocs/postgres/sql-createtable.html#SQL-CREATETABLE-DESCRIPTION
but the actual description about EXCLUDE constraints are in the subentry
of "Parameters" section. Can we add a tag to <varlistentry> for EXCLUDE?* "EXCLUDE constraints" is not indexed from the Index page.
Should we have for it? Unique Constraints have a section for them:
http://developer.postgresql.org/pgdocs/postgres/ddl-constraints.html#AEN2431
I think I agree with all of these suggestions. Also maybe it should
say CREATE TABLE ... CONSTRAINT ... EXCLUDE rather than CREATE TABLE
CONSTRAINT ... EXCLUDE.
...Robert
Also, where are we on using full names rather than first names only? I
don't see the point in omitting the last names. Are we trying to
obscure to outsiders who is really working on our code?
--
Alvaro Herrera http://www.CommandPrompt.com/
The PostgreSQL Company - Command Prompt, Inc.
"Robert Haas" <robertmhaas@gmail.com> wrote:
* (seq_page_cost/(random_page_cost))
* EXCLUDE constraints has no tags to be linked.
* "EXCLUDE constraints" is not indexed from the Index page.
CREATE TABLE ... CONSTRAINT ... EXCLUDE rather than CREATE TABLE
CONSTRAINT ... EXCLUDE.
Here is a patch to fix the documentation.
For exclusion constraints, I added a tag "SQL-CREATETABLE-exclude"
to <varlistentry> of EXCLUDE in CREATE TABLE documentation. Also,
"Exclusion constraints" section is added to the constraints doc.
But the section is very short and just links to the CREATE TABLE doc.
We could move some contents from CREATE TABLE to the constraints doc.
Regards,
---
Takahiro Itagaki
NTT Open Source Software Center
Attachments:
docfix_20100331.patchapplication/octet-stream; name=docfix_20100331.patchDownload
diff -cprN head/doc/src/sgml/ddl.sgml work/doc/src/sgml/ddl.sgml
*** head/doc/src/sgml/ddl.sgml 2010-02-25 09:58:18.518068000 +0900
--- work/doc/src/sgml/ddl.sgml 2010-03-31 15:46:11.748532000 +0900
*************** CREATE TABLE order_items (
*** 845,850 ****
--- 845,880 ----
<xref linkend="sql-createtable" endterm="sql-createtable-title">.
</para>
</sect2>
+
+ <sect2>
+ <title>Exclusion constraints</title>
+
+ <indexterm>
+ <primary>exclusion constraint</primary>
+ </indexterm>
+
+ <indexterm>
+ <primary>constraint</primary>
+ <secondary>exclusion</secondary>
+ </indexterm>
+
+ <para>
+ Exclusion constraints ensure that that if any two rows are compared on
+ the specified column(s) or expression(s) using the specified operator(s),
+ not all of these comparisons will return <literal>TRUE</>. The syntax is:
+ <programlisting>
+ CREATE TABLE circles (
+ c circle,
+ EXCLUDE USING gist (c WITH &&)
+ );
+ </programlisting>
+ </para>
+
+ <para>
+ See also <link linkend="SQL-CREATETABLE-exclude"><command>CREATE
+ TABLE ... CONSTRAINT ... EXCLUDE</></link> for details.
+ </para>
+ </sect2>
</sect1>
<sect1 id="ddl-system-columns">
diff -cprN head/doc/src/sgml/ref/create_table.sgml work/doc/src/sgml/ref/create_table.sgml
*** head/doc/src/sgml/ref/create_table.sgml 2010-03-01 10:46:55.122677000 +0900
--- work/doc/src/sgml/ref/create_table.sgml 2010-03-31 15:38:12.374337000 +0900
*************** CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY
*** 455,461 ****
</listitem>
</varlistentry>
! <varlistentry>
<term><literal>EXCLUDE [ USING <replaceable class="parameter">index_method</replaceable> ] ( <replaceable class="parameter">exclude_element</replaceable> WITH <replaceable class="parameter">operator</replaceable> [, ... ] ) <replaceable class="parameter">index_parameters</replaceable> [ WHERE ( <replaceable class="parameter">predicate</replaceable> ) ]</literal></term>
<listitem>
<para>
--- 455,461 ----
</listitem>
</varlistentry>
! <varlistentry id="SQL-CREATETABLE-exclude">
<term><literal>EXCLUDE [ USING <replaceable class="parameter">index_method</replaceable> ] ( <replaceable class="parameter">exclude_element</replaceable> WITH <replaceable class="parameter">operator</replaceable> [, ... ] ) <replaceable class="parameter">index_parameters</replaceable> [ WHERE ( <replaceable class="parameter">predicate</replaceable> ) ]</literal></term>
<listitem>
<para>
diff -cprN head/doc/src/sgml/release-9.0.sgml work/doc/src/sgml/release-9.0.sgml
*** head/doc/src/sgml/release-9.0.sgml 2010-03-24 11:50:12.991168000 +0900
--- work/doc/src/sgml/release-9.0.sgml 2010-03-31 15:23:51.604012000 +0900
***************
*** 285,291 ****
<listitem>
<para>
Allow per-tablespace sequential and random page cost variables
! (<varname>seq_page_cost</>/(<varname>random_page_cost</>)) via
<link linkend="SQL-ALTERTABLESPACE"><command>ALTER TABLESPACE
... SET/RESET</></link> (Robert Haas)
</para>
--- 285,291 ----
<listitem>
<para>
Allow per-tablespace sequential and random page cost variables
! (<varname>seq_page_cost</> and <varname>random_page_cost</>) via
<link linkend="SQL-ALTERTABLESPACE"><command>ALTER TABLESPACE
... SET/RESET</></link> (Robert Haas)
</para>
***************
*** 811,818 ****
<para>
This is enabled with the <link
! linkend="SQL-CREATETABLE-description"><command>CREATE
! TABLE CONSTRAINT ... EXCLUDE</></link> clause. While
uniqueness checks could be specified using this syntax,
the real value of this feature is in using complex
operators that do not have built-in constraints.
--- 811,818 ----
<para>
This is enabled with the <link
! linkend="SQL-CREATETABLE-exclude"><command>CREATE
! TABLE ... CONSTRAINT ... EXCLUDE</></link> clause. While
uniqueness checks could be specified using this syntax,
the real value of this feature is in using complex
operators that do not have built-in constraints.
On 31 March 2010 07:56, Takahiro Itagaki <itagaki.takahiro@oss.ntt.co.jp> wrote:
"Robert Haas" <robertmhaas@gmail.com> wrote:
* (seq_page_cost/(random_page_cost))
* EXCLUDE constraints has no tags to be linked.
* "EXCLUDE constraints" is not indexed from the Index page.CREATE TABLE ... CONSTRAINT ... EXCLUDE rather than CREATE TABLE
CONSTRAINT ... EXCLUDE.Here is a patch to fix the documentation.
For exclusion constraints, I added a tag "SQL-CREATETABLE-exclude"
to <varlistentry> of EXCLUDE in CREATE TABLE documentation. Also,
"Exclusion constraints" section is added to the constraints doc.
But the section is very short and just links to the CREATE TABLE doc.
We could move some contents from CREATE TABLE to the constraints doc.Regards,
---
Takahiro Itagaki
NTT Open Source Software Center
Just one typo: "that that".
Regards
Thom
On Wed, Mar 31, 2010 at 2:56 AM, Takahiro Itagaki
<itagaki.takahiro@oss.ntt.co.jp> wrote:
"Robert Haas" <robertmhaas@gmail.com> wrote:
* (seq_page_cost/(random_page_cost))
* EXCLUDE constraints has no tags to be linked.
* "EXCLUDE constraints" is not indexed from the Index page.CREATE TABLE ... CONSTRAINT ... EXCLUDE rather than CREATE TABLE
CONSTRAINT ... EXCLUDE.Here is a patch to fix the documentation.
For exclusion constraints, I added a tag "SQL-CREATETABLE-exclude"
to <varlistentry> of EXCLUDE in CREATE TABLE documentation. Also,
"Exclusion constraints" section is added to the constraints doc.
But the section is very short and just links to the CREATE TABLE doc.
We could move some contents from CREATE TABLE to the constraints doc.
This says:
Exclusion constraints ensure that that if any two rows are compared on
the specified column(s) or expression(s) using the specified
operator(s), not all of these comparisons will return
<literal>TRUE</>.
I think that's backwards - the last clause should say "none of those
comparisons will return <literal>TRUE</>".
Unless I'm confused.
...Robert
Robert Haas <robertmhaas@gmail.com> wrote:
This says:
Exclusion constraints ensure that that if any two rows are
compared on the specified column(s) or expression(s) using the
specified operator(s), not all of these comparisons will return
<literal>TRUE</>.I think that's backwards - the last clause should say "none of
those comparisons will return <literal>TRUE</>".Unless I'm confused.
"not all" seems correct. For example, you could be checking the
room number for equality and a range of time for overlap -- both
must be TRUE to have a problem; otherwise you could only schedule
one thing in the room for all time and one thing at a given time
across all rooms.
-Kevin
On Wed, Mar 31, 2010 at 1:07 PM, Kevin Grittner
<Kevin.Grittner@wicourts.gov> wrote:
Robert Haas <robertmhaas@gmail.com> wrote:
This says:
Exclusion constraints ensure that that if any two rows are
compared on the specified column(s) or expression(s) using the
specified operator(s), not all of these comparisons will return
<literal>TRUE</>.I think that's backwards - the last clause should say "none of
those comparisons will return <literal>TRUE</>".Unless I'm confused.
"not all" seems correct. For example, you could be checking the
room number for equality and a range of time for overlap -- both
must be TRUE to have a problem; otherwise you could only schedule
one thing in the room for all time and one thing at a given time
across all rooms.
Oh, I see. I thought it was referring to all pairs of rows, but I see
now it's referring to pairs of columns, so it's correct.
...Robert
Robert Haas <robertmhaas@gmail.com> wrote:
I thought it was referring to all pairs of rows, but I see
now it's referring to pairs of columns, so it's correct.
If it confused you, I suspect it will confuse others. Offhand,
I can't see how to improve the language, though.
-Kevin
* Kevin Grittner <Kevin.Grittner@wicourts.gov> [100331 13:18]:
If it confused you, I suspect it will confuse others. Offhand,
I can't see how to improve the language, though.
How about a simple:
s/these/the colomn or expression/
Leaving:
... not all of the column or expression comparisons ...
"These" isn't wrong, but if people are being confused about the objects
"these" refer to, being explicit can at least avoid that confusion.
a.
--
Aidan Van Dyk Create like a god,
aidan@highrise.ca command like a king,
http://www.highrise.ca/ work like a slave.
Takahiro Itagaki wrote:
Hi, I have some questions about 9.0 release note.
I'd like to work for some of them if required. Comments welcome.* Allow per-tablespace sequential and random page cost variables
(seq_page_cost/(random_page_cost)) via ALTER TABLESPACE ... SET/RESET
That is a bug, fixed.
Are those parentheses around random_page_cost intentional?
They seems to mean just "(seq_page_cost and random_page_cost)".* EXCLUDE constraints has no tags to be linked.
The item in release note is pointing the following page,
http://developer.postgresql.org/pgdocs/postgres/sql-createtable.html#SQL-CREATETABLE-DESCRIPTION
but the actual description about EXCLUDE constraints are in the subentry
of "Parameters" section. Can we add a tag to <varlistentry> for EXCLUDE?
I was hesitant to add an 'id' link just for the 9.0 docs, but I have now
added a link and linked to it.
* "EXCLUDE constraints" is not indexed from the Index page.
Should we have for it? Unique Constraints have a section for them:
http://developer.postgresql.org/pgdocs/postgres/ddl-constraints.html#AEN2431
I am unclear if exclude really belongs there because that section
contains mostly basic features.
--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com
On Wed, Mar 31, 2010 at 8:19 PM, Bruce Momjian <bruce@momjian.us> wrote:
* "EXCLUDE constraints" is not indexed from the Index page.
Should we have for it? Unique Constraints have a section for them:
http://developer.postgresql.org/pgdocs/postgres/ddl-constraints.html#AEN2431I am unclear if exclude really belongs there because that section
contains mostly basic features.
It seems like the charter of that page is to list all of the types of
constraints that we have, in which case exclusion constraints belong
there too.
...Robert
Kevin Grittner wrote:
Robert Haas <robertmhaas@gmail.com> wrote:
I thought it was referring to all pairs of rows, but I see
now it's referring to pairs of columns, so it's correct.If it confused you, I suspect it will confuse others. Offhand,
I can't see how to improve the language, though.
I have no idea what text this is referring to.
--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com
On Wed, Mar 31, 2010 at 8:21 PM, Bruce Momjian <bruce@momjian.us> wrote:
Kevin Grittner wrote:
Robert Haas <robertmhaas@gmail.com> wrote:
I thought it was referring to all pairs of rows, but I see
now it's referring to pairs of columns, so it's correct.If it confused you, I suspect it will confuse others. Offhand,
I can't see how to improve the language, though.I have no idea what text this is referring to.
Itagaki-san's proposed doc patch, which you seem to have missed.
...Robert
Robert Haas wrote:
On Wed, Mar 31, 2010 at 8:19 PM, Bruce Momjian <bruce@momjian.us> wrote:
* "EXCLUDE constraints" is not indexed from the Index page.
Should we have for it? Unique Constraints have a section for them:
http://developer.postgresql.org/pgdocs/postgres/ddl-constraints.html#AEN2431I am unclear if exclude really belongs there because that section
contains mostly basic features.It seems like the charter of that page is to list all of the types of
constraints that we have, in which case exclusion constraints belong
there too.
OK, but I am incapable of writing such a section.
--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com
On Wed, Mar 31, 2010 at 8:23 PM, Bruce Momjian <bruce@momjian.us> wrote:
Robert Haas wrote:
On Wed, Mar 31, 2010 at 8:19 PM, Bruce Momjian <bruce@momjian.us> wrote:
* "EXCLUDE constraints" is not indexed from the Index page.
Should we have for it? Unique Constraints have a section for them:
http://developer.postgresql.org/pgdocs/postgres/ddl-constraints.html#AEN2431I am unclear if exclude really belongs there because that section
contains mostly basic features.It seems like the charter of that page is to list all of the types of
constraints that we have, in which case exclusion constraints belong
there too.OK, but I am incapable of writing such a section.
Perhaps you could use the one from the patch Itagaki-san already wrote.
...Robert
Alvaro Herrera wrote:
Also, where are we on using full names rather than first names only? I
don't see the point in omitting the last names. Are we trying to
obscure to outsiders who is really working on our code?
You are the third person to ask for this and I was holding up that
change while Josh Berkus worked on rewording the release notes. I just
pinged him and he said he will deal with the merge conflicts so I went
ahead and added missing last names.
--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com
Takahiro Itagaki wrote:
"Robert Haas" <robertmhaas@gmail.com> wrote:
* (seq_page_cost/(random_page_cost))
* EXCLUDE constraints has no tags to be linked.
* "EXCLUDE constraints" is not indexed from the Index page.CREATE TABLE ... CONSTRAINT ... EXCLUDE rather than CREATE TABLE
CONSTRAINT ... EXCLUDE.Here is a patch to fix the documentation.
For exclusion constraints, I added a tag "SQL-CREATETABLE-exclude"
to <varlistentry> of EXCLUDE in CREATE TABLE documentation. Also,
"Exclusion constraints" section is added to the constraints doc.
But the section is very short and just links to the CREATE TABLE doc.
We could move some contents from CREATE TABLE to the constraints doc.
I applied a clarified version of your submitted patch, attached.
--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com
Attachments:
/rtmp/difftext/x-diffDownload
Index: doc/src/sgml/backup.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/backup.sgml,v
retrieving revision 2.144
diff -c -c -r2.144 backup.sgml
*** doc/src/sgml/backup.sgml 22 Feb 2010 17:15:10 -0000 2.144
--- doc/src/sgml/backup.sgml 31 Mar 2010 23:34:20 -0000
***************
*** 604,614 ****
directory).
It is advisable to test your proposed archive command to ensure that it
indeed does not overwrite an existing file, <emphasis>and that it returns
! nonzero status in this case</>. We have found that <literal>cp -i</> does
! this correctly on some platforms but not others. If the chosen command
! does not itself handle this case correctly, you should add a command
! to test for existence of the archive file. For example, something
! like:
<programlisting>
archive_command = 'test ! -f .../%f && cp %p .../%f'
</programlisting>
--- 604,615 ----
directory).
It is advisable to test your proposed archive command to ensure that it
indeed does not overwrite an existing file, <emphasis>and that it returns
! nonzero status in this case</>. On many Unix platforms, <command>cp
! -i</> causes copy to prompt before overwriting a file, and
! <literal>< /dev/null</> causes the prompt (and overwriting) to
! fail. If your platform does not support this behavior, you should
! add a command to test for the existence of the archive file. For
! example, something like:
<programlisting>
archive_command = 'test ! -f .../%f && cp %p .../%f'
</programlisting>
Takahiro Itagaki wrote:
"Robert Haas" <robertmhaas@gmail.com> wrote:
* (seq_page_cost/(random_page_cost))
* EXCLUDE constraints has no tags to be linked.
* "EXCLUDE constraints" is not indexed from the Index page.CREATE TABLE ... CONSTRAINT ... EXCLUDE rather than CREATE TABLE
CONSTRAINT ... EXCLUDE.Here is a patch to fix the documentation.
For exclusion constraints, I added a tag "SQL-CREATETABLE-exclude"
to <varlistentry> of EXCLUDE in CREATE TABLE documentation. Also,
"Exclusion constraints" section is added to the constraints doc.
But the section is very short and just links to the CREATE TABLE doc.
We could move some contents from CREATE TABLE to the constraints doc.
[ Apologies, proper patch now attached.]
I applied a clarified version of your submitted patch.
--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com
Attachments:
/rtmp/docfix_20100331.patchtext/x-diffDownload
diff -cprN head/doc/src/sgml/ddl.sgml work/doc/src/sgml/ddl.sgml
*** head/doc/src/sgml/ddl.sgml 2010-02-25 09:58:18.518068000 +0900
--- work/doc/src/sgml/ddl.sgml 2010-03-31 15:46:11.748532000 +0900
*************** CREATE TABLE order_items (
*** 845,850 ****
--- 845,880 ----
<xref linkend="sql-createtable" endterm="sql-createtable-title">.
</para>
</sect2>
+
+ <sect2>
+ <title>Exclusion constraints</title>
+
+ <indexterm>
+ <primary>exclusion constraint</primary>
+ </indexterm>
+
+ <indexterm>
+ <primary>constraint</primary>
+ <secondary>exclusion</secondary>
+ </indexterm>
+
+ <para>
+ Exclusion constraints ensure that if any two rows are compared on
+ the specified columns or expressions using the specified operators,
+ at least one of these operator comparisons will be false. The syntax is:
+ <programlisting>
+ CREATE TABLE circles (
+ c circle,
+ EXCLUDE USING gist (c WITH &&)
+ );
+ </programlisting>
+ </para>
+
+ <para>
+ See also <link linkend="SQL-CREATETABLE-EXCLUDE"><command>CREATE
+ TABLE ... CONSTRAINT ... EXCLUDE</></link> for details.
+ </para>
+ </sect2>
</sect1>
<sect1 id="ddl-system-columns">
Bruce Momjian <bruce@momjian.us> writes:
+ Exclusion constraints ensure that if any two rows are compared on + the specified columns or expressions using the specified operators, + at least one of these operator comparisons will be false. The syntax is:
Isn't that phrasing outright incorrect? Consider nulls.
regards, tom lane
Tom Lane wrote:
Bruce Momjian <bruce@momjian.us> writes:
+ Exclusion constraints ensure that if any two rows are compared on + the specified columns or expressions using the specified operators, + at least one of these operator comparisons will be false. The syntax is:Isn't that phrasing outright incorrect? Consider nulls.
Well, doesn't a comparison returning null really behave as false?
Should I reword it as "not true" or "false or null"?
--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com
Bruce Momjian <bruce@momjian.us> writes:
Tom Lane wrote:
Bruce Momjian <bruce@momjian.us> writes:
+ Exclusion constraints ensure that if any two rows are compared on + the specified columns or expressions using the specified operators, + at least one of these operator comparisons will be false. The syntax is:Isn't that phrasing outright incorrect? Consider nulls.
Well, doesn't a comparison returning null really behave as false?
Should I reword it as "not true" or "false or null"?
Either one.
regards, tom lane
Tom Lane wrote:
Bruce Momjian <bruce@momjian.us> writes:
Tom Lane wrote:
Bruce Momjian <bruce@momjian.us> writes:
+ Exclusion constraints ensure that if any two rows are compared on + the specified columns or expressions using the specified operators, + at least one of these operator comparisons will be false. The syntax is:Isn't that phrasing outright incorrect? Consider nulls.
Well, doesn't a comparison returning null really behave as false?
Should I reword it as "not true" or "false or null"?Either one.
I used "false or null".
--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com
Attachments:
/rtmp/difftext/x-diffDownload
Index: doc/src/sgml/ddl.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/ddl.sgml,v
retrieving revision 1.91
diff -c -c -r1.91 ddl.sgml
*** doc/src/sgml/ddl.sgml 1 Apr 2010 01:18:17 -0000 1.91
--- doc/src/sgml/ddl.sgml 6 Apr 2010 02:13:57 -0000
***************
*** 861,867 ****
<para>
Exclusion constraints ensure that if any two rows are compared on
the specified columns or expressions using the specified operators,
! at least one of these operator comparisons will be false. The syntax is:
<programlisting>
CREATE TABLE circles (
c circle,
--- 861,868 ----
<para>
Exclusion constraints ensure that if any two rows are compared on
the specified columns or expressions using the specified operators,
! at least one of these operator comparisons will return false or null.
! The syntax is:
<programlisting>
CREATE TABLE circles (
c circle,