Merge pull request #120 from github/the-fine-print

adding The Fine Print documentation

Author: Shlomi Noach

.github/PULL_REQUEST_TEMPLATE.md

@@ -6,6 +6,7 @@
 
 Related issue: https://github.com/github/gh-ost/issues/0123456789
 
+> Further notes in https://github.com/github/gh-ost/blob/master/.github/CONTRIBUTING.md
 > Thank you! We are open to PRs, but please understand if for technical reasons we are unable to accept each and any PR
 
 ### Description

README.md

@@ -30,7 +30,7 @@ In addition, it offers many [operational perks](doc/perks.md) that make it safer
 - Auditing: you may query `gh-ost` for status. `gh-ost` listens on unix socket or TCP.
 - Control over cut-over phase: `gh-ost` can be instructed to postpone what is probably the most critical step: the swap of tables, until such time that you're comfortably available. No need to worry about ETA being outside office hours.
 
-Please meanwhile refer to the [docs](doc) for more information. No, really, read the [docs](doc).
+Please refer to the [docs](doc) for more information. No, really, read the [docs](doc).
 
 ## Usage
 
@@ -54,14 +54,17 @@ 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?
 
 Originally this was named `gh-osc`: GitHub Online Schema Change, in the likes of [Facebook online schema change](https://www.facebook.com/notes/mysql-at-facebook/online-schema-change-for-mysql/430801045932/) and [pt-online-schema-change](https://www.percona.com/doc/percona-toolkit/2.2/pt-online-schema-change.html).
 
-But then a rare genetic mutation happened, and the `s` transformed into `t`. And that sent us down the path of trying to figure out a new acronym. Right now, `gh-ost` (pronounce: _Ghost_), stands for:
-- GitHub Online Schema Transmogrifier/Translator/Transformer/Transfigurator
+But then a rare genetic mutation happened, and the `s` transformed into `t`. And that sent us down the path of trying to figure out a new acronym. `gh-ost` (pronounce: _Ghost_), stands for GitHub's Online Schema Transmogrifier/Translator/Transformer/Transfigurator
 
 ## License
 

doc/requirements-and-limitations.md

@@ -12,7 +12,8 @@
 ### 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.
+- 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.
 - 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.

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.