diff --git a/doc/command-line-flags.md b/doc/command-line-flags.md index a2135a9..3ede1ff 100644 --- a/doc/command-line-flags.md +++ b/doc/command-line-flags.md @@ -16,6 +16,12 @@ 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-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`. +Skipping this step means `gh-ost` would not need the `SUPER` privilege in order to operate. +You may want to use this on Amazon RDS + ### conf `--conf=/path/to/my.cnf`: file where credentials are specified. Should be in (or contain) the following format: diff --git a/doc/requirements-and-limitations.md b/doc/requirements-and-limitations.md index e76e4db..4e061bd 100644 --- a/doc/requirements-and-limitations.md +++ b/doc/requirements-and-limitations.md @@ -7,7 +7,15 @@ - `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 `*.*` - - `SUPER, REPLICATION SLAVE` 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 @@ -20,6 +28,7 @@ - `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 probably not supported (due to `SUPER` requirement) +- Amazon RDS and Google Cloud SQL are currently not supported + - We began working towards removing this limitation. See tracking issue: https://github.com/github/gh-ost/issues/163 - 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. diff --git a/doc/testing-on-replica.md b/doc/testing-on-replica.md index c556512..cfc3c24 100644 --- a/doc/testing-on-replica.md +++ b/doc/testing-on-replica.md @@ -63,3 +63,6 @@ $ gh-osc --host=myhost.com --conf=/etc/gh-ost.cnf --database=test --table=sample ### Further notes Do not confuse `--test-on-replica` with `--migrate-on-replica`; the latter performs the migration and _keeps it that way_ (does not revert the table swap nor stops replication) + +As part of testing on replica, `gh-ost` issues a `STOP SLAVE`. This requires the `SUPER` privilege. +See related discussion on https://github.com/github/gh-ost/issues/162