List:Commits« Previous MessageNext Message »
From:jon Date:January 15 2006 5:24am
Subject:svn commit - mysqldoc@docsrva: r841 - in trunk: refman-4.1 refman-5.0 refman-5.1 refman-common
View as plain text  
Author: jstephens
Date: 2006-01-15 06:24:34 +0100 (Sun, 15 Jan 2006)
New Revision: 841

Log:

New subsection - Cluster Nodes, Node Groups, Replicas, Partitions

Updated Makefiles



Modified:
   trunk/refman-4.1/Makefile
   trunk/refman-4.1/ndbcluster.xml
   trunk/refman-5.0/Makefile
   trunk/refman-5.0/ndbcluster.xml
   trunk/refman-5.1/Makefile
   trunk/refman-5.1/ndbcluster.xml
   trunk/refman-common/titles.en.ent

Modified: trunk/refman-4.1/Makefile
===================================================================
--- trunk/refman-4.1/Makefile	2006-01-15 04:58:40 UTC (rev 840)
+++ trunk/refman-4.1/Makefile	2006-01-15 05:24:34 UTC (rev 841)
@@ -44,7 +44,7 @@
 
 MANUAL_SRCS_EXTRA = versions.ent ../refman-common/fixedchars.ent ../refman-common/titles.en.ent
 
-MANUAL_SRCS = $(MANUAL_SRCS_EXTRA) manual.xml preface.xml introduction.xml ../refman-common/manual-conventions.en.xml ../refman-common/what-is-mysql-ab.en.xml ../refman-common/what-is.en.xml ../refman-common/maxdb.en.xml ../refman-common/information-sources.xml ../refman-common/bug-reports.xml installing.xml tutorial.xml using-mysql-programs.xml database-administration.xml replication.xml optimization.xml client-utility-programs.xml language-structure.xml reservedwords.xml ../refman-common/reserved-new-4.0.xml ../refman-common/reserved-new-4.1.xml charset.xml data-types.xml functions.xml sql-syntax.xml storage-engines.xml images/blackhole-1.png innodb.xml ndbcluster.xml images/cluster-components-1.png images/multi-comp-1.png spatial-extensions.xml apis.xml connectors.xml connector-odbc.xml images/myarchitecture.png images/mydsn-icon.png images/mydsn.png images/mydsn-setup.png images/mydsn-example.png images/mydsn-test-success.png images/mydsn-test-fail.png images/mydsn-opti!
 ons.png images/mydsn-icon.png images/mydsn.png images/mydsn-trace.png images/myaccess.png images/myaccess-odbc.png images/mydsn-trace.png images/mydll-properties.png images/mydsn-options.png images/myflowchart.png connector-net.xml ../refman-common/news-connector-net.xml connector-j.xml ../refman-common/news-connector-j.xml connector-mxj.xml extending-mysql.xml problems.xml error-handling.xml errmsgs-server.xml errmsgs-client.xml ../refman-common/credits.xml news.xml ../refman-common/news-4.1.xml ../refman-common/news-4.0.xml ../refman-common/news-3.23.xml ../refman-common/news-innodb.xml ../refman-common/news-cluster.xml ../refman-common/news-myodbc.xml porting.xml ../refman-common/environment-variables.xml regexp.xml limits.xml restrictions.xml ../refman-common/gpl-license.xml ../refman-common/mysql-floss-license-exception.xml 
+MANUAL_SRCS = $(MANUAL_SRCS_EXTRA) manual.xml preface.xml introduction.xml ../refman-common/manual-conventions.en.xml ../refman-common/what-is-mysql-ab.en.xml ../refman-common/what-is.en.xml ../refman-common/maxdb.en.xml ../refman-common/information-sources.xml ../refman-common/bug-reports.xml installing.xml tutorial.xml using-mysql-programs.xml database-administration.xml replication.xml optimization.xml client-utility-programs.xml language-structure.xml reservedwords.xml ../refman-common/reserved-new-4.0.xml ../refman-common/reserved-new-4.1.xml charset.xml data-types.xml functions.xml sql-syntax.xml storage-engines.xml innodb.xml images/blackhole-1.png ndbcluster.xml images/cluster-components-1.png images/replicas-groups-1-1.png images/replicas-groups-1-2.png images/multi-comp-1.png spatial-extensions.xml apis.xml connectors.xml connector-odbc.xml images/myarchitecture.png images/mydsn-icon.png images/mydsn.png images/mydsn-setup.png images/mydsn-example.png images/mydsn!
 -test-success.png images/mydsn-test-fail.png images/mydsn-options.png images/mydsn-icon.png images/mydsn.png images/mydsn-trace.png images/myaccess.png images/myaccess-odbc.png images/mydsn-trace.png images/mydll-properties.png images/mydsn-options.png images/myflowchart.png connector-net.xml ../refman-common/news-connector-net.xml connector-j.xml ../refman-common/news-connector-j.xml connector-mxj.xml extending-mysql.xml problems.xml error-handling.xml errmsgs-server.xml errmsgs-client.xml ../refman-common/credits.xml news.xml ../refman-common/news-4.1.xml ../refman-common/news-4.0.xml ../refman-common/news-3.23.xml ../refman-common/news-innodb.xml ../refman-common/news-cluster.xml ../refman-common/news-myodbc.xml porting.xml ../refman-common/environment-variables.xml regexp.xml limits.xml restrictions.xml ../refman-common/gpl-license.xml ../refman-common/mysql-floss-license-exception.xml 
 
 manual-prepped.xml: $(MANUAL_SRCS)
 manual-manprepped.xml: $(MANUAL_SRCS)

