From fa5d08fbf8a0e5fd4586a6d655ebf17d3b01426d Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Sun, 22 Oct 2006 03:03:41 +0000 Subject: [PATCH] Some desultory copy-editing. --- doc/src/sgml/ddl.sgml | 71 ++++++++++++++++++++++++++--------------------- doc/src/sgml/queries.sgml | 6 ++-- doc/src/sgml/syntax.sgml | 8 +++--- 3 files changed, 46 insertions(+), 39 deletions(-) diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml index f974438988..b253cf98ed 100644 --- a/doc/src/sgml/ddl.sgml +++ b/doc/src/sgml/ddl.sgml @@ -1,4 +1,4 @@ - + Data Definition @@ -146,8 +146,10 @@ DROP TABLE products; Attempting to drop a table that does not exist is an error. Nevertheless, it is common in SQL script files to unconditionally - try to drop each table before creating it, ignoring the error - messages. + try to drop each table before creating it, ignoring any error + messages, so that the script works whether or not the table exists. + (If you like, you can use the DROP TABLE IF EXISTS variant + to avoid the error messages, but this is not standard SQL.) @@ -174,7 +176,7 @@ DROP TABLE products; A column can be assigned a default value. When a new row is - created and no values are specified for some of the columns, the + created and no values are specified for some of the columns, those columns will be filled with their respective default values. A data manipulation command can also request explicitly that a column be set to its default value, without having to know what that value is. @@ -245,7 +247,7 @@ CREATE TABLE products ( standard data type that accepts only positive numbers. Another issue is that you might want to constrain column data with respect to other columns or rows. For example, in a table containing product - information, there should only be one row for each product number. + information, there should be only one row for each product number. @@ -400,11 +402,6 @@ CREATE TABLE products ( ensure that a column does not contain null values, the not-null constraint described in the next section can be used. - - - Check constraints can be useful for enhancing the performance of - partitioned tables. For details see . - @@ -461,7 +458,7 @@ CREATE TABLE products ( NULL constraint. This does not mean that the column must be null, which would surely be useless. Instead, this simply selects the default behavior that the column may be null. - The NULL constraint is not defined in the SQL + The NULL constraint is not present in the SQL standard and should not be used in portable applications. (It was only added to PostgreSQL to be compatible with some other database systems.) Some users, however, @@ -556,7 +553,7 @@ CREATE TABLE products ( In general, a unique constraint is violated when there are two or more rows in the table where the values of all of the columns included in the constraint are equal. - However, null values are not considered equal in this + However, two null values are not considered equal in this comparison. That means even in the presence of a unique constraint it is possible to store duplicate rows that contain a null value in at least one of the constrained @@ -626,8 +623,10 @@ CREATE TABLE example ( - A table can have at most one primary key (while it can have many - unique and not-null constraints). Relational database theory + A table can have at most one primary key. (There can be any number + of unique and not-null constraints, which are functionally the same + thing, but only one can be identified as the primary key.) + Relational database theory dictates that every table must have a primary key. This rule is not enforced by PostgreSQL, but it is usually best to follow it. @@ -878,7 +877,7 @@ CREATE TABLE order_items ( The object identifier (object ID) of a row. This column is only present if the table was created using WITH OIDS, or if the - configuration variable was set. This column is of type + configuration variable was set at the time. This column is of type oid (same name as the column); see for more information about the type. @@ -1017,7 +1016,7 @@ CREATE TABLE order_items ( - The tables in question should be created using WITH + Of course, the tables in question must be created WITH OIDS. As of PostgreSQL 8.1, WITHOUT OIDS is the default. @@ -1096,7 +1095,7 @@ CREATE TABLE order_items ( All these actions are performed using the - command. + command, which see for details beyond those given here. @@ -1129,6 +1128,18 @@ ALTER TABLE products ADD COLUMN description text CHECK (description <> '') constraints later (see below) after you've filled in the new column correctly. + + + + Adding a column with a default requires updating each row of the + table (to store the new column value). However, if no default is + specified, PostgreSQL is able to avoid + the physical update. So if you intend to fill the column with + mostly nondefault values, it's best to add the column with no default, + insert the correct values using UPDATE, and then add any + desired default as described below. + + @@ -1376,17 +1387,19 @@ ALTER TABLE products RENAME TO items; GRANT UPDATE ON accounts TO joe; - To grant a privilege to a group, use this syntax: - -GRANT SELECT ON accounts TO GROUP staff; - - The special user name PUBLIC can - be used to grant a privilege to every user on the system. Writing - ALL in place of a specific privilege grants all + Writing ALL in place of a specific privilege grants all privileges that are relevant for the object type. + The special user name PUBLIC can + be used to grant a privilege to every user on the system. Also, + group roles can be set up to help manage privileges when + there are many users of a database — for details see + . + + + To revoke a privilege, use the fittingly named REVOKE command: @@ -1890,7 +1903,7 @@ REVOKE CREATE ON SCHEMA public FROM PUBLIC; - PostgreSQL implements table inheritance + PostgreSQL implements table inheritance, which can be a useful tool for database designers. (SQL:1999 and later define a type inheritance feature, which differs in many respects from the features described here.) @@ -2064,11 +2077,7 @@ VALUES ('New York', NULL, NULL, 'NY'); Table inheritance is typically established when the child table is created, using the INHERITS clause of the - statement. However the related statement CREATE TABLE AS - does not allow inheritance to be specified. - - - + statement. Alternatively, a table which is already defined in a compatible way can have a new parent relationship added, using the INHERIT variant of . @@ -2294,8 +2303,6 @@ VALUES ('New York', NULL, NULL, 'NY'); - - Hash partitioning is not currently supported. diff --git a/doc/src/sgml/queries.sgml b/doc/src/sgml/queries.sgml index 8cf0268fd9..2eedbca3d1 100644 --- a/doc/src/sgml/queries.sgml +++ b/doc/src/sgml/queries.sgml @@ -1,4 +1,4 @@ - + Queries @@ -131,9 +131,9 @@ FROM table_reference , table_r - When a table reference names a table that is the supertable of a + When a table reference names a table that is the parent of a table inheritance hierarchy, the table reference produces rows of - not only that table but all of its subtable successors, unless the + not only that table but all of its descendant tables, unless the key word ONLY precedes the table name. However, the reference produces only the columns that appear in the named table — any columns added in subtables are ignored. diff --git a/doc/src/sgml/syntax.sgml b/doc/src/sgml/syntax.sgml index 3a7b5d9ea1..65c29b835c 100644 --- a/doc/src/sgml/syntax.sgml +++ b/doc/src/sgml/syntax.sgml @@ -1,4 +1,4 @@ - + SQL Syntax @@ -182,8 +182,8 @@ UPDATE "my_table" SET "a" = 5; - Quoted identifiers can contain any character other than a double - quote itself. (To include a double quote, write two double quotes.) + Quoted identifiers can contain any character, except the character + with code zero. (To include a double quote, write two double quotes.) This allows constructing table or column names that would otherwise not be possible, such as ones containing spaces or ampersands. The length limitation still applies. @@ -251,7 +251,7 @@ UPDATE "my_table" SET "a" = 5; Two string constants that are only separated by whitespace with at least one newline are concatenated - and effectively treated as if the string had been written in one + and effectively treated as if the string had been written as one constant. For example: SELECT 'foo' -- 2.11.0