WL#1697: Multi-source replication

REQUIREMENTS
------------
Possible to replicate from multiple MySQL Servers 
to a single MySQL server (e.g. A->C, B->C).

IMPLEMENTATION
--------------
1. Add threads in destination server.  One receive thread (io) 
   and one apply thread (sql) for each connected master.
   Add mi and rli structs for each connected master

2. Add new file names for each connected master.

3. Add/modify replication commands 
   - Define syntaxes (backward compatible) to affect one master or 
     all master in one mysqld.
   - SHOW SLAVE STATUS will print one line for each 
     (directly connected) master; there should be a way to see 
     the info for only one master

SOURCE CODE
-----------
There are now three implementations of this feature:
1. Lars
2. He
3. Daniel

   (Subject: bk commit - 4.1 tree (gbichot:1.2142) BUG#8325): FYI Monty
   asked that in 5.1, when we have multimaster, there should be one
   counter of transaction retries per subslave, displayed on each line of
   SHOW SLAVE STATUS, and the counter I added below in SHOW STATUS would
   be a global counter (sum over all subslaves in this slave). That would
   be slightly redundant, but would still have the advantage that with
   the global counter you get info on even the subslaves which don't
   exist anymore (Monty's argument). )

High Level Architecture
WL#1697: Multi-Master Replication
Lars Thalmann, Rev 3, 2004-11-25


CONTENTS
--------
1. Filenames
2. Commands
3. Startup options
4. Future enhancements

1. FILENAMES
------------
In the below C denotes a "channel", i.e. a specific replication
(i.e. one-way binlog transfer) from a master to a slave.  C can be any
string of characters, e.g. the hostname of the master.  The channel 
namespace is only used within a slave.

Channel names should be composed of only the following characters: 
[A-Za-z0-9_].  Characters A-Z are automatically translated to a-z
when used in file names.

A MASTER variable is introduced.  The default value of this variable
is "default".  The upgrade problem (files have different names when
WL#1697 is implemented) can be solved in two ways:

- Remove file "master.info" and replace with a set of files
  master.C.info.
- Remove file "relay-log.info" and replace with a set of files
  "relay-log.C.info",
- Remove set of files "HOSTNAME-relay-bin.NNNNNN" and replace with set
  of set of files "HOSTNAME-relay-bin.C.NNNNNN" 
- Remove file "HOSTNAME-relay-bin.index" and replace with set of files
  "HOSTNAME-relay-bin.C.index"

1. The special "default" channel is never used in the file names.
   Instead the old file names are used, e.g.  master.info,
   HOSTNAME-relay-bin.NNNNNN etc.  This solution requires special
   cases in the code in several places.

2. A special routine is added to slave.cc:init_slave() that checks if
   there are any files with the old format.  If so, then it changes
   the filenames to master.default.info, 
   HOSTNAME-relay-bin.default.NNNNNN
   etc.

Solution 2 is being suggested.  (Lars, Guilhem are ok with it.
Downgrade scenario to be described in the manual.)
Also note relationship with WL#1401.

2. COMMANDS
-----------
The following commands changes are being made.

- A new command is introduced:
  SET MASTER=channel
  Default value of MASTER variable is 'default'.  
  In the text below, 'MASTER channel' refers to the 
  value of this variable.  

  Note that this command does NOT create the channel.  
  The CHANGE MASTER statement creates the channel.  
  If the related channel does not exist in the 
  commands below, then an error is given.

  Example:
  Ok:     SET MASTER=new_channel;
          CHANGE MASTER TO MASTER_HOST=... ; # creates new_channel

  Not ok: SET MASTER=new_channel2;
          START SLAVE;                       # new_channel2 does not exist

- CHANGE MASTER TO master_def [, master_def] ...
  is changed to:
  CHANGE MASTER channel TO master_def [, master_def] ...
  If channel is omitted, MASTER channel is assumed.

- LOAD DATA FROM MASTER
  is changed to:
  LOAD DATA FROM MASTER channel
  If channel is omitted, MASTER channel is assumed.

- LOAD TABLE tbl_name FROM MASTER
  is changed to
  LOAD TABLE tbl_name FROM MASTER channel
  If channel is omitted, MASTER channel is assumed.

- SELECT MASTER_POS_WAIT('master_log_file', 
  master_log_pos, timeout) is changed to
  SELECT MASTER_POS_WAIT(channel, 'master_log_file', 
  master_log_pos, timeout)
  
- RESET SLAVE
  means that all channels are reset.

- Two new commands are introduced,
  RESET SLAVE FOR MASTER channel
  to reset the files regarding a single master and 
  RESET SLAVE FOR ALL MASTERS
  to reset the slave completely.

- SET GLOBAL SQL_SLAVE_SKIP_COUNTER = n
  This is changed into a structured system variable. 
  If no instance name (for a channel) is specified,
  then the MASTER channel is affected.

- SHOW SLAVE STATUS 
  is changed to 
  SHOW SLAVE STATUS [FOR MASTER channel]
  If channel is not specified, then all channels are shown.  
  The first column of the output names the channel.
  SHOW SLAVE STATUS FOR ALL MASTERS
  is introduced to show complete slave status.

- START SLAVE [thread_type [, thread_type] ... ]
  is changed to
  START SLAVE [thread_type [, thread_type] ... ] 
    [FOR MASTER channel]
  If channel is not specified, then MASTER channel is 
  started.
  START SLAVE FOR ALL MASTERS 
  starts slave replication of all defined masters.

- START SLAVE [SQL_THREAD] UNTIL
    MASTER_LOG_FILE = 'log_name', MASTER_LOG_POS = log_pos
  is changed to
  START SLAVE [SQL_THREAD] UNTIL
    MASTER_LOG_FILE = 'log_name', MASTER_LOG_POS = log_pos
    [FOR MASTER channel]
  If channel is not specified, then MASTER channel is 
  started.

- START SLAVE [SQL_THREAD] UNTIL
    RELAY_LOG_FILE = 'log_name', RELAY_LOG_POS = log_pos
  is changed to 
  START SLAVE [SQL_THREAD] UNTIL
    RELAY_LOG_FILE = 'log_name', RELAY_LOG_POS = log_pos
    [FOR MASTER channel]
  If channel is not specified, then MASTER channel is 
  started.

- STOP SLAVE [thread_type [, thread_type] ... ]
  is changed to
  STOP SLAVE [thread_type [, thread_type] ... ]
    [FOR MASTER channel]
  If channel is not specified, then MASTER channel is 
  stopped.
  STOP SLAVE [thread_type [, thread_type] ... ] FOR ALL MASTERS
  stops the slave completely.

3. STARTUP OPTIONS
------------------
A. The mysqld.cc:my_long_options[] options below are being changed.

   The following options will apply to all channels.  Comments:
   1. The --log-slave-updates is saved in each thd->options as value
      OPTION_BIN_LOG, so it would not be that hard to make it into a
      structured system variable and keep different channels behave
      differently.  Is it needed to have this as a structured system
      variable?)
   
   OPTION                               STORAGE (STRUCTURED)
   --log-slave-updates                  thd->options | OPTION_BIN_LOG
   --relay-log-purge={0|1}              mysqld.cc:relay_log_purge
   --relay-log-space-limit=#            mysqld.cc:relay_log_space_limit
   --skip-slave-start                   mysqld.cc:skip_slave_start
   --slave_compressed_protocol={0|1}    mysqld.cc:opt_slave_compressed_protocol
   --slave-load-tmpdir=file_name        slave.cc:slave_load_tmpdir
   --slave-net-timeout=seconds          mysqld.cc:slave_net_timeout
   --slave-skip-errors=err1,err2,...    N/A
   --slave-skip-errors=all              N/A
   
   OPTION                               STORAGE (GLOBAL)
   --log-warnings                       global_system_variables.log_warnings
   --max-relay-log-size=#               mysqld.cc:max_relay_log_bin
   --read-only                          mysqld.cc:opt_readonly
   --report-host=host                   mysqld.cc:report_host (Old code)
   --report-port=port_number            mysqld.cc:report_port (Old code)

B. The following 13 options are changed into structured system variables.
   If no instance name is given (naming a channel), then only the default
   channel is affected.  If an instance name is naming a channel, then
   only that named channel is affected.
   
   OPTION                                   STORAGE
   --master-connect-retry=seconds           mi->connect_retry
   --master-host=host                       mi->host
   --master-info-file=file_name             mi->info_file
   --master-password=password               mi->password
   --master-port=port_number                mi->port
   --master-ssl                             mi->ssl
   --master-ssl-ca=file_name                mi->ssl_ca
   --master-ssl-capath=directory_name       mi->ssl_capath
   --master-ssl-cert=file_name              mi->ssl_cert
   --master-ssl-cipher=cipher_list          mi->ssl_cipher
   --master-ssl-key=file_name               mi->ssl_key
   --master-user=username                   mi->user
   --master-retry-count  (Not documented?)  mi->retry_count
    
C. The following variables should be changed into structured options.
   All these options generate new fields in MASTER_INFO.  Not specifying
   instance means that the option applies to default channel only.

   --replicate-do-db=db_name
   --replicate-do-table=db_name.tbl_name
   --replicate-ignore-db=db_name
   --replicate-ignore-table=db_name.tbl_name
   --replicate-wild-do-table=db_name.tbl_name
   --replicate-wild-do-table=my\\_own\\%db.
   --replicate-wild-ignore-table=db_name.tbl_name
   --replicate-rewrite-db=from_name->to_name
   --replicate-same-server-id
   
D. The following options are changed into structured system variables.
   If no instance name is given (naming a channel), then the default
   channel is affected.  If an instance name is naming a channel, then
   that channel is affected.
   
   OPTION                                   STORAGE
   --relay-log=file_name                    rli->relay_log->log_file_name
   --relay-log-index=file_name              rli->relay_log->index_file
   --relay-log-info-file=file_name          rli->info_file

4. FUTURE ENHANCEMENTS
----------------------
These features will not be implemented as part of this 
worklog task, but could be implemented in the future.

A. Renaming of channel
   I can imagine users having upgraded, so having a channel named
   "default", and wishing to call it something else. The manual method is
   STOP SLAVE;
   manually rename the .info and *relay* files
   START SLAVE;
   but I guess this will not be enough for some people.
   RENAME MASTER old_channel TO new_channel ?
   which would do the above steps?