Bug #54115 Cluster replication conflict resolution docs confuse me
Submitted: 31 May 2010 18:49 Modified: 21 Sep 2010 9:14
Reporter: Mark Callaghan Email Updates:
Status: Closed Impact on me:
None 
Category:MySQL Server: Documentation Severity:S3 (Non-critical)
Version:5.1 OS:Any
Assigned to: Jon Stephens CPU Architecture:Any
Tags: cluster, Docs, replication
Triage: Needs Triage: D3 (Medium)

[31 May 2010 18:49] Mark Callaghan
Description:
This section confuses me. The basic problem is that while it describes the options that must be set, it wanders a bit before discussing the values that should be used for these options.

http://dev.mysql.com/doc/refman/5.1/en/mysql-cluster-replication-conflict-resolution.html

I think that --ndb-log-updated-only should be OFF. That isn't clear from this text.
>>>
Requirements.   Preparations for conflict resolution must be made on both the master and the slave:

    * On the master writing the binlogs, you must determine which columns are sent (all columns or only those that have been updated). This is done for the MySQL Server as a whole by applying the mysqld startup option -–ndb-log-updated-only (described later in this section) or on a per-table basis by entries in the mysql.ndb_replication table. 
>>>

This text should have a link to describe these tables.
>>>
On the slave, you must determine which type of conflict resolution to apply (“latest timestamp wins”, “same timestamp wins”, or none). This is done using the mysql.ndb_replication  system table, on a per-table basis. 
>>>

This line has no context. The text that precedes and follows it is unrelated to it.
>>>
If only some but not all columns are sent, then the master and slave can diverge.
>>>

This is a requirement, not a note:
>>>
Note

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 should be INT (INTEGER) or BIGINT. This column should be UNSIGNED and NOT NULL.
>>>

This doesn't describe what the option does nor does it mention the value required to support conflict resolution:
>>>
Master column control.   We can see update operations in terms of “before” and “after” images—that is, the states of the table before and after the update is applied. Normally, when updating a table with a primary key, the “before” image is not of great interest; however, when we need to determine on a per-update basis whether or not to use the updated values on a replication slave, we need to make sure that both images are written to the master's binary log. This is done with the --ndb-log-update-as-write option for mysqld, as described later in this section. 
>>>

And then there is more text on an option without specifying which value I need to use:
>>>
For purposes of conflict resolution, there are two basic methods of logging rows, as determined by the setting of the --ndb-log-updated-only option for mysqld:

    *

      Log complete rows
    *

      Log only column data that has been updated—that is, column data whose value has been set, regardless of whether or not this value was actually changed. This is the default behavior.

It is more efficient to log updated columns only; however, if you need to log full rows, you can do so by setting --ndb-log-updated-only to 0 or OFF. 
>>>

This section tells me that I must set --ndb-log-update-as-write=OFF. But the description of the option is of no help -- "updates are updates and not writes". Note that the MySQL handler unfortunately uses 'write' for 'insert'. Anyone not aware of that will reasonably assume that insert, update and delete are all writes.
>>>
Either of these logging methods can be configured to be done with or without the “before” image as determined by the setting of another MySQL Server option --ndb-log-update-as-write. Because conflict resolution is done in the MySQL Server's update handler, it is necessary to control logging on the master such that updates are updates and not writes; that is, such that updates are treated as changes in existing rows rather than the writing of new rows (even though these replace existing rows). This option is turned on by default; to turn it off, start the server with --ndb-log-update-as-write=0 or --ndb-log-update-as-write=OFF.
>>>

How to repeat:
read the docs
[20 Sep 2010 17:18] Jon Stephens
In progress:

http://lists.mysql.com/commits/118620
http://lists.mysql.com/commits/118623
[20 Sep 2010 17:52] Jon Stephens
Also http://lists.mysql.com/commits/118626

I'll take another look at Andrew's notes tomorrow and see what else I can do before closing this.
[21 Sep 2010 9:14] Jon Stephens
Thank you for your bug report. This issue has been addressed in the documentation. The updated documentation will appear on our website shortly, and will be included in the next release of the relevant products.