Modified: trunk/refman-4.1/ndbcluster.xml
===================================================================
--- trunk/refman-4.1/ndbcluster.xml	2006-01-15 04:58:40 UTC (rev 840)
+++ trunk/refman-4.1/ndbcluster.xml	2006-01-15 05:24:34 UTC (rev 841)
@@ -256,6 +256,12 @@
       </listitem>
 
     </itemizedlist>
+    
+    <para>
+      For a brief introduction to the relationships between nodes, node
+      groups, replicas, and partitions in MySQL Cluster, see 
+      <xref linkend="mysql-cluster-nodes-groups"/>. 
+    </para>
 
     <para>
       Configuration of a cluster involves configuring each individual
@@ -354,6 +360,172 @@
       @subsection How MySQL Cluster Avoids Network Partitioning
     </remark>
 
+    <section id="mysql-cluster-nodes-groups">
+      <title>&title-mysql-cluster-nodes-groups;</title>
+  
+  <remark role="note">
+    Author: Jon Stephens, with valuable assistance from Tomas Ulin, Jeb
+    Miller, and Hartmut Holzgraefe
+  </remark>
+  
+  <para>
+    This section discusses the manner in which MySQL Cluster divides
+    and duplicates data for storage and its implications for CLuster
+    memory requirements.
+  </para>
+  
+  <para>
+    <emphasis role="bold">Concepts</emphasis>
+  </para>
+  
+  <para>
+    Central to an understanding of this topic are the following
+    concepts, listed here with brief definitions:
+  </para>
+  
+  <itemizedlist>
+    <listitem>
+      <para>
+        <emphasis role="bold">(Data) Node</emphasis>: An
+        <command>ndbd</command> process, which stores a
+        <firstterm>replica</firstterm> &mdash;that is, a copy of the
+        <firstterm>partition</firstterm> (see below) assigned to the
+        node group of which the node is a member.
+      </para>
+      
+      <para>
+        Each data node is usually located on a separate computer.
+        However, it is also possible to host multiple data nodes on a
+        single computer having more than one processor. In such cases,
+        it is feasible to run one instance of <command>ndbd</command>
+        per physical CPU. (Note that a processor with multiple cores is
+        still a single processor.)
+      </para>
+      
+      <para>
+        It is common for the terms <quote>node</quote> and <quote>data
+          node</quote> to be used interchangeably when referring to an
+        <command>ndbd</command> process; where mentioned, management
+        nodes (<command>ndb_mgmd</command> processes) and SQL nodes
+        (<command>mysqld</command> processes) are specified as such in
+        this discussion.
+      </para>
+    </listitem>
+    
+    <listitem>
+      <para>
+        <emphasis role="bold">Node Group</emphasis>: A node group
+        consists of one or more nodes, and stores a partition, or set of
+        <firstterm>replicas</firstterm> (see next item). 
+      </para>
+      
+      <para>
+        <emphasis role="bold">Note</emphasis>: Currently, all node
+        groups in a cluster must have the same number of nodes.
+      </para>
+    </listitem>
+    
+    <listitem>
+      <para>
+        <emphasis role="bold">Partition</emphasis>: This is a portion of
+        the data stored by the cluster. There are as many cluster
+        partitions as node groups participating in the cluster, and each
+        node group is responible for keeping at least one copy of the
+        partition assigned to it (that, at least one replica) available
+        to the cluster.
+      </para>
+    </listitem>
+    
+    <listitem>
+      <para>
+        <emphasis role="bold">Replica</emphasis>: This is a copy of a
+        cluster partition. Each node in a node group stores a replica.
+        Also sometimes known as a <firstterm>partition
+          replica</firstterm>.
+      </para>
+    </listitem>
+  </itemizedlist>
+  
+  <para>
+    The following diagram illustrates a MySQL Cluster with four data
+    nodes, arranged in two node groups of two nodes each. Note that no
+    nodes other than data nodes are shown here, although a working
+    cluster requires an <command>ndb_mgm</command> process for cluster
+    management and at least one SQL node in order to access the data
+    stored by the cluster.
+  </para>
+
+  <mediaobject>
+    <imageobject>
+      <imagedata fileref="images/replicas-groups-1-1.png" format="PNG"/>
+    </imageobject>
+    <textobject>
+      <phrase lang="en">A MySQL Cluster, with 2 node groups having 2
+        nodes each</phrase>
+    </textobject>
+  </mediaobject>
+  
+  <para>
+    The data stored by the cluster is divided into two partitions,
+    labeled <emphasis role="bold">A</emphasis> and 
+    <emphasis role="bold">B</emphasis> in the diagram. Each partition is
+    stored &mdash; in multiple copies &mdash; on a node group. The data
+    making up Partition <emphasis role="bold">A</emphasis> is stored on
+    Node <emphasis role="bold">A-1</emphasis>, and this data is
+    identical to that stored by Node 
+    <emphasis role="bold">A-2</emphasis>. The data stored by Nodes
+    <emphasis role="bold">B-1</emphasis> and 
+    <emphasis role="bold">B-2</emphasis> is also the same &mdash; these
+    two nodes store identical copies of the data making up Partition
+    <emphasis role="bold">B</emphasis>.
+  </para>
+  
+  <para>
+    What this means so far as the continued operation of a MySQL
+    Cluster is this: so long as each node group participating in the
+    cluster has at least one <quote>live</quote> node, the cluster has a
+    complete copy of all data and remains viable. This is illustrated in
+    the next diagram.
+  </para>
+  
+  <remark role="todo">
+    [js] Not a very good caption; think of a better one.
+  </remark>
+
+  <mediaobject>
+    <imageobject>
+      <imagedata fileref="images/replicas-groups-1-2.png" format="PNG"/>
+    </imageobject>
+    <textobject>
+      <phrase lang="en">Nodes required to keep a 2x2 cluster viable</phrase>
+    </textobject>
+  </mediaobject>
+  
+  <para>
+    In this example, where the cluster consists of two node groups of
+    two nodes each, any combination of at least one node in Node Group
+    <emphasis role="bold">A</emphasis> and at least one node in Node
+    Group <emphasis role="bold">B</emphasis> is sufficient to keep the
+    cluster <quote>alive</quote> (indicated by arrows in the diagram).
+    However, if both nodes from either node group fail, the remaining
+    two nodes are not sufficient (shown by arrows marked out with an
+    <emphasis role="bold">X</emphasis>); in either case, the cluster has    
+    lost an entire partition and so can no longer provide access to a
+    complete set of all cluster data.
+  </para>
+      
+      <remark role="todo">
+        [js] Add discussion of application of the above to hosts running
+        multiple CPUs.
+      </remark>
+      
+      <remark role="todo">
+        [js] Add description of memory requirements based on Hartmut's
+        example scripts.
+      </remark>
+    </section>
+    
+    
   </section>
 
   <section id="multi-computer">

