Author: jstephens
Date: 2006-08-06 15:06:57 +0200 (Sun, 06 Aug 2006)
New Revision: 2965
Log:
Documenting use of multiple Ndb_cluster_connection and Ndb objects to
access multiple clusters in a single app. (E.g. for application-level
partitioning of data amongst clusters.)
Modified:
trunk/ndbapi/ndb-classes.xml
Modified: trunk/ndbapi/ndb-classes.xml
===================================================================
--- trunk/ndbapi/ndb-classes.xml 2006-08-06 11:04:16 UTC (rev 2964)
+++ trunk/ndbapi/ndb-classes.xml 2006-08-06 13:06:57 UTC (rev 2965)
Changed blocks: 4, Lines Added: 130, Lines Deleted: 3; 6450 bytes
@@ -112,6 +112,15 @@
</para>
</note>
+ <para>
+ It is also possible to use multiple <literal>Ndb</literal> objects
+ to perform operations on different clusters in a single
+ application. See the
+ <link linkend="ndb-application-level-partitioning">Note
+ onApplication-Level Partitioning</link> for conditions and
+ restrictions applying to such usage.
+ </para>
+
<formalpara>
<title>Public Methods</title>
@@ -1513,9 +1522,9 @@
<title>Description</title>
<para>
- Any NDB application program should begin with the creation of a
+ An NDB application program should begin with the creation of a
single <literal>Ndb_cluster_connection</literal> object, and
- should make use of one and only one
+ typically makes use of a single
<literal>Ndb_cluster_connection</literal>. The application
connects to a cluster management server when this object's
<literal>connect()</literal> method is called. By using the
@@ -1525,6 +1534,124 @@
</formalpara>
+ <note id="ndb-application-level-partitioning">
+ <indexterm>
+ <primary>application-level partitioning</primary>
+ </indexterm>
+
+ <indexterm>
+ <primary>multiple clusters</primary>
+ </indexterm>
+
+ <para>
+ There is no restriction against instantiating multiple
+ <literal>Ndb_cluster_connection</literal> objects representing
+ connections to different management servers in a single
+ application, nor against using these for creating multiple
+ instances of the <literal>Ndb</literal> class. Such
+ <literal>Ndb_cluster_connection</literal> objects (and the
+ <literal>Ndb</literal> instances based on them) are not required
+ even to connect to the same cluster.
+ </para>
+
+ <para>
+ For example, it is entirely possible to perform
+ <firstterm>application-level partitioning</firstterm> of data in
+ such a manner that data meeting one set of criteria are
+ <quote>handed off</quote> to one cluster via an
+ <literal>Ndb</literal> object that makes use of an
+ <literal>Ndb_cluster_connection</literal> object representing a
+ connection to that cluster, while data not meeting those
+ criteria (or perhaps a different set of criteria) can be sent to
+ a different cluster through a different instance of Ndb that
+ makes use of an <literal>Ndb_cluster_connection</literal>
+ <quote>pointing</quote> to the second cluster.
+ </para>
+
+ <para>
+ It is possible to extend this scenario to develop a single
+ application that accesses an arbitrary number of clusters.
+ However, in doing so, the following conditions and requirements
+ must be kept in mind:
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ A cluster management server (<command>ndb_mgmd</command>)
+ can connect to one and only one cluster without being
+ restarted and reconfigured, as it must read the data
+ telling it which data nodes make up the cluster from a
+ configuration file (<filename>config.ini</filename>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ An <literal>Ndb_cluster_connection</literal> object
+ <quote>belongs</quote> to a single management server whose
+ hostname or IP address is used in instantiating this
+ object (passed as the
+ <replaceable>connectstring</replaceable> argument to its
+ constructor); once the object is created, it cannot be
+ used to initiate a connection to a different management
+ server.
+ </para>
+
+ <para>
+ (See
+ <xref linkend="class-ndb-cluster-connection-constructor"/>.)
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ An <literal>Ndb</literal> object making use of this
+ connection (<literal>Ndb_cluster_connection</literal>)
+ cannot be re-used to connect to a different cluster
+ management server (and thus to a different collection of
+ data nodes making up a cluster). Any given instance of
+ <literal>Ndb</literal> is bound to a specific
+ <literal>Ndb_cluster_connection</literal> when created,
+ and that <literal>Ndb_cluster_connection</literal> is in
+ turn bound to a single and unique management server when
+ it is instantiated.
+ </para>
+
+ <para>
+ (See <xref linkend="class-ndb-constructor"/>.)
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The bindings described above persist for the lifetimes of
+ the <literal>Ndb</literal> and
+ <literal>Ndb_cluster_connection</literal> objects in
+ question.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ Therefore, it is imperative in designing and implementing any
+ application that accesses multiple clusters in a single session,
+ that a separate set of <literal>Ndb_cluster_connection</literal>
+ and <literal>Ndb</literal> objects be instantiated for
+ connecting to each cluster management server, and that no
+ confusion arises as to which of these is used to access which
+ MySQL Cluster.
+ </para>
+
+ <para>
+ It is also important to keep in mind that no direct
+ <quote>sharing</quote> of data or data nodes between different
+ clusters is possible. A data node can belong to one and only one
+ cluster, and any movement of data between clusters must be
+ accomplished on the application level.
+ </para>
+ </note>
+
<formalpara>
<title>Public Methods</title>
@@ -1579,7 +1706,7 @@
<para>
This diagram shows all the available methods of the
- <literal>...</literal> class:
+ <literal>Ndb_cluster_connection</literal> class:
<mediaobject>
<imageobject>
| Thread |
|---|
| • svn commit - mysqldoc@docsrva: r2965 - trunk/ndbapi | jstephens | 6 Aug |
