Merge pull request #59 from github/more-docs-4

More docs

Author: Shlomi Noach

README.md

@@ -18,6 +18,7 @@ Please meanwhile refer to the [docs](doc) for more information. No, really, go t
 - [Cut over phase](doc/cut-over.md)
 - [Testing on replica](doc/testing-on-replica.md)
 - [Throttle](doc/throttle.md)
+- [Operational perks](perks.md)
 - [Migrating with Statement Based Replication](doc/migrating-with-sbr.md)
 - [Understanding output](doc/understanding-output.md)
 - [Interactive commands](doc/interactive-commands.md)

doc/perks.md

@@ -0,0 +1,51 @@
+# Perks
+
+Listed below are some operation perks that make the DBA happy.
+
+### Dynamic reconfiguration
+
+You started with a `chunk-size=5000` but you find out it's too much. You want to reduce it. There is no need to kill and restart the migration with a new configuration. You may change the `chunk-size` dynamically.
+
+`gh-ost` listens on a unix socket file, and optionally via `TCP` as well. You may, for example:
+
+```shell
+$ echo "chunk-size=250" | nc -U /tmp/gh-ost.test.sample_data_0.sock
+```
+
+Read more about [interactive commands](interactive-commands.md)
+
+### What's the status?
+
+You do not have to have access to the `screen` where the migration is issued. You have two ways to get current status:
+
+0. Use [interactive commands](interactive-commands.md). Via unix socket file or via `TCP` you can get current status:
+
+```shell
+$ echo status | nc -U /tmp/gh-ost.test.sample_data_0.sock
+# Migrating `test`.`sample_data_0`; Ghost table is `test`.`_sample_data_0_gst`
+# Migration started at Tue Jun 07 11:45:16 +0200 2016
+# chunk-size: 200; max lag: 1500ms; max-load: map[Threads_connected:20]
+# Throttle additional flag file: /tmp/gh-ost.throttle
+# Serving on unix socket: /tmp/gh-ost.test.sample_data_0.sock
+# Serving on TCP port: 10001
+Copy: 0/2915 0.0%; Applied: 0; Backlog: 0/100; Elapsed: 40s(copy), 41s(total); streamer: mysql-bin.000550:49942; ETA: throttled, flag-file
+```
+
+0. `gh-ost` creates and uses a changelog table for internal bookkeeping. This table has the `_osc` suffix (the tool creates and announces this table upon startup) If you like, you can SQL your status:
+
+```
+> select * from _sample_data_0_osc order by id desc limit 1 \G
+*************************** 1. row ***************************
+         id: 325
+last_update: 2016-06-08 15:52:13
+       hint: copy iteration 0 at 1465393933
+      value: Copy: 0/2915 0.0%; Applied: 0; Backlog: 0/100; Elapsed: 1m35s(copy), 1m35s(total); streamer: mysql-bin.000560:60904; ETA: throttled, flag-file
+```
+
+### Postpone the cut-over phase
+
+You begin a migration, and the ETA is for it to complete at 04:00am. Not a good time for you, because you happen to want to have eyes on things as the migration completes (ideally, you shouldn't need to, but life is hard).
+
+Today, DBAs are coordinating the migration start time such that it completes in a convenient hour. `gh-ost` offers an alternative: postpone the final cut-over phase till you're ready.
+
+Execute `gh-ost` with `--postpone-cut-over-flag-file=/path/to/flag.file`. As long as this file exists, `gh-ost` will not take the final cut-over step. It will complete the row copy, and continue to synchronize the tables by continuously applying changes made on the original table onto the ghost table. It can do so on and on and on. When you're finally ready, remove the file and cut-over will take place.