diff --git a/README.md b/README.md index 2ffa892..55b7571 100644 --- a/README.md +++ b/README.md @@ -54,7 +54,11 @@ More tips: - Use `--postpone-cut-over-flag-file` to gain control over cut-over timing - Get familiar with the [interactive commands](doc/interactive-commands.md) -Also see [requirements and limitations](doc/requirements-and-limitations.md), [what if?](doc/what-if.md) +Also see: + +- [requirements and limitations](doc/requirements-and-limitations.md) +- [what if?](doc/what-if.md) +- [the fine print](doc/the-fine-print.md) ## What's in a name? diff --git a/doc/the-fine-print.md b/doc/the-fine-print.md new file mode 100644 index 0000000..3f1fe40 --- /dev/null +++ b/doc/the-fine-print.md @@ -0,0 +1,41 @@ +# The Fine Print: What are You Not Telling Me? + +Here are technical considerations you may be interested in. We write here things that are not an obvious [Requirements & Limitations](requirements-and-limitations.md) + +# Connecting to replica + +`gh-ost` prefers connecting to replica. If your master uses Statement Based Replication, this is a _requirement_. + +What does "connect to replica" mean? + +- `gh-ost` connects to the replica as a normal client +- It additionally connects as a replica to the replica (pretends to be a MySQL replica itself) +- It auto-detects master + +`gh-ost` reads the RBR binary logs from the replica, and applies events onto the master as tables are being migrated. + +THE FINE PRINT: + +- You trust the replica's binary logs to represent events applied on master. + If you don't trust the replica, if you suspect there's data drift between replica & master, take notice. If your master is RBR, do instead connect `gh-ost` to master, via `--allow-on-master` (see [cheatsheet](cheatsheet.md)). + Our take: we trust replica data; if master dies in production, we promote a replica. Our read serving is based on replica(s). + +- Replication needs to run. + This is an obvious, but worth stating. You cannot perform a migration with "connect to replica" if your replica lags. `gh-ost` will actually do all it can so that replication does not lag, and avoid critical operations at such time when replication does lag. + +# Network usage + +`gh-ost` reads binary logs and then applies them onto the migrated server. + +THE FINE PRINT: + +- `gh-ost` delivers more network traffic than other online-schema-change tools, that let MySQL handle all data transfer internally. This is part of the [triggerless design](triggerless-design.md). + Our take: we deal with cross-DC migration traffic and this is working well for us. + +# Impersonating as a replica + +`gh-ost` impersonates as a replica: connects to a MySQL server, says "oh hey, I'm a replica, please send me binary logs kthx". + +THE FINE PRINT: + +- `SHOW SLAVE HOSTS` or `SHOW PROCESSLIST` will list down this strange "replica" that you can't really connect to.