Modified: trunk/refman-5.0/Makefile
===================================================================
--- trunk/refman-5.0/Makefile	2006-01-15 04:58:40 UTC (rev 840)
+++ trunk/refman-5.0/Makefile	2006-01-15 05:24:34 UTC (rev 841)
@@ -44,7 +44,7 @@
 
 MANUAL_SRCS_EXTRA = versions.ent ../refman-common/fixedchars.ent ../refman-common/titles.en.ent
 
-MANUAL_SRCS = $(MANUAL_SRCS_EXTRA) manual.xml preface.xml introduction.xml ../refman-common/manual-conventions.en.xml ../refman-common/what-is-mysql-ab.en.xml ../refman-common/what-is.en.xml ../refman-common/maxdb.en.xml ../refman-common/information-sources.xml ../refman-common/bug-reports.xml installing.xml tutorial.xml using-mysql-programs.xml database-administration.xml replication.xml optimization.xml client-utility-programs.xml language-structure.xml reservedwords.xml ../refman-common/reserved-new-5.0.xml charset.xml data-types.xml functions.xml sql-syntax.xml storage-engines.xml innodb.xml images/blackhole-1.png ndbcluster.xml images/cluster-components-1.png images/multi-comp-1.png spatial-extensions.xml stored-procedures.xml triggers.xml views.xml information-schema.xml precision-math.xml apis.xml connectors.xml connector-odbc.xml images/myarchitecture.png images/mydsn-icon.png images/mydsn.png images/mydsn-setup.png images/mydsn-example.png images/mydsn-test-success!
 .png images/mydsn-test-fail.png images/mydsn-options.png images/mydsn-icon.png images/mydsn.png images/mydsn-trace.png images/myaccess.png images/myaccess-odbc.png images/mydsn-trace.png images/mydll-properties.png images/mydsn-options.png images/myflowchart.png connector-net.xml ../refman-common/news-connector-net.xml connector-j.xml ../refman-common/news-connector-j.xml connector-mxj.xml extending-mysql.xml problems.xml error-handling.xml errmsgs-server.xml errmsgs-client.xml ../refman-common/credits.xml news.xml ../refman-common/news-5.0.xml ../refman-common/news-cluster.xml ../refman-common/news-myodbc.xml porting.xml ../refman-common/environment-variables.xml regexp.xml limits.xml restrictions.xml ../refman-common/gpl-license.xml ../refman-common/mysql-floss-license-exception.xml 
