From ebd53371d64a08388e1a663b54a7b18c65a25edb Mon Sep 17 00:00:00 2001 From: Shlomi Noach Date: Thu, 25 Aug 2016 14:43:06 +0200 Subject: [PATCH] adding hooks documentation --- doc/hooks.md | 74 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 74 insertions(+) create mode 100644 doc/hooks.md diff --git a/doc/hooks.md b/doc/hooks.md new file mode 100644 index 0000000..48d3887 --- /dev/null +++ b/doc/hooks.md @@ -0,0 +1,74 @@ +# Hooks + +`gh-ost` supports _hooks_: external processes which `gh-ost` executes at particular points of interest. + +Use cases include: + +- You wish to be notified ny mail when a migration completes/fails +- You wish to be notified when `gh-ost` postpones cut-over (at your demand), thus ready to complete (at your leisure) +- RDS users who wish to `--test-on-replica`, but who cannot have `gh-ost` issue a `STOP SLAVE`, would use a hook to command RDS to stop replication +- Send a status message to your chatops every hour +- Perform cleanup on the _ghost_ table (drop/rename/nibble) once migration completes +- etc. + +`gh-ost` defines certain points of interest (event types), and executes hooks at those points. + +Notes: + +- You may have more than one hook per event type. +- `gh-ost` will invoke relevant hooks _sequentially_ and _synchronously_ + - thus, you would generally like the hooks to execute as fast as possible, or otherwise issue tasks in the background +- A hook returning with error code will propagate the error in `gh-ost`. Thus, you are able to force `gh-ost` to fail migration on your conditions. + - Make sure to only return an error code when you do indeed wish to fail the rest of the migration + +### Creating hooks + +All hooks are expected to reside in a single directory. This directory is indicated by `--hooks-path`. When not provided, no hooks are executed. + +`gh-ost` will dynamically search for hooks in said directory. You may add and remove hooks to/from this directory as `gh-ost` makes progress (though likely you don't want to). Hook files are expected to be executable processes. + +In an effort to simplify code and to standardize usage, `gh-ost` expects hooks in explicit naming conventions. As an example, the `onStartup` hook expects processes named `gh-ost-on-startup*`. It will match and accept files named: + +- `gh-ost-on-startup` +- `gh-ost-on-startup--send-notification-mail` +- `gh-ost-on-startup12345` +- etc. + +The full list of supported hooks is best found in code: [hooks.go](https://github.com/github/gh-ost/blob/master/go/logic/hooks.go). Documentation will always be a bit behind. At this time, though, the following are recognized: + +- `gh-ost-on-startup` +- `gh-ost-on-validated` +- `gh-ost-on-rowcount-complete` +- `gh-ost-on-before-row-copy` +- `gh-ost-on-status` +- `gh-ost-on-interactive-command` +- `gh-ost-on-row-copy-complete` +- `gh-ost-on-stop-replication` +- `gh-ost-on-begin-postponed` +- `gh-ost-on-before-cut-over` +- `gh-ost-on-success` +- `gh-ost-on-failure` + +### Context + +`gh-ost` will set environment variables per hook invocation. Hooks are then able to read those variables, indicating schema name, table name, `alter` statement, migrated host name etc. Some variables are available on all hooks, and some are available on relevant hooks. + +The following variables are available on all hooks: + +- `GH_OST_DATABASE_NAME` +- `GH_OST_TABLE_NAME` +- `GH_OST_GHOST_TABLE_NAME` +- `GH_OST_OLD_TABLE_NAME` +- `GH_OST_DDL` +- `GH_OST_ELAPSED_SECONDS` +- `GH_OST_MIGRATED_HOST` +- `GH_OST_INSPECTED_HOST` +- `GH_OST_EXECUTING_HOST` +- `GH_OST_HOOKS_HINT` + +- `GH_OST_COMMAND` is only available in `gh-ost-on-interactive-command` +- `GH_OST_STATUS` and `GH_OST_ELAPSED_SECONDS` are only available in `gh-ost-on-status` + +### Examples + +See [sample hooks](https://github.com/github/gh-ost/tree/master/resources/hooks-sample), as `bash` implementation samples.