test(demo): add some comments to pt-osc demo

scripts/create-triggers-accounts.sh

@@ -12,16 +12,20 @@ set -ex
 # Optionally, initialize a new, empty database.
 if [ ! -z "$REMOVE_OLD_FXA_DB" ]; then
   mysql fxa -e 'DROP DATABASE IF EXISTS fxa'
-  node ./bin/db_patcher.js
 fi
 
-# Create _accounts_new from accounts, install the DEL/UPD/INS triggers, and compare.
+# Ensure `fxa`.`accounts` exists.
+node ./bin/db_patcher.js
+
+# Create _accounts_new from accounts, install the DEL/UPD/INS triggers.
 mysql fxa < ./scripts/create-triggers-accounts.sql
 mysql fxa -e 'show create table accounts\G show create table _accounts_new\G show triggers\G'
+# Compare the two empty initial tables
 mysql fxa < ./scripts/union-compare-two-tables.sql
 
-# Run equiv. of `npm run test-mysql`, populating some rows and check that accounts
-# and _accounts_new have the same data.
+# Run equiv. of `npm run test-mysql`, to create/delete/update some rows in
+# `fxa`.`accounts`, and then compare that all those changes now appear in
+# `fxa`.`_accounts_new`.
 NO_COVERAGE=1 node ./scripts/mocha-coverage.js test/backend test/local --exit
 mysql fxa < ./scripts/union-compare-two-tables.sql
 

scripts/create-triggers-accounts.sql

@@ -1,12 +1,43 @@
 USE fxa;
 SET NAMES utf8mb4 COLLATE utf8mb4_bin;
 
--- Clear any existing triggers
+--
+-- Short summary of `pt-online-schema-change` mechanics:
+--
+-- 1) creates a mirror `_tablename_new` table identical to the schema of
+--   `tablename`.
+--
+-- 2) runs the alter on `_tablename_new` specified in the `--alter`
+-- option. Since it is altering an empty table, this takes zero time.
+--
+-- 3) installs triggers for insert/delete/update changes to `tablename`
+--    so that changes to `tablename` are replayed into `_tablename_new`
+--    while the the copy phase in (4) is in progress.
+--
+-- 4) begins walking the rows in `tablename`, copying chunks into
+--    `_tablename_new` while adapting the chunk size as various
+--    performance metrics (execution time, slave lag, master threads
+--    running) change.
+--
+-- 5) when the copy phase is complete, `pt-osc` swaps the `_tablename_new`
+--    with `tablename`, and removes the triggers the swapped out table.  the
+--    triggers on `tablename`. The contents of what was `_tablename_new` are
+--    now the new authoritative table contents.
+--
+-- This script is intended to provide a "playground" to get familiar
+-- with steps 1-3 below in a local environment.
+--
+
+--
+-- Clear any existing triggers leftover from previous runs.
+--
 DROP TRIGGER IF EXISTS pt_osc_fxa_accounts_del;
 DROP TRIGGER IF EXISTS pt_osc_fxa_accounts_ins;
 DROP TRIGGER IF EXISTS pt_osc_fxa_accounts_upd;
 
--- Create a mirror copy of fxa.accounts schema and data
+--
+-- Create fxa._accounts_new as a mirror copy of fxa.accounts schema and data.
+--
 DROP TABLE IF EXISTS _accounts_new;
 CREATE TABLE `_accounts_new` (
   `uid` binary(16) NOT NULL,
@@ -27,10 +58,18 @@ CREATE TABLE `_accounts_new` (
   UNIQUE KEY `normalizedEmail` (`normalizedEmail`)
 ) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_unicode_ci SELECT * FROM accounts;
 
--- Add a new columnn
-ALTER TABLE _accounts_new ADD COLUMN profileChangedAt BIGINT UNSIGNED DEFAULT NULL;
+--
+-- Add two new columns to `fxa`.`_accounts_new`.
+--
+ALTER TABLE _accounts_new ADD COLUMN profileChangedAt BIGINT UNSIGNED DEFAULT NULL,
+                          ADD COLUMN keysChangedAt BIGINT UNSIGNED DEFAULT NULL;
 
--- Install the triggers
+--
+-- Install triggers for DELETE/INSERT/UPDATE changes of the `fxa`.`accounts`
+-- table to repeat them idempotently into the `fxa`.`_accounts_new` table
+--
+-- NOTE: these statements are the statements generated by
+-- `pt-online-schema-change`, which lowercases all the column names.
 --
 CREATE TRIGGER `pt_osc_fxa_accounts_del` AFTER DELETE ON `fxa`.`accounts` FOR EACH ROW
   DELETE FROM `fxa`.`_accounts_new` WHERE `fxa`.`_accounts_new`.`uid` <=> OLD.`uid`;
@@ -38,7 +77,7 @@ CREATE TRIGGER `pt_osc_fxa_accounts_del` AFTER DELETE ON `fxa`.`accounts` FOR EA
 --
 CREATE TRIGGER `pt_osc_fxa_accounts_ins` AFTER INSERT ON `fxa`.`accounts` FOR EACH ROW
   REPLACE INTO `fxa`.`_accounts_new` (`uid`, `normalizedemail`, `email`, `emailcode`, `emailverified`, `ka`, `wrapwrapkb`, `authsalt`,
-               `verifyhash`, `verifierversion`, `verifiersetat`, `createdat`, `locale`, `lockedat`) 
+               `verifyhash`, `verifierversion`, `verifiersetat`, `createdat`, `locale`, `lockedat`)
   VALUES (NEW.`uid`, NEW.`normalizedemail`, NEW.`email`, NEW.`emailcode`, NEW.`emailverified`, NEW.`ka`, NEW.`wrapwrapkb`, NEW.`authsalt`,
           NEW.`verifyhash`, NEW.`verifierversion`, NEW.`verifiersetat`, NEW.`createdat`, NEW.`locale`, NEW.`lockedat`);
 
@@ -56,6 +95,3 @@ CREATE TRIGGER `pt_osc_fxa_accounts_upd` AFTER UPDATE ON `fxa`.`accounts` FOR EA
   END
 $$
 DELIMITER ;
-
--- now run tests, and then `source ./scripts/union-compare-two-tables.sql
-

scripts/union-compare-two-tables.sql

@@ -1,3 +1,7 @@
+-- In comparing two tables, where one of the tables has additional columns
+-- that do not exist in the other table, we only compare the columns that
+-- exist in both tables.
+
 SELECT
   HEX(uid) AS uid,
   normalizedEmail,