+MANUAL_SRCS = $(MANUAL_SRCS_EXTRA) manual.xml preface.xml introduction.xml ../refman-common/manual-conventions.en.xml ../refman-common/what-is-mysql-ab.en.xml ../refman-common/what-is.en.xml ../refman-common/maxdb.en.xml ../refman-common/information-sources.xml ../refman-common/bug-reports.xml installing.xml tutorial.xml using-mysql-programs.xml database-administration.xml replication.xml optimization.xml client-utility-programs.xml language-structure.xml reservedwords.xml ../refman-common/reserved-new-5.0.xml charset.xml data-types.xml functions.xml sql-syntax.xml storage-engines.xml innodb.xml images/blackhole-1.png ndbcluster.xml images/cluster-components-1.png images/replicas-groups-1-1.png images/replicas-groups-1-2.png images/multi-comp-1.png spatial-extensions.xml stored-procedures.xml triggers.xml views.xml information-schema.xml precision-math.xml apis.xml connectors.xml connector-odbc.xml images/myarchitecture.png images/mydsn-icon.png images/mydsn.png images/myds!
 n-setup.png images/mydsn-example.png images/mydsn-test-success.png images/mydsn-test-fail.png images/mydsn-options.png images/mydsn-icon.png images/mydsn.png images/mydsn-trace.png images/myaccess.png images/myaccess-odbc.png images/mydsn-trace.png images/mydll-properties.png images/mydsn-options.png images/myflowchart.png connector-net.xml ../refman-common/news-connector-net.xml connector-j.xml ../refman-common/news-connector-j.xml connector-mxj.xml extending-mysql.xml problems.xml error-handling.xml errmsgs-server.xml errmsgs-client.xml ../refman-common/credits.xml news.xml ../refman-common/news-5.0.xml ../refman-common/news-cluster.xml ../refman-common/news-myodbc.xml porting.xml ../refman-common/environment-variables.xml regexp.xml limits.xml restrictions.xml ../refman-common/gpl-license.xml ../refman-common/mysql-floss-license-exception.xml 
 
 manual-prepped.xml: $(MANUAL_SRCS)
 manual-manprepped.xml: $(MANUAL_SRCS)

Modified: trunk/refman-5.0/ndbcluster.xml
===================================================================
--- trunk/refman-5.0/ndbcluster.xml	2006-01-15 04:58:40 UTC (rev 840)
+++ trunk/refman-5.0/ndbcluster.xml	2006-01-15 05:24:34 UTC (rev 841)
@@ -257,6 +257,12 @@
     </itemizedlist>
 
     <para>
+      For a brief introduction to the relationships between nodes, node
+      groups, replicas, and partitions in MySQL Cluster, see 
+      <xref linkend="mysql-cluster-nodes-groups"/>. 
+    </para>
+
+    <para>
       Configuration of a cluster involves configuring each individual
       node in the cluster and setting up individual communication links
       between nodes. MySQL Cluster is currently designed with the
@@ -353,6 +359,172 @@
       @subsection How MySQL Cluster Avoids Network Partitioning
     </remark>
 
