From: jon Date: October 18 2007 10:18am Subject: svn commit - mysqldoc@docsrva: r8161 - in trunk: refman-5.1 refman-5.2 List-Archive: http://lists.mysql.com/commits/35821 Message-Id: <200710181018.l9IAImtH005853@docsrva.mysql.com> Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Author: jstephens Date: 2007-10-18 12:18:41 +0200 (Thu, 18 Oct 2007) New Revision: 8161 Log: A few more minor corrections; propagated recent additions to 5.2 version Modified: trunk/refman-5.1/mysql-cluster-replication.xml trunk/refman-5.2/mysql-cluster-replication.xml Modified: trunk/refman-5.1/mysql-cluster-replication.xml =================================================================== --- trunk/refman-5.1/mysql-cluster-replication.xml 2007-10-18 09:50:33 UTC (rev 8160) +++ trunk/refman-5.1/mysql-cluster-replication.xml 2007-10-18 10:18:41 UTC (rev 8161) Changed blocks: 1, Lines Added: 4, Lines Deleted: 3; 1162 bytes @@ -2406,9 +2406,10 @@ since the last time that mysqld was started. Beginning with MySQL-5.1.22-ndb-6.3.4, the number of times that a row was not applied as the result of same timestamp - wins conflict resolution a given mysqld - since the last time it was restarted is given by the global status - variable Ndb_conflict_fn_old. In addition to + wins conflict resolution on a given + mysqld since the last time it was restarted is + given by the global status variable + Ndb_conflict_fn_old. In addition to incrementing Ndb_conflict_fn_old, the primary key of the row that was not used is inserted into an exceptions table, as explained later in Modified: trunk/refman-5.2/mysql-cluster-replication.xml =================================================================== --- trunk/refman-5.2/mysql-cluster-replication.xml 2007-10-18 09:50:33 UTC (rev 8160) +++ trunk/refman-5.2/mysql-cluster-replication.xml 2007-10-18 10:18:41 UTC (rev 8161) Changed blocks: 18, Lines Added: 301, Lines Deleted: 126; 22117 bytes @@ -12,13 +12,13 @@ MySQL Cluster replication - + MySQL Cluster replication replication in MySQL Cluster - + MySQL Cluster replication @@ -27,12 +27,12 @@ asynchronous replication - + MySQL Cluster replication replication, asynchronous - + MySQL Cluster replication @@ -294,17 +294,6 @@ - (If high availability is a requirement for the slave server or - cluster, then it is still advisable to set up multiple - replication lines, to monitor the master - mysqld on the primary replication line, and - to fail over to a secondary line if and as necessary. For - information about implementing this type of setup, see - , and - .) - - - Beginning with MySQL 5.1.18, the master issues a gap event when connecting to the cluster. When the slave encounters a gap in the replication log, it stops @@ -404,94 +393,76 @@ - + In this case, different SQL nodes in each cluster are used as + replication masters and slaves. However, you must + not start any of the SQL nodes using + (see the + description of + this option for more information). This type of + circular replication scheme for MySQL Cluster, in which the + line of replication (again indicated by the red arrows in the + diagram) is discontinuous, should be possible, but it should + be noted that it has not yet been thoroughly tested and must + therefore still be considered experimental. + @@ -1298,10 +1269,6 @@ . - - batched updates (MySQL Cluster Replication) @@ -1371,10 +1338,6 @@ - -
@@ -2013,7 +1976,7 @@ reset-slave.pl - + MySQL Cluster replication @@ -2211,10 +2174,6 @@ in MySQL Cluster Replication - - When using a replication setup involving multiple masters, it is possible that different masters may try to update the same row on @@ -2222,13 +2181,26 @@ Cluster Replication provides a means of resolving such conflicts by allowing a user defined timestamp column to be used to determine whether or not an update to the row on a given - master should be applied on the slave. Generally speaking, if the - timestamp for a given row coming from the master is - higher than that on the slave, it is applied it; otherwise it is - not applied on the slave. + master should be applied on the slave. There are two ways in which + this column can be used, as explained in the next two paragraphs. + In the first method, if the timestamp for a given + row coming from the master is higher than that on the slave, it is + applied; otherwise it is not applied on the slave. This ensures + that, in the event of a conflict, the version of the row that was + most recently updated is the version that persists. + + + + In the second method for conflict resolution, the update is + applied only if the timestamp column is the same on + both the master and the slave. This ensures that updates are not + applied from the wrong master. + + + This replication scheme, also known as changed parameter only replication, is configurable on a per-table basis. @@ -2244,8 +2216,8 @@ On the slave, it must be determined which type of conflict - resolution to apply (none or latest timestamp - wins). + resolution to apply (latest timestamp wins, + same timestamp wins, or none). @@ -2260,8 +2232,8 @@ We refer to the column used for determining updates as a timestamp column, but the data type of this column is never TIMESTAMP; rather, its data - type can be either of INT SIGNED or - INT UNSIGNED. + type should be an integer type. This column can be either signed + or unsigned. @@ -2379,6 +2351,23 @@ + + The server status variable Ndb_conflict_fn_max + provides a count of the number of times that a row was not applied + on the current SQL node due to greatest timestamp + wins conflict resolution since the last time that + mysqld was started. The number of times that a + row was not applied as the result of same timestamp + wins conflict resolution on a given + mysqld since the last time it was restarted is + given by the global status variable + Ndb_conflict_fn_old. In addition to + incrementing Ndb_conflict_fn_old, the primary + key of the row that was not used is inserted into an + exceptions table, as explained later in + this section. + + conflict resolution enabling @@ -2404,7 +2393,7 @@ binlog_type INT UNSIGNED, conflict_fn VARBINARY(128), PRIMARY KEY USING HASH (db, table_name, server_id) -) ENGINE=NDB +) ENGINE=NDB PARTITION BY KEY(db,table_name); @@ -2531,11 +2520,39 @@ <literal>conflict_fn</literal> - The conflict resolution function to be applied. Currently - this function must be specified as either - NDB$MAX(column_name - or NULL (if conflict resolution is not - to be used). + The conflict resolution function to be applied. This + function must be specified as one of the following: + + + + + + NDB$MAX(column_name: + Indicates that greatest timestamp + wins conflict resolution is to be used. + + + + + + NDB$OLD(column_name: + An update is applied only if the value of + column_name is the same + on both the master and the slave. + + + + + + NULL: Indicates that conflict + resolution is not to be used for the corresponding + table + + + + + + . @@ -2544,6 +2561,76 @@ + + + Additional requirements for <quote>Same timestamp wins</quote> conflict + resolution + + + To use the NDB$OLD() conflict resolution + function, it is also necessary to create an exceptions table + corresponding to each NDB table for which + this type of conflict resolution is to be employed. The name of + this table is that of the table for which same timestamp + wins conflict resolution is to be applied, with the + string $EX appended. (For example, if the + name of the original table is mytable, the + name of the corresponding exception table name should be + mytable$EX.) This table is created as + follows: + + +CREATE TABLE original_table$EX ( + server_id SMALLINT UNSIGNED, + master_server_id SMALLINT UNSIGNED, + master_epoch BIGINT UNSIGNED, + count BIGINT UNSIGNED, + original_table_pk_columns, + [additional_columns,] + PRIMARY KEY(server_id, master_server_id, master_epoch, count) +) ENGINE=NDB; + + + The first four columns are required. Following these columns, + the columns making up the original table's primary key + should be copied in the order in which they are used to define + the primary key of the original table. + + + + The names of the first four columns and the columns matching + the original table's primary key columns are not + critical; however, we suggest for reasons of clarity and + consistency, that you use the names shown here for the + server_id, + master_server_id, + master_epoch, and + count columns, and that you use the same + names as in the original table for the columns matching + those in the original table's primary key. + + + + The first four columns should be some variety of + INT UNSIGNED. We suggest the types shown, + or larger ones, in order to ensure that they are large + enough to accommodate likely values. The data types for the + columns duplicating the primary key columns of the original + table should be the same as for (or larger than) the + original columns. + + + + Additional columns may optionally be defined following these + columns, but not before any of them. The exception table's + primary key must be defined as shown. The exception table must + use the NDB storage engine. An example of use + for NDB$OLD() and an exception table is given + later in this section. + + + + The mysql.ndb_replication table is read when @@ -2567,10 +2654,11 @@ - Example + <literal>NDB$MAX()</literal> example - Suppose you wish to enable conflict resolution on table + Suppose you wish to enable greatest timestamp + wins conflict resolution on table test.t1, using column mycol as the timestamp. This can be done using the following two steps: @@ -2579,18 +2667,19 @@ - On the master, perform this query: + On the master, perform this INSERT + statement: -INSERT INTO mysql.ndb_replication VALUES - ("test", "t1", 0, NULL, "NDB$MAX(mycol)"); +INSERT INTO mysql.ndb_replication + VALUES ('test', 't1', 0, NULL, 'NDB$MAX(mycol)'); Inserting a 0 into the server_id indicates that all SQL nodes accessing this table should - use the conflict resolution. If you want to use conflict + use conflict resolution. If you want to use conflict resolution on a specific mysqld only, use the actual server ID. @@ -2627,6 +2716,92 @@ + + + <literal>NDB$OLD()</literal> example + + + Suppose an NDB table such as the one defined + here is being replicated, and you wish to enable same + timestamp wins conflict resolution for updates to this + table: + + +CREATE TABLE test.t2 ( + a INT UNSIGNED NOT NULL, + b CHAR(25) NOT NULL, + columns, + mycol INT UNSIGNED NOT NULL, + columns, + PRIMARY KEY pk (a, b) +) ENGINE=NDB; + + + The following steps are required, in the order shown: + + + + + + First — and prior to creating + test.t2 — you must insert a row + into the mysql.ndb_replication table, + as shown here: + + +INSERT INTO mysql.ndb_replication + VALUES ('test', 't2', 0, NULL, 'NDB$OLD(mycol)'); + + + Possible values for the binlog_type + column are shown earlier in this section. The value + 'NDB$OLD(mycol)' should be inserted + into the conflict_fn column. + + + + + + Create an appropriate exceptions table for + test.t2. The table creation statement + shown here includes all required columns; any additional + columns must be declared following these columns, and + before the definition of the table's primary key. + + +CREATE TABLE test.t2$EX ( + server_id SMALLINT UNSIGNED, + master_server_id SMALLINT UNSIGNED, + master_epoch BIGINT UNSIGNED, + count BIGINT UNSIGNED, + a INT UNSIGNED NOT NULL, + b CHAR(25) NOT NULL, + [additional_columns,] + PRIMARY KEY(server_id, master_server_id, master_epoch, count) +) ENGINE=NDB; + + + + + + + Create the table test.t2 as shown + previously. + + + + + + These steps must be followed for every table for which you wish + to perform conflict resolution using + NDB$OLD(). For each such table, there must be + a corresponding row in mysql.ndb_replication, + and there must be an exceptions table in the same database as + the table being replicated. + + + +