doc: Improve documentation related to table partitioning feature.

Commit f0e44751d7175fa3394da2c8f85e3ceb3cdbfe63 implemented table
partitioning, but failed to mention the "no row movement"
restriction in the documentation.  Fix that and a few other issues.

Amit Langote, with some additional wordsmithing by me.

diff --git a/doc/src/sgml/ref/alter_table.sgml b/doc/src/sgml/ref/alter_table.sgml
index a6a43c4b302c58cd39f23ade8d97de3807724b45..333b01db36e836a4cd18b3f0c4aaa2c0fd631a94 100644 (file)
--- a/doc/src/sgml/ref/alter_table.sgml
+++ b/doc/src/sgml/ref/alter_table.sgml
@@ -715,7 +715,7 @@ ALTER TABLE [ IF EXISTS ] name
    
 
    
-    ATTACH PARTITION partition_name partition_bound_spec
+    ATTACH PARTITION partition_name FOR VALUES partition_bound_spec
     
      
       This form attaches an existing table (which might itself be partitioned)
@@ -1332,7 +1332,7 @@ ALTER TABLE measurement
    Attach a partition to list partitioned table:
 
 ALTER TABLE cities
-    ATTACH PARTITION cities_west FOR VALUES IN ('Los Angeles', 'San Francisco');
+    ATTACH PARTITION cities_ab FOR VALUES IN ('a', 'b');
 
 
   

diff --git a/doc/src/sgml/ref/create_table.sgml b/doc/src/sgml/ref/create_table.sgml
index 8bf8af302b595ab111492b29678d5cdd75300cd1..58f8bf6d6a1133af0e66d037f488c2b5973199cf 100644 (file)
--- a/doc/src/sgml/ref/create_table.sgml
+++ b/doc/src/sgml/ref/create_table.sgml
@@ -248,7 +248,7 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
    
 
    
-    PARTITION OF parent_table
+    PARTITION OF parent_table FOR VALUES partition_bound_spec
     
      
       Creates the table as partition of the specified
@@ -275,7 +275,8 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
      
       Rows inserted into a partitioned table will be automatically routed to
       the correct partition.  If no suitable partition exists, an error will
-      occur.
+      occur.  Also, if updating a row in a given partition causes it to move
+      to another partition due to the new partition key, an error will occur.
      
 
      
@@ -1477,7 +1478,6 @@ CREATE TABLE employees OF employee_type (
    Create a range partitioned table:
 
 CREATE TABLE measurement (
-    city_id         int not null,
     logdate         date not null,
     peaktemp        int,
     unitsales       int
@@ -1488,9 +1488,10 @@ CREATE TABLE measurement (
    Create a list partitioned table:
 
 CREATE TABLE cities (
+    city_id      bigserial not null,
     name         text not null,
-    population   int,
-) PARTITION BY LIST (initcap(name));
+    population   bigint,
+) PARTITION BY LIST (left(lower(name), 1));
 
 
   
@@ -1498,30 +1499,30 @@ CREATE TABLE cities (
 
 CREATE TABLE measurement_y2016m07
     PARTITION OF measurement (
-    unitsales WITH OPTIONS DEFAULT 0
+    unitsales DEFAULT 0
 ) FOR VALUES FROM ('2016-07-01') TO ('2016-08-01');
 
 
   
    Create partition of a list partitioned table:
 
-CREATE TABLE cities_west
+CREATE TABLE cities_ab
     PARTITION OF cities (
     CONSTRAINT city_id_nonzero CHECK (city_id != 0)
-) FOR VALUES IN ('Los Angeles', 'San Francisco');
+) FOR VALUES IN ('a', 'b');
 
 
   
    Create partition of a list partitioned table that is itself further
    partitioned and then add a partition to it:
 
-CREATE TABLE cities_west
+CREATE TABLE cities_ab
     PARTITION OF cities (
     CONSTRAINT city_id_nonzero CHECK (city_id != 0)
-) FOR VALUES IN ('Los Angeles', 'San Francisco') PARTITION BY RANGE (population);
+) FOR VALUES IN ('a', 'b') PARTITION BY RANGE (population);
 
-CREATE TABLE cities_west_10000_to_100000
-    PARTITION OF cities_west FOR VALUES FROM (10000) TO (100000);
+CREATE TABLE cities_ab_10000_to_100000
+    PARTITION OF cities_ab FOR VALUES FROM (10000) TO (100000);
 
  
 

diff --git a/doc/src/sgml/ref/insert.sgml b/doc/src/sgml/ref/insert.sgml
index 06f416039b97d6349549cc2e610338aa6b0fb3bf..00c984d8d54e80312410f6f53a9f7f43ae887561 100644 (file)
--- a/doc/src/sgml/ref/insert.sgml
+++ b/doc/src/sgml/ref/insert.sgml
@@ -526,6 +526,17 @@ INSERT oid count
    updated by the command.
   
  
+ 
+ 
+  Notes
+
+  
+   If the specified table is a partitioned table, each row is routed to
+   the appropriate partition and inserted into it.  If the specified table
+   is a partition, an error will occur if one of the input rows violates
+   the partition constraint.
+  
+ 
 
  
   Examples

diff --git a/doc/src/sgml/ref/update.sgml b/doc/src/sgml/ref/update.sgml
index 2de0f4aad109a5c659dd7758829376d26124ef52..8a1619fb68b60d2f6d3df10928d87324a2044320 100644 (file)
--- a/doc/src/sgml/ref/update.sgml
+++ b/doc/src/sgml/ref/update.sgml
@@ -279,6 +279,14 @@ UPDATE count
    sub-selects is safer, though often harder to read and slower than
    using a join.
   
+
+  
+   In the case of a partitioned table, updating a row might cause it to no
+   longer satisfy the partition constraint.  Since there is no provision to
+   move the row to the partition appropriate to the new value of its
+   partitioning key, an error will occur in this case.  This can also happen
+   when updating a partition directly.
+