+  <section id="mysql-cluster-nodes-groups">
+      <title>&title-mysql-cluster-nodes-groups;</title>
+  
+  <remark role="note">
+    Author: Jon Stephens, with valuable assistance from Tomas Ulin, Jeb
+    Miller, and Hartmut Holzgraefe
+  </remark>
+  
+  <para>
+    This section discusses the manner in which MySQL Cluster divides
+    and duplicates data for storage and its implications for CLuster
+    memory requirements.
+  </para>
+  
+  <para>
+    <emphasis role="bold">Concepts</emphasis>
+  </para>
+  
+  <para>
+    Central to an understanding of this topic are the following
+    concepts, listed here with brief definitions:
+  </para>
+  
+  <itemizedlist>
+    <listitem>
+      <para>
+        <emphasis role="bold">(Data) Node</emphasis>: An
+        <command>ndbd</command> process, which stores a
+        <firstterm>replica</firstterm> &mdash;that is, a copy of the
+        <firstterm>partition</firstterm> (see below) assigned to the
+        node group of which the node is a member.
+      </para>
+      
+      <para>
+        Each data node is usually located on a separate computer.
+        However, it is also possible to host multiple data nodes on a
+        single computer having more than one processor. In such cases,
+        it is feasible to run one instance of <command>ndbd</command>
+        per physical CPU. (Note that a processor with multiple cores is
+        still a single processor.)
+      </para>
+      
+      <para>
+        It is common for the terms <quote>node</quote> and <quote>data
+          node</quote> to be used interchangeably when referring to an
+        <command>ndbd</command> process; where mentioned, management
+        nodes (<command>ndb_mgmd</command> processes) and SQL nodes
+        (<command>mysqld</command> processes) are specified as such in
+        this discussion.
+      </para>
+    </listitem>
+    
+    <listitem>
+      <para>
+        <emphasis role="bold">Node Group</emphasis>: A node group
+        consists of one or more nodes, and stores a partition, or set of
+        <firstterm>replicas</firstterm> (see next item). 
+      </para>
+      
+      <para>
+        <emphasis role="bold">Note</emphasis>: Currently, all node
+        groups in a cluster must have the same number of nodes.
+      </para>
+    </listitem>
+    
+    <listitem>
+      <para>
+        <emphasis role="bold">Partition</emphasis>: This is a portion of
+        the data stored by the cluster. There are as many cluster
+        partitions as node groups participating in the cluster, and each
+        node group is responible for keeping at least one copy of the
+        partition assigned to it (that, at least one replica) available
+        to the cluster.
+      </para>
+    </listitem>
+    
+    <listitem>
+      <para>
+        <emphasis role="bold">Replica</emphasis>: This is a copy of a
+        cluster partition. Each node in a node group stores a replica.
+        Also sometimes known as a <firstterm>partition
+          replica</firstterm>.
+      </para>
+    </listitem>
+  </itemizedlist>
+  
+  <para>
+    The following diagram illustrates a MySQL Cluster with four data
+    nodes, arranged in two node groups of two nodes each. Note that no
+    nodes other than data nodes are shown here, although a working
+    cluster requires an <command>ndb_mgm</command> process for cluster
+    management and at least one SQL node in order to access the data
+    stored by the cluster.
+  </para>
+
+  <mediaobject>
+    <imageobject>
+      <imagedata fileref="images/replicas-groups-1-1.png" format="PNG"/>
+    </imageobject>
+    <textobject>
+      <phrase lang="en">A MySQL Cluster, with 2 node groups having 2
+        nodes each</phrase>
+    </textobject>
+  </mediaobject>
+  
+  <para>
+    The data stored by the cluster is divided into two partitions,
+    labeled <emphasis role="bold">A</emphasis> and 
+    <emphasis role="bold">B</emphasis> in the diagram. Each partition is
+    stored &mdash; in multiple copies &mdash; on a node group. The data
+    making up Partition <emphasis role="bold">A</emphasis> is stored on
+    Node <emphasis role="bold">A-1</emphasis>, and this data is
+    identical to that stored by Node 
+    <emphasis role="bold">A-2</emphasis>. The data stored by Nodes
+    <emphasis role="bold">B-1</emphasis> and 
+    <emphasis role="bold">B-2</emphasis> is also the same &mdash; these
+    two nodes store identical copies of the data making up Partition
+    <emphasis role="bold">B</emphasis>.
+  </para>
+  
+  <para>
+    What this means so far as the continued operation of a MySQL
+    Cluster is this: so long as each node group participating in the
+    cluster has at least one <quote>live</quote> node, the cluster has a
+    complete copy of all data and remains viable. This is illustrated in
+    the next diagram.
+  </para>
+  
+  <remark role="todo">
+    [js] Not a very good caption; think of a better one.
+  </remark>
+
+  <mediaobject>
+    <imageobject>
+      <imagedata fileref="images/replicas-groups-1-2.png" format="PNG"/>
+    </imageobject>
+    <textobject>
+      <phrase lang="en">Nodes required to keep a 2x2 cluster viable</phrase>
+    </textobject>
+  </mediaobject>
+  
+  <para>
+    In this example, where the cluster consists of two node groups of
+    two nodes each, any combination of at least one node in Node Group
+    <emphasis role="bold">A</emphasis> and at least one node in Node
+    Group <emphasis role="bold">B</emphasis> is sufficient to keep the
+    cluster <quote>alive</quote> (indicated by arrows in the diagram).
+    However, if both nodes from either node group fail, the remaining
+    two nodes are not sufficient (shown by arrows marked out with an
+    <emphasis role="bold">X</emphasis>); in either case, the cluster has    
+    lost an entire partition and so can no longer provide access to a
+    complete set of all cluster data.
+  </para>
+      
+      <remark role="todo">
+        [js] Add discussion of application of the above to hosts running
+        multiple CPUs.
+      </remark>
+      
+      <remark role="todo">
+        [js] Add description of memory requirements based on Hartmut's
+        example scripts.
+      </remark>
+    </section>
+    
+    
   </section>
 
   <section id="multi-computer">

