support for --assume-master-host, master-master/tungsten

Author: Shlomi Noach

doc/cheatsheet.md

@@ -124,3 +124,30 @@ password=123456
 ```
 
 You may then remove `--user=gh-ost --password=123456` and specify `--conf=/path/to/config/file.cnf`
+
+
+### Special configurations
+
+#### Master-master
+
+Master-master setups are supported, but at this time only active-passive. An active-active setup, where both masters write to the migrated table, is not supported at this stage. `gh-ost` requires you to acknowledge master-master via:
+
+```
+gh-ost --allow-master-master
+```
+
+`gh-ost` will pick one of the masters to work on. You may additionally force `gh-ost` to pick a particular master of your choice:
+
+```
+gh-ost --allow-master-master --assume-master-host=a.specific.master.com
+```
+
+#### Tungsten
+
+Topologies using _tungsten replicator_ are peculiar in that the participating servers are not actually aware they are replicating. The _tungsten replicator_ looks just like another app issuing queries on those hosts. `gh-ost` is unable to identify that a server participates in a _tungsten_ topology.
+
+If you choose to migrate directly on master (see above), there's nothing special you need to do. If you choose to migrate via replica, then you must supply the identity of the master, and indicate this is a tungsten setup, as follows:
+
+```
+gh-ost --tungsten --assume-master-host=the.topology.master.com
+```

doc/command-line-flags.md

@@ -16,6 +16,13 @@ When your migration issues a column rename (`change column old_name new_name ...
 
 If you think `gh-ost` is mistaken and that there's actually no _rename_ involved, you may pass `--skip-renamed-columns` instead. This will cause `gh-ost` to disassociate the column values; data will not be copied between those columns.
 
+### assume-master-host
+
+`gh-ost` infers the identity of the master server by crawling up the replication topology. You may explicitly tell `gh-ost` the identity of the master host via `--assume-master-host=the.master.com`. This is useful in:
+
+- master-master topologies (together with `--allow-master-master`), where `gh-ost` can arbitrarily pick one of the co-master and you prefer that it picks a specific one
+- _tungsten replicator_ topologies (together with `--tungsten`), where `gh-ost` is unable to crawl and detect the master
+
 ### assume-rbr
 
 If you happen to _know_ your servers use RBR (Row Based Replication, i.e. `binlog_format=ROW`), you may specify `--assume-rbr`. This skips a verification step where `gh-ost` would issue a `STOP SLAVE; START SLAVE`.

go/base/context.go

