bk commit - mysqldoc@docsrva tree (jon:1.3669)

[jon]

Below is the list of changes that have just been committed into a local
mysqldoc repository of jon. When jon does a push these changes will
be propagated to the main repository and, within 24 hours after the
push, to the public repository.
For information on how to access the public repository
see http://www.mysql.com/doc/I/n/Installing_source_tree.html

ChangeSet
  1.3669 05/10/06 16:59:29 jon@stripped +2 -0
  5.1/Partitioning: 
    Remainder of RANGE/LIST partition management section.
  
  Minor edit to tools/xmlformat.conf file.

  tools/xmlformat.conf
    1.17 05/10/06 16:59:28 jon@stripped +1 -1
    Make foreignphrase element inline.

  refman-5.1/partitioning.xml
    1.25 05/10/06 16:59:28 jon@stripped +107 -11
    Remainder of RANGE/LIST partition management section.

# This is a BitKeeper patch.  What follows are the unified diffs for the
# set of deltas contained in the patch.  The rest of the patch, the part
# that BitKeeper cares about, is below these diffs.
# User:	jon
# Host:	ghidora.site
# Root:	/home/jon/bk/mysqldoc

--- 1.16/tools/xmlformat.conf	2005-09-08 02:57:27 +10:00
+++ 1.17/tools/xmlformat.conf	2005-10-06 16:59:28 +10:00
@@ -84,7 +84,7 @@
 filename citetitle keycap \
 guibutton guilabel guimenu guisubmenu \
 quote superscript firstterm \
-methodname property function phrase envar
+methodname property function phrase envar foreignphrase
     format          inline
 
 # Begin each element on new line, indenting sub elements two spaces.

--- 1.24/refman-5.1/partitioning.xml	2005-10-06 11:49:39 +10:00
+++ 1.25/refman-5.1/partitioning.xml	2005-10-06 16:59:28 +10:00
@@ -1834,6 +1834,11 @@
         order to accomplish this:
       </para>
       
+      <remark role="todo">
+        [js] Verify that this is the correct syntax for REORGANISE
+        ( = "file a bug and see what Mikael says").
+      </remark>
+      
 <programlisting>
 ALTER TABLE members REORGANISE PARTITION p0 (
     PARTITION s0 VALUES LESS THAN (1960),
@@ -1899,7 +1904,7 @@
           PARTITION</literal>. For example, you can reorganise all four
         partitions of the <literal>members</literal> table into two, as
         follows: 
-      </para>
+      </para>      
       
 <programlisting>
 ALTER TABLE members REORGANISE PARTITION p0,p1,p2,p3 (
@@ -1909,18 +1914,22 @@
 </programlisting>
       
       <para>
-        Nor are you limited to using <literal>REORGANISE
-          PARTITION</literal> with tables that are partitioned by range.
-        Let us turn our attention back to the problem of adding a new 
-        partition to the list-partitioned <literal>tt</literal> table
-        and failing because the new partition had a value that was
-        already present in the value-list of one of the existing
-        partitions. We can handle this by adding a partition that
-        contains only non-conflicting values, and then reorganising
-        the new partition and the existing one so that the value which
-        was stored in the existing one is now moved to the new one:
+        You can also use <literal>REORGANISE PARTITION</literal> with
+        tables that are partitioned by <literal>LIST</literal>. Let us
+        return to the problem of adding a new partition to the
+        list-partitioned <literal>tt</literal> table and failing because
+        the new partition had a value that was already present in the
+        value-list of one of the existing partitions. We can handle this
+        by adding a partition that contains only non-conflicting values,
+        and then reorganising the new partition and the existing one so
+        that the value which was stored in the existing one is now moved
+        to the new one: 
       </para>
       
+      <remark role="todo">
+        [js] Is ADD PARTITION really necessary in the following example?  
+      </remark>
+      
 <programlisting>
 ALTER TABLE tt ADD PARTITION (PARTITION np VALUES IN (4, 8));
 ALTER TABLE tt REORGANISE PARTITION p1,np (
@@ -1929,6 +1938,86 @@
 );
 </programlisting>
       
+      <para>
+        Here are some key points to keep in mind when using
+        <literal>ALTER TABLE ... REORGANISE PARTITION</literal> to
+        repartition tables that are partitioned by
+        <literal>RANGE</literal> or <literal>LIST</literal>: 
+      </para>
+      
+      <itemizedlist>        
+        <listitem>
+          <para>
+            The <literal>PARTITION</literal> clauses used to determine
+            the new partitioning scheme are subject to the same rules as
+            those used with a <literal>CREATE TABLE</literal> statement.
+          </para>
+          
+          <para>
+            Most importantl, you should remember that the new
+            partitioning scheme cannot have any overlapping ranges 
+            (applies to tables partitioned by <literal>RANGE</literal>)
+            or sets of values (when reorganising tables partitioned by
+            <literal>LIST</literal>). 
+          </para>
+        </listitem>
+        
+        <listitem>
+          <para>
+            The combination of partitions in the
+            <replaceable>partition_definitions</replaceable> list should
+            account for the same range or set of values overall as the
+            combined partitions named in the
+            <replaceable>partition_list</replaceable>.
+          </para>
+          
+          <para>
+            For instance, in the <literal>members</literal> table used
+            as an example in this section, partitions
+            <literal>p1</literal> and <literal>p2</literal>
together
+            cover the years 1980 through 1999. Therefore, any
+            reorganisation of these two partitions should cover the same
+            range of years overall.
+          </para>
+        </listitem>
+        
+        <listitem>
+          <para>
+            For tables partitioned by <literal>RANGE</literal>, you can
+            reorganise only adjacent partitions; you cannot skip over
+            range partitions.  
+          </para>
+          
+          <para>
+            For instance, you could not reorganise the
+            <literal>members</literal> table used as an example in this
+            section using a statement beginning with <literal>ALTER
+              TABLE members REORGANISE PARTITION p0,p2 ...</literal>
+            because <literal>p0</literal> covers the years prior to 1970
+            and <literal>p2</literal> the years from 1990 through 1999
+            inclusive, and thus the two are not ajacent partitions.
+          </para>
+        </listitem>
+        
+        <listitem>
+          <para>
+            You cannot use <literal>REORGANISE PARTITION</literal> to
+            change the table's partitioning type; that is, you cannot
+            (for example) change <literal>RANGE</literal> partitions to
+            <literal>LIST</literal> partitions or <foreignphrase>vice
+              versa</foreignphrase>. You also cannot use this command to
+            change the partitioning expression or column. In MySQL
+            &current-series;, the only way to accomplish either of these
+            tasks is to drop and re-create the table. If you need to
+            retain data already stored in the data, use <literal>CREATE
+              TABLE ... SELECT ...</literal> to create the new table and
+            copy the data from the old one, drop the old table, and then
+            rename the new table.
+          </para>
+        </listitem>
+      </itemizedlist>
+      
+      
     </section>
     
     <section id="partitioning-management-hash-key">
@@ -1943,6 +2032,13 @@
         or by key only. For a discussion of adding and dropping of
         partitions of tables that are partitioned by range or list, see
         <xref linkend="partitioning-management-range-list"/>.
+      </para>
+      
+      <para>
+        You cannot drop partitions from tables that are partitioned by
+        HASH or KEY in the same way that you can from tables that are
+        partitioned by <literal>RANGE</literal> or
+        <literal>LIST</literal>. 
       </para>
       
     </section>