Modified: trunk/refman-5.1/Makefile
===================================================================
--- trunk/refman-5.1/Makefile	2006-01-15 04:58:40 UTC (rev 840)
+++ trunk/refman-5.1/Makefile	2006-01-15 05:24:34 UTC (rev 841)
@@ -44,7 +44,7 @@
 
 MANUAL_SRCS_EXTRA = versions.ent ../refman-common/fixedchars.ent ../refman-common/titles.en.ent
 
-MANUAL_SRCS = $(MANUAL_SRCS_EXTRA) manual.xml preface.xml introduction.xml ../refman-common/manual-conventions.en.xml ../refman-common/what-is-mysql-ab.en.xml ../refman-common/what-is.en.xml ../refman-common/maxdb.en.xml ../refman-common/information-sources.xml ../refman-common/bug-reports.xml installing.xml tutorial.xml using-mysql-programs.xml database-administration.xml replication.xml optimization.xml client-utility-programs.xml language-structure.xml reservedwords.xml ../refman-common/reserved-new-5.1.xml charset.xml data-types.xml functions.xml sql-syntax.xml pluggable-storage.xml images/pluggable-storage-overview.png storage-engines.xml innodb.xml images/blackhole-1.png custom-engine.xml images/custom-engine-overview.png ndbcluster.xml images/cluster-components-1.png images/multi-comp-1.png partitioning.xml spatial-extensions.xml stored-procedures.xml triggers.xml views.xml information-schema.xml precision-math.xml apis.xml connectors.xml connector-odbc.xml images/my!
 architecture.png images/mydsn-icon.png images/mydsn.png images/mydsn-setup.png images/mydsn-example.png images/mydsn-test-success.png images/mydsn-test-fail.png images/mydsn-options.png images/mydsn-icon.png images/mydsn.png images/mydsn-trace.png images/myaccess.png images/myaccess-odbc.png images/mydsn-trace.png images/mydll-properties.png images/mydsn-options.png images/myflowchart.png connector-net.xml ../refman-common/news-connector-net.xml connector-j.xml ../refman-common/news-connector-j.xml connector-mxj.xml extending-mysql.xml problems.xml error-handling.xml errmsgs-server.xml errmsgs-client.xml ../refman-common/credits.xml news.xml ../refman-common/news-5.1.xml ../refman-common/news-myodbc.xml porting.xml ../refman-common/environment-variables.xml regexp.xml limits.xml restrictions.xml ../refman-common/gpl-license.xml ../refman-common/mysql-floss-license-exception.xml 
+MANUAL_SRCS = $(MANUAL_SRCS_EXTRA) manual.xml preface.xml introduction.xml ../refman-common/manual-conventions.en.xml ../refman-common/what-is-mysql-ab.en.xml ../refman-common/what-is.en.xml ../refman-common/maxdb.en.xml ../refman-common/information-sources.xml ../refman-common/bug-reports.xml installing.xml tutorial.xml using-mysql-programs.xml database-administration.xml replication.xml optimization.xml client-utility-programs.xml language-structure.xml reservedwords.xml ../refman-common/reserved-new-5.1.xml charset.xml data-types.xml functions.xml sql-syntax.xml pluggable-storage.xml images/pluggable-storage-overview.png storage-engines.xml innodb.xml images/blackhole-1.png custom-engine.xml images/custom-engine-overview.png ndbcluster.xml images/cluster-components-1.png images/replicas-groups-1-1.png images/replicas-groups-1-2.png images/multi-comp-1.png partitioning.xml spatial-extensions.xml stored-procedures.xml triggers.xml views.xml information-schema.xml precision!
 -math.xml apis.xml connectors.xml connector-odbc.xml images/myarchitecture.png images/mydsn-icon.png images/mydsn.png images/mydsn-setup.png images/mydsn-example.png images/mydsn-test-success.png images/mydsn-test-fail.png images/mydsn-options.png images/mydsn-icon.png images/mydsn.png images/mydsn-trace.png images/myaccess.png images/myaccess-odbc.png images/mydsn-trace.png images/mydll-properties.png images/mydsn-options.png images/myflowchart.png connector-net.xml ../refman-common/news-connector-net.xml connector-j.xml ../refman-common/news-connector-j.xml connector-mxj.xml extending-mysql.xml problems.xml error-handling.xml errmsgs-server.xml errmsgs-client.xml ../refman-common/credits.xml news.xml ../refman-common/news-5.1.xml ../refman-common/news-myodbc.xml porting.xml ../refman-common/environment-variables.xml regexp.xml limits.xml restrictions.xml ../refman-common/gpl-license.xml ../refman-common/mysql-floss-license-exception.xml 
 
 manual-prepped.xml: $(MANUAL_SRCS)
 manual-manprepped.xml: $(MANUAL_SRCS)

