octoleo/gh-ost
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
3be76cd0ff
gh-ost/doc/requirements-and-limitations.md

3.7 KiB
Raw Blame History

Requirements and limitations

Requirements

  • You will need to have one server serving Row Based Replication (RBR) format binary logs. Right now FULL row image is supported. MINIMAL to be supported in the near future. gh-ost prefers to work with replicas. You may still have your master configured with Statement Based Replication (SBR).

  • If you are using a replica, the table must have an identical schema between the master and replica.

  • gh-ost requires an account with these privileges:

    • ALTER, CREATE, DELETE, DROP, INDEX, INSERT, LOCK TABLES, SELECT, TRIGGER, UPDATE on the database (schema) where your migrated table is, or of course on *.*
    • either:
      • SUPER, REPLICATION SLAVE on *.*, or:
      • REPLICATION CLIENT, REPLICATION SLAVE on *.*

The SUPER privilege is required for STOP SLAVE, START SLAVE operations. These are used on:

  • Switching your binlog_format to ROW, in the case where it is not ROW and you explicitly specified --switch-to-rbr

    • If your replication is already in RBR (binlog_format=ROW) you can specify --assume-rbr to avoid the STOP SLAVE/START SLAVE operations, hence no need for SUPER.

  • Running --test-on-replica: before the cut-over phase, gh-ost stops replication so that you can compare the two tables and satisfy that the migration is sound.

Limitations

  • Foreign keys not supported. They may be supported in the future, to some extent.

  • Triggers are not supported. They may be supported in the future.

  • MySQL 5.7 generated columns are not supported. They may be supported in the future.

  • MySQL 5.7 JSON columns are not supported. They are likely to be supported shortly.

  • The two before & after tables must share some UNIQUE KEY. Such key would be used by gh-ost to iterate the table.

    • As an example, if your table has a single UNIQUE KEY and no PRIMARY KEY, and you wish to replace it with a PRIMARY KEY, you will need two migrations: one to add the PRIMARY KEY (this migration will use the existing UNIQUE KEY), another to drop the now redundant UNIQUE KEY (this migration will use the PRIMARY KEY).

  • The chosen migration key must not include columns with NULL values.

    • gh-ost will do its best to pick a migration key with non-nullable columns. It will by default refuse a migration where the only possible UNIQUE KEY includes nullable-columns. You may override this refusal via --allow-nullable-unique-key but you must be sure there are no actual NULL values in those columns. Such NULL values would cause a data integrity problem and potentially a corrupted migration.

  • It is not allowed to migrate a table where another table exists with same name and different upper/lower case.

    • For example, you may not migrate MyTable if another table called MYtable exists in the same schema.

  • Amazon RDS and Google Cloud SQL are currently not supported

  • Multisource is not supported when migrating via replica. It should work (but never tested) when connecting directly to master (--allow-on-master)

  • Master-master setup is only supported in active-passive setup. Active-active (where table is being written to on both masters concurrently) is unsupported. It may be supported in the future.

  • If you have en enum field as part of your migration key (typically the PRIMARY KEY), migration performance will be degraded and potentially bad. Read more

  • Migrating a FEDERATED table is unsupported and is irrelevant to the problem gh-ost tackles.