@@ -69,6 +69,7 @@ type MigrationContext struct {
 	NullableUniqueKeyAllowed bool
 	ApproveRenamedColumns    bool
 	SkipRenamedColumns       bool
+	IsTungsten               bool
 
 	config      ContextConfig
 	configMutex *sync.Mutex
@@ -109,7 +110,7 @@ type MigrationContext struct {
 	CutOverType                  CutOver
 
 	Hostname                               string
-	OverrideApplierHostname                string
+	AssumeMasterHostname                   string
 	TableEngine                            string
 	RowsEstimate                           int64
 	RowsDeltaEstimate                      int64

go/cmd/gh-ost/main.go

@@ -44,7 +44,7 @@ func main() {
 	migrationContext := base.GetMigrationContext()
 
 	flag.StringVar(&migrationContext.InspectorConnectionConfig.Key.Hostname, "host", "127.0.0.1", "MySQL hostname (preferably a replica, not the master)")
-	flag.StringVar(&migrationContext.OverrideApplierHostname, "override-applier-host", "", "(with -allow-master-master), optionally specify which host should have changes applied to it")
+	flag.StringVar(&migrationContext.AssumeMasterHostname, "assume-master-host", "", "(optional) explicitly tell gh-ost the identity of the master. Format: some.host.com[:port] This is useful in master-master setups where you wish to pick an explicit master, or in a tungsten-replicator where gh-ost is unabel to determine the master")
 	flag.IntVar(&migrationContext.InspectorConnectionConfig.Key.Port, "port", 3306, "MySQL port (preferably a replica, not the master)")
 	flag.StringVar(&migrationContext.CliUser, "user", "", "MySQL user")
 	flag.StringVar(&migrationContext.CliPassword, "password", "", "MySQL password")
@@ -60,6 +60,7 @@ func main() {
 	flag.BoolVar(&migrationContext.NullableUniqueKeyAllowed, "allow-nullable-unique-key", false, "allow gh-ost to migrate based on a unique key with nullable columns. As long as no NULL values exist, this should be OK. If NULL values exist in chosen key, data may be corrupted. Use at your own risk!")
 	flag.BoolVar(&migrationContext.ApproveRenamedColumns, "approve-renamed-columns", false, "in case your `ALTER` statement renames columns, gh-ost will note that and offer its interpretation of the rename. By default gh-ost does not proceed to execute. This flag approves that gh-ost's interpretation si correct")
 	flag.BoolVar(&migrationContext.SkipRenamedColumns, "skip-renamed-columns", false, "in case your `ALTER` statement renames columns, gh-ost will note that and offer its interpretation of the rename. By default gh-ost does not proceed to execute. This flag tells gh-ost to skip the renamed columns, i.e. to treat what gh-ost thinks are renamed columns as unrelated columns. NOTE: you may lose column data")
+	flag.BoolVar(&migrationContext.IsTungsten, "tungsten", false, "explicitly let gh-ost know that you are running on a tungsten-replication based topology (you are likely to also provide --assume-master-host)")
 
 	executeFlag := flag.Bool("execute", false, "actually execute the alter & migrate the table. Default is noop: do some tests and exit")
 	flag.BoolVar(&migrationContext.TestOnReplica, "test-on-replica", false, "Have the migration run on a replica, not on the master. At the end of migration replication is stopped, and tables are swapped and immediately swap-revert. Replication remains stopped and you can compare the two tables for building trust")
@@ -162,8 +163,8 @@ func main() {
 		}
 		log.Warning("--test-on-replica-skip-replica-stop enabled. We will not stop replication before cut-over. Ensure you have a plugin that does this.")
 	}
-	if migrationContext.OverrideApplierHostname != "" && !migrationContext.AllowedMasterMaster {
-		log.Fatalf("--override-applier-host is only for use with --allow-master-amster")
+	if migrationContext.AssumeMasterHostname != "" && !migrationContext.AllowedMasterMaster && !migrationContext.IsTungsten {
+		log.Fatalf("--assume-master-host requires either --allow-master-master or --tungsten")
 	}
 
 	switch *cutOver {

go/logic/migrator.go

@@ -20,6 +20,7 @@ import (
 
 	"github.com/github/gh-ost/go/base"
 	"github.com/github/gh-ost/go/binlog"
+	"github.com/github/gh-ost/go/mysql"
 	"github.com/github/gh-ost/go/sql"
 
 	"github.com/outbrain/golib/log"
@@ -761,8 +762,12 @@ func (this *Migrator) initiateInspector() (err error) {
 	if this.migrationContext.ApplierConnectionConfig, err = this.inspector.getMasterConnectionConfig(); err != nil {
 		return err
 	}
-	if this.migrationContext.OverrideApplierHostname != "" {
-		this.migrationContext.ApplierConnectionConfig.Key.Hostname = this.migrationContext.OverrideApplierHostname
+	if this.migrationContext.AssumeMasterHostname != "" {
+		if key, err := mysql.ParseRawInstanceKeyLoose(this.migrationContext.AssumeMasterHostname); err != nil {
+			return err
+		} else {
+			this.migrationContext.ApplierConnectionConfig.Key = *key
+		}
 	}
 	if this.migrationContext.TestOnReplica || this.migrationContext.MigrateOnReplica {
 		if this.migrationContext.InspectorIsAlsoApplier() {