diff --git a/doc/src/sgml/advanced.sgml b/doc/src/sgml/advanced.sgml index acd548dd29..2f7e43604d 100644 --- a/doc/src/sgml/advanced.sgml +++ b/doc/src/sgml/advanced.sgml @@ -1,5 +1,5 @@ @@ -130,8 +130,8 @@ ERROR: <unnamed> referential integrity violation - key referenced from we The behavior of foreign keys can be finely tuned to your application. We will not go beyond this simple example in this - tutorial, but just refer you to the Reference - Manual for more information. Making correct use of + tutorial, but just refer you to &cite-reference; + for more information. Making correct use of foreign keys will definitely improve the quality of your database applications, so you are strongly encouraged to learn about them. @@ -394,9 +394,8 @@ SELECT name, altitude PostgreSQL has many features not touched upon in this tutorial introduction, which has been oriented toward newer users of SQL. These - features are discussed in more detail in both the - User's Guide and the - Programmer's Guide. + features are discussed in more detail in both &cite-user; + and &cite-programmer;. diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml index 0f10263df0..253d163ede 100644 --- a/doc/src/sgml/ddl.sgml +++ b/doc/src/sgml/ddl.sgml @@ -1,4 +1,4 @@ - + Data Definition @@ -10,7 +10,7 @@ explaining how tables are created and modified and what features are available to control what data is stored in the tables. Subsequently, we discuss how tables can be organized into - namespaces, and how privileges can be assigned to tables. Finally, + schemas, and how privileges can be assigned to tables. Finally, we will briefly look at other features that affect the data storage, such as views, functions, and triggers. Detailed information on these topics is found in &cite-programmer;. @@ -78,7 +78,7 @@ CREATE TABLE my_first_table ( second_column and the type integer. The table and column names follow the identifier syntax explained in . The type names are - also identifiers, but there are some exceptions. Note that the + usually also identifiers, but there are some exceptions. Note that the column list is comma-separated and surrounded by parentheses. @@ -101,7 +101,7 @@ CREATE TABLE products ( When you create many interrelated tables it is wise to choose a - consistent naming patter for the tables and columns. For + consistent naming pattern for the tables and columns. For instance, there is a choice of using singular or plural nouns for table names, both of which are favored by some theorist or other. @@ -287,7 +287,7 @@ CREATE TABLE products ( - The default value may be a scalar expression, which well be + The default value may be a scalar expression, which will be evaluated whenever the default value is inserted (not when the table is created). @@ -618,7 +618,8 @@ CREATE TABLE example ( A foreign key constraint specifies that the values in a column (or - a group of columns) must match the values in some other column. + a group of columns) must match the values appearing in some row + of another table. We say this maintains the referential integrity between two related tables. @@ -758,7 +759,7 @@ CREATE TABLE order_items ( Restricting and cascading deletes are the two most common options. RESTRICT can also be written as NO - ACTON and it's also the default if you don't specify + ACTION and it's also the default if you don't specify anything. There are two other options for what should happen with the foreign key columns when a primary key is deleted: SET NULL and SET DEFAULT. @@ -981,7 +982,7 @@ SET SQL_Inheritance TO OFF; Add columns, - Remove a column, + Remove columns, Add constraints, @@ -993,10 +994,10 @@ SET SQL_Inheritance TO OFF; Change default values, - Rename a column, + Rename columns, - Rename the table. + Rename tables. @@ -1270,7 +1271,7 @@ REVOKE ALL ON accounts FROM PUBLIC; Schemas are analogous to directories at the operating system level, - but schemas cannot be nested. + except that schemas cannot be nested. @@ -1341,7 +1342,7 @@ DROP SCHEMA myschema CASCADE; (since this is one of the ways to restrict the activities of your users to well-defined namespaces). The syntax for that is: -CREATE SCHEMA schemaname AUTHORIZATON username; +CREATE SCHEMA schemaname AUTHORIZATION username; You can even omit the schema name, in which case the schema name will be the same as the user name. See schemaname AUTHORIZATON us In the previous sections we created tables without specifying any - schema names. Those tables (and other objects) are automatically - put into a schema named public. Every new database - contains such a schema. Thus, the following are equivalent: + schema names. By default, such tables (and other objects) are + automatically put into a schema named public. Every new + database contains such a schema. Thus, the following are equivalent: CREATE TABLE products ( ... ); @@ -1550,7 +1551,7 @@ REVOKE CREATE ON public FROM PUBLIC; Schemas can be used to organize your data in many ways. There are - a few usage patterns are recommended and are easily supported by + a few usage patterns that are recommended and are easily supported by the default configuration: @@ -1558,7 +1559,7 @@ REVOKE CREATE ON public FROM PUBLIC; If you do not create any schemas then all users access the public schema implicitly. This simulates the situation where schemas are not available at all. This setup is mainly - recommended when there is only a single user or few cooperating + recommended when there is only a single user or a few cooperating users in a database. This setup also allows smooth transition from the non-schema-aware world. @@ -1586,7 +1587,7 @@ REVOKE CREATE ON public FROM PUBLIC; additional functions provided by third parties, etc.), put them into separate schemas. Remember to grant appropriate privileges to allow the other users to access them. Users can - then refer to these additional object by qualifying the names + then refer to these additional objects by qualifying the names with a schema name, or they can put the additional schemas into their path, as they choose. @@ -1690,9 +1691,10 @@ ERROR: Cannot drop table products because other objects depend on it DROP TABLE products CASCADE; - and all the dependent objects will be removed. Actually, this + and all the dependent objects will be removed. In this case, it doesn't remove the orders table, it only removes the foreign key - constraint. + constraint. (If you want to check what DROP ... CASCADE will do, + run DROP without CASCADE and read the NOTICEs.) @@ -1709,7 +1711,8 @@ DROP TABLE products CASCADE; According to the SQL standard, specifying either RESTRICT or CASCADE is required. No database system actually implements it that way, but - the defaults might be different. + whether the default behavior is RESTRICT or + CASCADE varies across systems. @@ -1718,7 +1721,8 @@ DROP TABLE products CASCADE; Foreign key constraint dependencies and serial column dependencies from PostgreSQL versions prior to 7.3 are not maintained or created during the - upgrade process. All other dependency types survive the upgrade. + upgrade process. All other dependency types will be properly + created during an upgrade. diff --git a/doc/src/sgml/dml.sgml b/doc/src/sgml/dml.sgml index 5bcec13975..788f4d7dac 100644 --- a/doc/src/sgml/dml.sgml +++ b/doc/src/sgml/dml.sgml @@ -1,4 +1,4 @@ - + Data Manipulation @@ -119,8 +119,8 @@ INSERT INTO products DEFAULT VALUES; necessarily possible to directly specify which row to update. Instead, you specify which conditions a row must meet in order to be updated. Only if you have a primary key in the table (no matter - whether you declared it or not) you can address rows individually - by choosing a condition that matches the primary key only. + whether you declared it or not) can you reliably address individual rows, + by choosing a condition that matches the primary key. Graphical database access tools rely on this fact to allow you to update rows individually. @@ -195,5 +195,13 @@ UPDATE mytable SET a = 5, b = 3, c = 1 WHERE a > 0; DELETE FROM products WHERE price = 10; + + + If you simply write + +DELETE FROM products; + + then all rows in the table will be deleted! Caveat programmer. + diff --git a/doc/src/sgml/queries.sgml b/doc/src/sgml/queries.sgml index aa2df9af1d..12f043b95f 100644 --- a/doc/src/sgml/queries.sgml +++ b/doc/src/sgml/queries.sgml @@ -1,4 +1,4 @@ - + Queries @@ -35,13 +35,12 @@ SELECT * FROM table1; table1. (The method of retrieval depends on the client application. For example, the psql program will display an ASCII-art - table on the screen, client libraries will offer functions to + table on the screen, while client libraries will offer functions to retrieve individual rows and columns.) The select list specification * means all columns that the table expression happens to provide. A select list can also select a - subset of the available columns or even make calculations on the - columns before retrieving them; see . For example, if + subset of the available columns or make calculations using the + columns. For example, if table1 has columns named a, b, and c (and perhaps others) you can make the following query: @@ -50,6 +49,7 @@ SELECT a, b + c FROM table1; (assuming that b and c are of a numerical data type). + See for more details. @@ -62,7 +62,7 @@ SELECT a, b + c FROM table1; SELECT 3 * 4; This is more useful if the expressions in the select list return - varying results. For example, you could call a function this way. + varying results. For example, you could call a function this way: SELECT random(); @@ -266,7 +266,7 @@ FROM table_reference , table_r First, an inner join is performed. Then, for each row in T1 that does not satisfy the join condition with any row in - T2, a joined row is returned with null values in columns of + T2, a joined row is added with null values in columns of T2. Thus, the joined table unconditionally has at least one row for each row in T1. @@ -280,7 +280,7 @@ FROM table_reference , table_r First, an inner join is performed. Then, for each row in T2 that does not satisfy the join condition with any row in - T1, a joined row is returned with null values in columns of + T1, a joined row is added with null values in columns of T1. This is the converse of a left join: the result table will unconditionally have a row for each row in T2. @@ -294,10 +294,10 @@ FROM table_reference , table_r First, an inner join is performed. Then, for each row in T1 that does not satisfy the join condition with any row in - T2, a joined row is returned with null values in columns of + T2, a joined row is added with null values in columns of T2. Also, for each row of T2 that does not satisfy the join condition with any row in T1, a joined row with null - values in the columns of T1 is returned. + values in the columns of T1 is added. @@ -602,7 +602,7 @@ FROM a NATURAL JOIN b WHERE b.val > 5 JOIN syntax in the FROM clause is probably not as portable to other SQL database products. For outer joins there is no choice in any case: they must be done in - the FROM clause. A ON/USING + the FROM clause. An ON/USING clause of an outer join is not equivalent to a WHERE condition, because it determines the addition of rows (for unmatched input rows) as well as the removal of rows @@ -692,11 +692,11 @@ SELECT select_list In the second query, we could not have written SELECT * - FROM test1 GROUP BY x;, because there is no single value + FROM test1 GROUP BY x, because there is no single value for the column y that could be associated with each group. In general, if a table is grouped, columns that are not used in the grouping cannot be referenced except in aggregate - expressions, for example: + expressions. An example with aggregate expressions is: => SELECT x, sum(y) FROM test1 GROUP BY x; x | sum @@ -717,25 +717,25 @@ SELECT select_list they have a known constant value per group. - + Grouping without aggregate expressions effectively calculates the set of distinct values in a column. This can also be achieved using the DISTINCT clause (see ). - + - Here is another example: A sum(sales) on a + Here is another example: sum(sales) on a table grouped by product code gives the total sales for each product, not the total sales on all products. SELECT product_id, p.name, (sum(s.units) * p.price) AS sales FROM products p LEFT JOIN sales s USING (product_id) - GROUP BY pid, p.name, p.price; + GROUP BY product_id, p.name, p.price; - In this example, the columns pid, + In this example, the columns product_id, p.name, and p.price must be in the GROUP BY clause since they are referenced in the query select list. (Depending on how exactly the products @@ -767,7 +767,7 @@ SELECT product_id, p.name, (sum(s.units) * p.price) AS sales SELECT select_list FROM ... WHERE ... GROUP BY ... HAVING boolean_expression Expressions in the HAVING clause can refer both to - grouped expressions and to ungrouped expression (which necessarily + grouped expressions and to ungrouped expressions (which necessarily involve an aggregate function). @@ -794,7 +794,7 @@ SELECT select_list FROM ... WHERE ... SELECT product_id, p.name, (sum(s.units) * (p.price - p.cost)) AS profit - FROM products p LEFT JOIN sales s USING (pid) + FROM products p LEFT JOIN sales s USING (product_id) WHERE s.date > CURRENT_DATE - INTERVAL '4 weeks' GROUP BY product_id, p.name, p.price, p.cost HAVING sum(p.price * s.units) > 5000; @@ -1093,7 +1093,7 @@ SELECT a AS b FROM table1 ORDER BY a; If more than one sort column is specified, the later entries are used to sort rows that are equal under the order imposed by the - earlier sort specifications. + earlier sort columns. diff --git a/doc/src/sgml/query.sgml b/doc/src/sgml/query.sgml index 7a37e7b99a..230baa276b 100644 --- a/doc/src/sgml/query.sgml +++ b/doc/src/sgml/query.sgml @@ -1,5 +1,5 @@ @@ -205,7 +205,7 @@ INSERT INTO weather VALUES ('San Francisco', 46, 50, 0.25, '1994-11-27'); Constants that are not simple numeric values usually must be surrounded by single quotes ('), as in the example. The - date column is actually quite flexible in what it + date type is actually quite flexible in what it accepts, but for this tutorial we will stick to the unambiguous format shown here. @@ -259,8 +259,7 @@ COPY weather FROM '/home/user/weather.txt'; where the file name for the source file must be available to the backend server machine, not the client, since the backend server reads the file directly. You can read more about the - COPY command in the Reference - Manual. + COPY command in &cite-reference;. @@ -341,10 +340,7 @@ SELECT * FROM weather duplicate As a final note, you can request that the results of a select can - be returned in sorted order or with duplicate rows removed. (Just - to make sure the following won't confuse you, - DISTINCT and ORDER BY can be - used separately.) + be returned in sorted order or with duplicate rows removed: SELECT DISTINCT city @@ -359,6 +355,9 @@ SELECT DISTINCT city San Francisco (2 rows) + + DISTINCT and ORDER BY can be + used separately, of course. diff --git a/doc/src/sgml/start.sgml b/doc/src/sgml/start.sgml index f4ca77fe1f..b7eda72737 100644 --- a/doc/src/sgml/start.sgml +++ b/doc/src/sgml/start.sgml @@ -1,5 +1,5 @@ @@ -31,8 +31,8 @@ $Header: /cvsroot/pgsql/doc/src/sgml/start.sgml,v 1.24 2002/08/13 20:40:43 momji If you are installing PostgreSQL - yourself, then refer to the Administrator's - Guide for instructions on installation, and return to + yourself, then refer to &cite-admin; + for instructions on installation, and return to this guide when the installation is complete. Be sure to follow closely the section about setting up the appropriate environment variables. @@ -87,7 +87,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/start.sgml,v 1.24 2002/08/13 20:40:43 momji The user's client (frontend) application that wants to perform database operations. Client applications can be very diverse - in nature: They could be a text-oriented tool, a graphical + in nature: a client could be a text-oriented tool, a graphical application, a web server that accesses the database to display web pages, or a specialized database maintenance tool. Some client applications are supplied with the @@ -292,8 +292,7 @@ createdb: database creation failed Writing a custom application, using one of the several available language bindings. These possibilities are discussed - further in The PostgreSQL Programmer's - Guide. + further in &cite-programmer;. @@ -353,13 +352,13 @@ mydb=# mydb=> SELECT version(); version ---------------------------------------------------------------- - PostgreSQL 7.2devel on i586-pc-linux-gnu, compiled by GCC 2.96 + PostgreSQL 7.3devel on i586-pc-linux-gnu, compiled by GCC 2.96 (1 row) mydb=> SELECT current_date; date ------------ - 2001-08-31 + 2002-08-31 (1 row) mydb=> SELECT 2 + 2; @@ -391,8 +390,8 @@ mydb=# and psql will quit and return you to your command shell. (For more internal commands, type \? at the psql prompt.) The - full capabilities of psql are documented in the - Reference Manual. If PostgreSQL is + full capabilities of psql are documented in + &cite-reference;. If PostgreSQL is installed correctly you can also type man psql at the operating system shell prompt to see the documentation. In this tutorial we will not use these features explicitly, but you diff --git a/doc/src/sgml/syntax.sgml b/doc/src/sgml/syntax.sgml index 3c606b098a..99e7975b2b 100644 --- a/doc/src/sgml/syntax.sgml +++ b/doc/src/sgml/syntax.sgml @@ -1,5 +1,5 @@ @@ -73,8 +73,8 @@ INSERT INTO MY_TABLE VALUES (3, 'hi there'); a SET token to appear in a certain position, and this particular variation of INSERT also requires a VALUES in order to be complete. The - precise syntax rules for each command are described in the - Reference Manual. + precise syntax rules for each command are described in + &cite-reference;. @@ -206,9 +206,9 @@ UPDATE "my_table" SET "a" = 5; - There are four kinds of implicitly-typed + There are three kinds of implicitly-typed constants in PostgreSQL: - strings, bit strings, integers, and floating-point numbers. + strings, bit strings, and numbers. Constants can also be specified with explicit types, which can enable more accurate representation and more efficient handling by the system. The implicit constants are described below; explicit @@ -271,8 +271,9 @@ SELECT 'foobar'; SELECT 'foo' 'bar'; - is not valid syntax, and PostgreSQL is - consistent with SQL9x in this regard. + is not valid syntax. (This slightly bizarre behavior is specified + by SQL9x; PostgreSQL is + following the standard.) @@ -290,52 +291,52 @@ SELECT 'foo' 'bar'; opening quote (no intervening whitespace), e.g., B'1001'. The only characters allowed within bit-string constants are 0 and - 1. Bit-string constants can be continued + 1. + + + + Alternatively, bit-string constants can be specified in hexadecimal + notation, using a leading X (upper or lower case), + e.g., X'1FF'. This notation is equivalent to + a bit-string constant with four binary digits for each hex digit. + + + + Both forms of bit-string constant can be continued across lines in the same way as regular string constants. - Integer Constants - - - Integer constants in SQL are sequences of decimal digits (0 - though 9) with no decimal point and no exponent. The range of legal values - depends on which integer data type is used, but the plain - integer type accepts values ranging from -2147483648 - to +2147483647. (The optional plus or minus sign is actually a - separate unary operator and not part of the integer constant.) - - - - - Floating-Point Constants + Numeric Constants - floating point + numeric constants - Floating-point constants are accepted in these general forms: + Numeric constants are accepted in these general forms: +digits digits.digitse+-digits digits.digitse+-digits digitse+-digits where digits is one or more decimal - digits. At least one digit must be before or after the decimal - point. At least one digit must follow the exponent delimiter - (e) if that field is present. - Thus, a floating-point constant is distinguished from an integer - constant by the presence of either the decimal point or the - exponent clause (or both). There must not be a space or other - characters embedded in the constant. + digits (0 through 9). At least one digit must be before or after the + decimal point, if one is used. At least one digit must follow the + exponent marker (e), if one is present. + There may not be any spaces or other characters embedded in the + constant. Notice that any leading plus or minus sign is not actually + considered part of the constant; it is an operator applied to the + constant. - These are some examples of valid floating-point constants: + These are some examples of valid numeric constants: +42 3.5 4. .001 @@ -345,14 +346,29 @@ SELECT 'foo' 'bar'; - Floating-point constants are of type DOUBLE - PRECISION. REAL can be specified explicitly - by using SQL string notation or - PostgreSQL type notation: + A numeric constant that contains neither a decimal point nor an + exponent is initially presumed to be type integer if its + value fits in type integer (32 bits); otherwise it is + presumed to be type bigint if its + value fits in type bigint (64 bits); otherwise it is + taken to be type numeric. Constants that contain decimal + points and/or exponents are always initially presumed to be type + numeric. + + + + The initially assigned data type of a numeric constant is just a + starting point for the type resolution algorithms. In most + cases the constant will be automatically coerced to the most + appropriate type depending on context. When necessary, you + can force a numeric value to be interpreted as a specific + data type by casting it. For example, you can force a numeric + value to be treated as type real (float4) + by writing REAL '1.23' -- string style -'1.23'::REAL -- PostgreSQL (historical) style +1.23::REAL -- PostgreSQL (historical) style @@ -921,7 +937,7 @@ SELECT 3 OPERATOR(pg_catalog.+) 4; table (possibly qualified), or an alias for a table defined by means of a FROM clause, or the key words NEW or OLD. - (NEW and OLD can only appear in the action portion of a rule, + (NEW and OLD can only appear in rules, while other correlation names can be used in any SQL statement.) The correlation name and separating dot may be omitted if the column name is unique @@ -939,8 +955,9 @@ SELECT 3 OPERATOR(pg_catalog.+) 4; A positional parameter reference is used to indicate a parameter - in an SQL function. Typically this is used in SQL function - definition statements. The form of a parameter is: + that is supplied externally to an SQL statement. Parameters are + used in SQL function definitions and in prepared queries. + The form of a parameter reference is: $number diff --git a/doc/src/sgml/tutorial.sgml b/doc/src/sgml/tutorial.sgml index 812fb9d390..ed7688de63 100644 --- a/doc/src/sgml/tutorial.sgml +++ b/doc/src/sgml/tutorial.sgml @@ -1,5 +1,5 @@ @@ -25,13 +25,9 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/tutorial.sgml,v 1.15 2001/09/02 23:27 - After you have worked through this tutorial you might want to move on - to reading the User's - Guide]]>]]> to - gain a more formal knowledge of the SQL language, or the - Programmer's - Guide]]>]]> - for information about developing applications for + After you have worked through this tutorial you might want to move on to + reading &cite-user; to gain a more formal knowledge of the SQL language, + or &cite-programmer; for information about developing applications for PostgreSQL.