Modified: trunk/refman-5.1/ndbcluster.xml
===================================================================
--- trunk/refman-5.1/ndbcluster.xml	2006-01-15 04:58:40 UTC (rev 840)
+++ trunk/refman-5.1/ndbcluster.xml	2006-01-15 05:24:34 UTC (rev 841)
@@ -257,6 +257,12 @@
     </itemizedlist>
 
     <para>
+      For a brief introduction to the relationships between nodes, node
+      groups, replicas, and partitions in MySQL Cluster, see 
+      <xref linkend="mysql-cluster-nodes-groups"/>. 
+    </para>
+
+    <para>
       Configuration of a cluster involves configuring each individual
       node in the cluster and setting up individual communication links
       between nodes. MySQL Cluster is currently designed with the
@@ -353,6 +359,172 @@
       @subsection How MySQL Cluster Avoids Network Partitioning
     </remark>
 
+  <section id="mysql-cluster-nodes-groups">
+      <title>&title-mysql-cluster-nodes-groups;</title>
+  
+  <remark role="note">
+    Author: Jon Stephens, with valuable assistance from Tomas Ulin, Jeb
+    Miller, and Hartmut Holzgraefe
+  </remark>
+  
+  <para>
+    This section discusses the manner in which MySQL Cluster divides
+    and duplicates data for storage and its implications for CLuster
+    memory requirements.
+  </para>
+  
+  <para>
+    <emphasis role="bold">Concepts</emphasis>
+  </para>
+  
+  <para>
+    Central to an understanding of this topic are the following
+    concepts, listed here with brief definitions:
+  </para>
+  
+  <itemizedlist>
+    <listitem>
+      <para>
+        <emphasis role="bold">(Data) Node</emphasis>: An
+        <command>ndbd</command> process, which stores a
+        <firstterm>replica</firstterm> &mdash;that is, a copy of the
+        <firstterm>partition</firstterm> (see below) assigned to the
+        node group of which the node is a member.
+      </para>
+      
+      <para>
+        Each data node is usually located on a separate computer.
+        However, it is also possible to host multiple data nodes on a
+        single computer having more than one processor. In such cases,
+        it is feasible to run one instance of <command>ndbd</command>
+        per physical CPU. (Note that a processor with multiple cores is
+        still a single processor.)
+      </para>
+      
+      <para>
+        It is common for the terms <quote>node</quote> and <quote>data
+          node</quote> to be used interchangeably when referring to an
+        <command>ndbd</command> process; where mentioned, management
+        nodes (<command>ndb_mgmd</command> processes) and SQL nodes
+        (<command>mysqld</command> processes) are specified as such in
+        this discussion.
+      </para>
+    </listitem>
+    
+    <listitem>
+      <para>
+        <emphasis role="bold">Node Group</emphasis>: A node group
+        consists of one or more nodes, and stores a partition, or set of
+        <firstterm>replicas</firstterm> (see next item). 
+      </para>
+      
+      <para>
+        <emphasis role="bold">Note</emphasis>: Currently, all node
+        groups in a cluster must have the same number of nodes.
+      </para>
+    </listitem>
+    
+    <listitem>
+      <para>
+        <emphasis role="bold">Partition</emphasis>: This is a portion of
+        the data stored by the cluster. There are as many cluster
+        partitions as node groups participating in the cluster, and each
+        node group is responible for keeping at least one copy of the
+        partition assigned to it (that, at least one replica) available
+        to the cluster.
+      </para>
+    </listitem>
+    
+    <listitem>
+      <para>
+        <emphasis role="bold">Replica</emphasis>: This is a copy of a
+        cluster partition. Each node in a node group stores a replica.
+        Also sometimes known as a <firstterm>partition
+          replica</firstterm>.
+      </para>
+    </listitem>
+  </itemizedlist>
+  
+  <para>
+    The following diagram illustrates a MySQL Cluster with four data
+    nodes, arranged in two node groups of two nodes each. Note that no
+    nodes other than data nodes are shown here, although a working
+    cluster requires an <command>ndb_mgm</command> process for cluster
+    management and at least one SQL node in order to access the data
+    stored by the cluster.
+  </para>
+
+  <mediaobject>
+    <imageobject>
+      <imagedata fileref="images/replicas-groups-1-1.png" format="PNG"/>
+    </imageobject>
+    <textobject>
+      <phrase lang="en">A MySQL Cluster, with 2 node groups having 2
+        nodes each</phrase>
+    </textobject>
+  </mediaobject>
+  
+  <para>
+    The data stored by the cluster is divided into two partitions,
+    labeled <emphasis role="bold">A</emphasis> and 
+    <emphasis role="bold">B</emphasis> in the diagram. Each partition is
+    stored &mdash; in multiple copies &mdash; on a node group. The data
+    making up Partition <emphasis role="bold">A</emphasis> is stored on
+    Node <emphasis role="bold">A-1</emphasis>, and this data is
+    identical to that stored by Node 
+    <emphasis role="bold">A-2</emphasis>. The data stored by Nodes
+    <emphasis role="bold">B-1</emphasis> and 
+    <emphasis role="bold">B-2</emphasis> is also the same &mdash; these
+    two nodes store identical copies of the data making up Partition
+    <emphasis role="bold">B</emphasis>.
+  </para>
+  
+  <para>
+    What this means so far as the continued operation of a MySQL
+    Cluster is this: so long as each node group participating in the
+    cluster has at least one <quote>live</quote> node, the cluster has a
+    complete copy of all data and remains viable. This is illustrated in
+    the next diagram.
+  </para>
+  
+  <remark role="todo">
+    [js] Not a very good caption; think of a better one.
+  </remark>
+
+  <mediaobject>
+    <imageobject>
+      <imagedata fileref="images/replicas-groups-1-2.png" format="PNG"/>
+    </imageobject>
+    <textobject>
+      <phrase lang="en">Nodes required to keep a 2x2 cluster viable</phrase>
+    </textobject>
+  </mediaobject>
+  
+  <para>
+    In this example, where the cluster consists of two node groups of
+    two nodes each, any combination of at least one node in Node Group
+    <emphasis role="bold">A</emphasis> and at least one node in Node
+    Group <emphasis role="bold">B</emphasis> is sufficient to keep the
+    cluster <quote>alive</quote> (indicated by arrows in the diagram).
+    However, if both nodes from either node group fail, the remaining
+    two nodes are not sufficient (shown by arrows marked out with an
+    <emphasis role="bold">X</emphasis>); in either case, the cluster has    
+    lost an entire partition and so can no longer provide access to a
+    complete set of all cluster data.
+  </para>
+      
+      <remark role="todo">
+        [js] Add discussion of application of the above to hosts running
+        multiple CPUs.
+      </remark>
+      
+      <remark role="todo">
+        [js] Add description of memory requirements based on Hartmut's
+        example scripts.
+      </remark>
+    </section>
+    
+    
   </section>
 
   <section id="multi-computer">

