Some small docs improvements motivated by reading the comments for the
authorTom Lane
Sat, 8 Jan 2005 01:44:08 +0000 (01:44 +0000)
committerTom Lane
Sat, 8 Jan 2005 01:44:08 +0000 (01:44 +0000)
7.4 interactive docs.

doc/src/sgml/ddl.sgml
doc/src/sgml/history.sgml
doc/src/sgml/query.sgml
doc/src/sgml/start.sgml

index 2504970a7e39daac148ee064be74f40d4c749e6f..6d29859ed974d5289df60e97ad409c5e059f2a2b 100644 (file)
@@ -1,4 +1,4 @@
-
+
 
 
  Data Definition
@@ -395,7 +395,28 @@ CREATE TABLE products (
    evaluated whenever the default value is inserted
    (not when the table is created).  A common example
    is that a timestamp column may have a default of now(),
-   so that it gets set to the time of row insertion.
+   so that it gets set to the time of row insertion.  Another common
+   example is generating a serial number for each row.
+   In PostgreSQL this is typically done by
+   something like
+
+CREATE TABLE products (
+    product_no integer DEFAULT nextval('products_product_no_seq'),
+    ...
+);
+
+   where the nextval() function supplies successive values
+   from a sequence object (see 
+   linkend="functions-sequence">). This arrangement is sufficiently common
+   that there's a special shorthand for it:
+
+CREATE TABLE products (
+    product_no SERIAL,
+    ...
+);
+
+   The SERIAL shorthand is discussed further in 
+   linkend="datatype-serial">.
   
  
 
@@ -1138,6 +1159,12 @@ WHERE c.altitude > 500 and c.tableoid = p.oid;
    
   
 
+  
+   A table can inherit from more than one parent table, in which case it has
+   the union of the columns defined by the parent tables (plus any columns
+   declared specifically for the child table).
+  
+
   
    A serious limitation of the inheritance feature is that indexes (including
    unique constraints) and foreign key constraints only apply to single
index 5247cf3dc7f931473a50466e46a2fec09f3225fa..be84418c7dfbd56196b508ed7c7ebd571dc69d6d 100644 (file)
@@ -1,5 +1,5 @@
 
 
 
@@ -128,10 +128,11 @@ $PostgreSQL: pgsql/doc/src/sgml/history.sgml,v 1.23 2003/11/29 19:51:37 pgsql Ex
 
     
      
-      In addition to the monitor program, a new program
+      A new program
       (psql) was provided for interactive
       SQL queries, which used GNU
-      Readline.
+      Readline.  This largely superseded
+      the old monitor program.
      
     
 
index 33294afd3c52a89b1bea0bf0fb55db852e960287..7478b4251f1e95e2b54aca269de54d6a523a3163 100644 (file)
@@ -1,5 +1,5 @@
 
 
  
@@ -293,7 +293,7 @@ COPY weather FROM '/home/user/weather.txt';
 
 SELECT * FROM weather;
 
-    (here * means all columns).
+    Here * is a shorthand for all columns.
      
       
        While SELECT * is useful for off-the-cuff
@@ -301,6 +301,11 @@ SELECT * FROM weather;
        since adding a column to the table would change the results.
       
      
+    So the same result would be had with:
+
+SELECT city, temp_lo, temp_hi, prcp, date FROM weather;
+
+
     The output should be:
 
 
@@ -314,8 +319,8 @@ SELECT * FROM weather;
    
 
    
-    You may specify any arbitrary expressions in the select list.  For 
-    example, you can do:
+    You can write expressions, not just simple column references, in the
+    select list.  For example, you can do:
 
 SELECT city, (temp_hi+temp_lo)/2 AS temp_avg, date FROM weather;
 
@@ -333,15 +338,18 @@ SELECT city, (temp_hi+temp_lo)/2 AS temp_avg, date FROM weather;
    
 
    
-    Arbitrary Boolean operators (AND,
+    A query can be qualified by adding a WHERE
+    clause that specifies which rows are wanted.  The WHERE
+    clause contains a Boolean (truth value) expression, and only rows for
+    which the Boolean expression is true are returned.  The usual
+    Boolean operators (AND,
     OR, and NOT) are allowed in
-    the qualification of a query.  For example, the following
+    the qualification.  For example, the following
     retrieves the weather of San Francisco on rainy days:
 
 
 SELECT * FROM weather
-    WHERE city = 'San Francisco'
-    AND prcp > 0.0;
+    WHERE city = 'San Francisco' AND prcp > 0.0;
 
     Result:
 
@@ -354,16 +362,43 @@ SELECT * FROM weather
 
    
     ORDER BY
+
+    You can request that the results of a query
+    be returned in sorted order:
+
+
+SELECT * FROM weather
+    ORDER BY city;
+
+
+
+     city      | temp_lo | temp_hi | prcp |    date
+---------------+---------+---------+------+------------
+ Hayward       |      37 |      54 |      | 1994-11-29
+ San Francisco |      43 |      57 |    0 | 1994-11-29
+ San Francisco |      46 |      50 | 0.25 | 1994-11-27
+
+
+    In this example, the sort order isn't fully specified, and so you
+    might get the San Francisco rows in either order.  But you'd always
+    get the results shown above if you do
+
+
+SELECT * FROM weather
+    ORDER BY city, temp_lo;
+
+   
+
+   
     DISTINCT
     duplicate
 
-    As a final note, you can request that the results of a query can
-    be returned in sorted order or with duplicate rows removed:
+    You can request that duplicate rows be removed from the result of
+    a query:
 
 
 SELECT DISTINCT city
-    FROM weather
-    ORDER BY city;
+    FROM weather;
 
 
 
@@ -374,8 +409,26 @@ SELECT DISTINCT city
 (2 rows)
 
 
-    DISTINCT and ORDER BY can be
-    used separately, of course.
+    Here again, the result row ordering might vary.
+    You can ensure consistent results by using DISTINCT and
+    ORDER BY together:
+     
+      
+       In some database systems, including older versions of
+       PostgreSQL, the implementation of
+       DISTINCT automatically orders the rows and
+       so ORDER BY is redundant.  But this is not
+       required by the SQL standard, and current
+       PostgreSQL doesn't guarantee that
+       DISTINCT causes the rows to be ordered.
+      
+     
+
+
+SELECT DISTINCT city
+    FROM weather
+    ORDER BY city;
+
    
   
 
index c40f76c8ce39e6f0b972863553eb99af35a19c79..3ae094b37c09da77983997c0b215bcc5e67b1a29 100644 (file)
@@ -1,5 +1,5 @@
 
 
  
@@ -146,7 +146,7 @@ $PostgreSQL: pgsql/doc/src/sgml/start.sgml,v 1.37 2004/12/17 04:50:32 tgl Exp $
    
     Possibly, your site administrator has already created a database
     for your use.  He should have told you what the name of your
-    database is.  In this case you can omit this step and skip ahead
+    database is.  In that case you can omit this step and skip ahead
     to the next section.
    
 
@@ -194,8 +194,28 @@ No such file or directory
    
 
    
-    If you do not have the privileges required to create a database,
-    you will see the following:
+    Another response could be this:
+
+createdb: could not connect to database template1: FATAL:  user "joe" does not
+exist
+
+    where your own login name is mentioned.  This will happen if the
+    administrator has not created a PostgreSQL user account
+    for you.  (PostgreSQL user accounts are distinct from
+    operating system user accounts.)  If you are the administrator, see
+     for help creating accounts.  You will need to
+    become the operating system user under which PostgreSQL
+    was installed (usually postgres) to create the first user
+    account.  It could also be that you were assigned a
+    PostgreSQL user name that is different from your
+    operating system user name; in that case you need to use the 
+    switch or set the PGUSER environment variable to specify your
+    PostgreSQL user name.
+   
+
+   
+    If you have a user account but it does not have the privileges required to
+    create a database, you will see the following:
 
 createdb: database creation failed: ERROR:  permission denied to create database
 
@@ -340,10 +360,10 @@ mydb=#
    
 
    
-    If you have encountered problems starting psql
+    If you encounter problems starting psql
     then go back to the previous section.  The diagnostics of
-    psql and createdb are
-    similar, and if the latter worked the former should work as well.
+    createdb and psql are
+    similar, and if the former worked the latter should work as well.