Modified: trunk/refman-common/titles.en.ent
===================================================================
--- trunk/refman-common/titles.en.ent	2006-01-15 04:58:40 UTC (rev 840)
+++ trunk/refman-common/titles.en.ent	2006-01-15 05:24:34 UTC (rev 841)
@@ -820,6 +820,7 @@
 <!ENTITY title-mysql-cluster-news-5-0-5 "Changes in MySQL Cluster-5.0.5 (Not released)">
 <!ENTITY title-mysql-cluster-news-5-0-6 "Changes in MySQL Cluster-5.0.6 (26 May 2005)">
 <!ENTITY title-mysql-cluster-news-5-0-7 "Changes in MySQL Cluster-5.0.7 (Not yet released)">
+<!ENTITY title-mysql-cluster-nodes-groups "MySQL Cluster Nodes, Node Groups, Replicas, and Partitions">
 <!ENTITY title-mysql-cluster-overview "MySQL Cluster Overview">
 <!ENTITY title-mysql-cluster-process-management "Process Management in MySQL Cluster">
 <!ENTITY title-mysql-cluster-quick "Quick Test Setup of MySQL Cluster">

Thread
svn commit - mysqldoc@docsrva: r841 - in trunk: refman-4.1 refman-5.0 refman-5.1 refman-commonjon15 Jan