本文的驗收標準是：你能產出 dump、記錄 binlog position、還原到隔離 database、跑 validation query，並寫下 RPO / RTO note。

Create Backup

Create backup 的核心責任是建立可還原 artifact。

1mkdir -p /tmp/mysql-backup-lab
2mysqldump -h 127.0.0.1 -P 33069 -u app_user -papp_pw \
3  --single-transaction --routines --triggers appdb \
4  > /tmp/mysql-backup-lab/appdb.sql

記錄 binlog 狀態：

1mysql -h 127.0.0.1 -P 33069 -u root -proot_pw -e "SHOW BINARY LOG STATUS;"

--single-transaction 適合 InnoDB consistent dump。大型 production 要評估 physical backup、backup lock、replication lag 與 binlog retention。

Mutate Source

Mutate source 的核心責任是讓 restore 時間點具體化。

1mysql -h 127.0.0.1 -P 33069 -u app_user -papp_pw appdb \
2  -e "INSERT INTO ledger_entries(account_id, amount_cents, idempotency_key) VALUES (1, 777, 'after-backup-write');"

Source 現在比 backup 多一筆。這能用來討論 RPO 與 binlog PITR。

Restore Isolated Database

Restore isolated database 的核心責任是避免覆蓋 source。

1mysql -h 127.0.0.1 -P 33069 -u root -proot_pw \
2  -e "DROP DATABASE IF EXISTS appdb_restore; CREATE DATABASE appdb_restore;"
3mysql -h 127.0.0.1 -P 33069 -u root -proot_pw appdb_restore \
4  < /tmp/mysql-backup-lab/appdb.sql

Validation：

1mysql -h 127.0.0.1 -P 33069 -u root -proot_pw appdb_restore <<'SQL'
2SELECT COUNT(*) FROM accounts;
3SELECT COUNT(*) FROM ledger_entries;
4SELECT a.owner_name, SUM(l.amount_cents) AS balance_cents
5FROM accounts a JOIN ledger_entries l ON l.account_id = a.id
6GROUP BY a.owner_name;
7SQL

Validation query 要和 application smoke test 對齊。正式 drill 還要啟動 app 指向 restore database。

RPO / RTO Note

RPO / RTO note 的核心責任是把演練結果轉成服務承諾。

完成本篇後，binlog CDC 讀 Binlog CDC；PITR 策略讀 PITR / Backup。

本文的驗收標準是：你能啟動 MySQL、套用 schema、跑 sample workload、取得 processlist / InnoDB status / table count，並能 teardown 重建。

Docker Compose

Docker Compose 的核心責任是讓 lab 環境可重建。

 1services:
 2  mysql:
 3    image: mysql:8.4
 4    environment:
 5      MYSQL_ROOT_PASSWORD: root_pw
 6      MYSQL_DATABASE: appdb
 7      MYSQL_USER: app_user
 8      MYSQL_PASSWORD: app_pw
 9    ports:
10      - "33069:3306"
11    command:
12      - "--performance-schema=ON"
13      - "--log-bin=mysql-bin"
14      - "--server-id=1"

啟動：

1docker compose up -d
2export MYSQL_PWD=app_pw
3mysql -h 127.0.0.1 -P 33069 -u app_user appdb -e "SELECT VERSION();"

Baseline Schema

Baseline schema 的核心責任是建立可測 transaction、index、binlog 與 OSC 的模型。

 1mysql -h 127.0.0.1 -P 33069 -u app_user appdb <<'SQL'
 2CREATE TABLE accounts (
 3  id BIGINT PRIMARY KEY AUTO_INCREMENT,
 4  tenant_id CHAR(36) NOT NULL,
 5  owner_name VARCHAR(128) NOT NULL,
 6  status ENUM('active', 'closed') NOT NULL,
 7  created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
 8  KEY idx_accounts_tenant (tenant_id)
 9) ENGINE=InnoDB;
10
11CREATE TABLE ledger_entries (
12  id BIGINT PRIMARY KEY AUTO_INCREMENT,
13  account_id BIGINT NOT NULL,
14  amount_cents BIGINT NOT NULL,
15  idempotency_key VARCHAR(128) NOT NULL,
16  created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
17  UNIQUE KEY uk_ledger_idempotency (idempotency_key),
18  KEY idx_ledger_account_created (account_id, created_at),
19  CONSTRAINT fk_ledger_account FOREIGN KEY (account_id) REFERENCES accounts(id)
20) ENGINE=InnoDB;
21SQL

Seed and Evidence

Seed and evidence 的核心責任是產生可重跑資料與 baseline。

 1mysql -h 127.0.0.1 -P 33069 -u app_user appdb <<'SQL'
 2INSERT INTO accounts(tenant_id, owner_name, status)
 3VALUES ('tenant-a', 'Ada', 'active'), ('tenant-b', 'Lin', 'active');
 4
 5INSERT INTO ledger_entries(account_id, amount_cents, idempotency_key)
 6VALUES (1, 1000, 'seed-ada-1'), (1, -200, 'seed-ada-2'), (2, 500, 'seed-lin-1');
 7
 8SELECT a.owner_name, SUM(l.amount_cents) AS balance_cents
 9FROM accounts a JOIN ledger_entries l ON l.account_id = a.id
10GROUP BY a.owner_name;
11SQL

Basic evidence：

1mysql -h 127.0.0.1 -P 33069 -u app_user appdb -e "SHOW FULL PROCESSLIST;"
2mysql -h 127.0.0.1 -P 33069 -u app_user appdb -e "SHOW TABLE STATUS;"
3mysql -h 127.0.0.1 -P 33069 -u app_user appdb -e "SHOW ENGINE INNODB STATUS\\G"

Teardown

Teardown 的核心責任是讓 lab 可重跑。

1docker compose down -v

完成本篇後，backup 進入 Backup Restore Drill；schema change 進入 Online Schema Change Lab；routing 進入 ProxySQL Routing Lab。

本文的驗收標準是：你能跑一個低風險 ALTER、觀察 metadata lock、記錄 validation query，並理解 gh-ost / pt-osc 的 cutover evidence。

Direct ALTER Baseline

Direct ALTER baseline 的核心責任是先看 MySQL 原生 DDL 的行為。

1mysql -h 127.0.0.1 -P 33069 -u app_user -papp_pw appdb <<'SQL'
2ALTER TABLE accounts ADD COLUMN email VARCHAR(255) NULL;
3SHOW CREATE TABLE accounts\G
4SQL

記錄 ALTER duration、algorithm、lock impact 與 table size。不同 MySQL 版本與 DDL 類型會有不同行為，production 要在 staging dry run。

Metadata Lock Observation

Metadata lock observation 的核心責任是看到 blocker。

開 Session A：

1START TRANSACTION;
2SELECT * FROM accounts WHERE id = 1;

保持 transaction 開啟。Session B 執行：

1ALTER TABLE accounts ADD COLUMN note VARCHAR(255) NULL;

Session C 查：

1SELECT OBJECT_SCHEMA, OBJECT_NAME, LOCK_TYPE, LOCK_STATUS, OWNER_THREAD_ID
2FROM performance_schema.metadata_locks
3WHERE OBJECT_SCHEMA = 'appdb';

完成觀察後，Session A COMMIT。這段 lab 展示 long transaction 如何讓 DDL 等待。

OSC Frame

OSC frame 的核心責任是理解 gh-ost / pt-online-schema-change 的證據，而非要求每個 lab 都安裝工具。

OSC runbook 要記錄：

1. Source table、ghost table、migration statement。
2. Copy progress、chunk size、throttle condition。
3. Replication lag / load threshold。
4. Cutover pre-check：long transaction、metadata lock、traffic。
5. Cutover duration 與 validation query。
6. Rollback / drop ghost table policy。

Cutover 前最重要的是 metadata lock pre-check。工具能降低大部分 copy 風險，但最後 rename / swap 仍需要短暫鎖。

Validation

Validation 的核心責任是證明 schema change 後資料與 query 仍正確。

1mysql -h 127.0.0.1 -P 33069 -u app_user -papp_pw appdb <<'SQL'
2SELECT COUNT(*) FROM accounts;
3SELECT COUNT(*) FROM ledger_entries;
4EXPLAIN SELECT * FROM accounts WHERE tenant_id = 'tenant-a';
5SQL

正式 migration 要補 row checksum、null rate、index usage、replication lag 與 application smoke test。

Release Gate

Release gate 的核心責任是形成交付 artifact。

1Migration:
2DDL / OSC command:
3Table size:
4MDL pre-check:
5Duration:
6Validation:
7Rollback:
8Owner:

完成本篇後，MDL 事故讀 Metadata Lock Deep Dive；工具選型讀 Online Schema Change Tools。

本文的驗收標準是：你能定義 writer / reader hostgroup、建立 query rule、觀察 routing stats，並寫下 stale read 與 failover 風險。

Hostgroup Model

Hostgroup model 的核心責任是把 backend 分成 writer 與 reader。

1hostgroup 10: writer
2hostgroup 20: reader

在單節點 lab 中，writer / reader 可以先指向同一 MySQL；正式環境應用 replica 作 reader，並搭配 replication lag guard。

Query Rule

Query rule 的核心責任是示範 routing policy。

1-- Conceptual ProxySQL admin commands. Adjust host / credential for your lab.
2INSERT INTO mysql_query_rules(rule_id, active, match_pattern, destination_hostgroup, apply)
3VALUES
4  (10, 1, '^SELECT', 20, 1),
5  (20, 1, '.*', 10, 1);
6LOAD MYSQL QUERY RULES TO RUNTIME;
7SAVE MYSQL QUERY RULES TO DISK;

這個規則把 SELECT 導向 reader，其餘導向 writer。Production 要排除 SELECT ... FOR UPDATE、transaction、read-after-write 與 session state。

Routing Evidence

Routing evidence 的核心責任是確認 query 真的走到預期 hostgroup。

1SELECT hostgroup, srv_host, Queries
2FROM stats_mysql_connection_pool;
3
4SELECT rule_id, hits
5FROM stats_mysql_query_rules
6ORDER BY rule_id;

Evidence 要和 application log 對齊。若某個 workflow 寫後立刻讀，routing rule 要保證它走 writer 或具備 freshness policy。

Failure Note

Failure note 的核心責任是記錄 proxy 常見風險。

完成本篇後，完整設定讀 ProxySQL Config；replica 與 failover 讀 Replication Failover Lab。

本文的驗收標準是：你能記錄 replication status、lag、promotion timeline、client error sample、validation query 與 incident decision log。

Baseline Replication

Baseline replication 的核心責任是先保存 source / replica 狀態。實際建立 replication 依 GTID、binlog file position、Docker topology 或 managed service 而異；本文聚焦演練 evidence。

1SHOW REPLICA STATUS\G
2SHOW BINARY LOG STATUS;

Baseline 要記錄：

1. Source host / replica host。
2. GTID executed / retrieved。
3. IO thread / SQL thread。
4. Seconds behind source。
5. Read endpoint / write endpoint。

Client Workload

Client workload 的核心責任是讓 failover 對 application 可見。

1while true; do
2  mysql -h "$MYSQL_WRITE_HOST" -u app_user -papp_pw appdb \
3    -e "INSERT INTO ledger_entries(account_id, amount_cents, idempotency_key) VALUES (1, 1, UUID());"
4  sleep 1
5done

這個 synthetic workload 產生成功、timeout、duplicate、read-only 或 connection error。正式演練要避免碰 production side effect。

Promotion Frame

Promotion frame 的核心責任是把 failover action 寫成可審查步驟。

1failover_start:
2old_source:
3candidate_replica:
4lag_before:
5promotion_method:
6accepted_data_loss:
7operator:

Managed service、Orchestrator 或手動 promotion 都要留下同樣欄位。工具不同，決策證據一致。

Validation

Validation 的核心責任是確認 promoted instance 可讀寫且資料符合預期。

1SELECT COUNT(*) FROM ledger_entries;
2SELECT MAX(created_at) FROM ledger_entries;
3SHOW VARIABLES LIKE 'read_only';
4SHOW VARIABLES LIKE 'super_read_only';

若使用 GTID，還要比較 source / replica 的 GTID set。若有 external side effect，要用 idempotency key 做 reconciliation。

Client Route

Client route 的核心責任是確認 application、ProxySQL、DNS 或 secret 已指向新 writer。

檢查項目：

1. Write endpoint 是否更新。
2. ProxySQL writer hostgroup 是否切換。
3. Application pool 是否清掉舊連線。
4. Retry 是否有 backoff。
5. Read replica 是否重新掛到新 source。

Failover 完成標準包含資料庫 promotion 與 client route 穩定。只 promote 成功，application 仍可能寫到舊 endpoint。

Incident Log

Incident log 的核心責任是把演練結果保存。

1Drill id:
2RTO observed:
3RPO / accepted data loss:
4Client errors:
5Validation:
6Follow-up:

完成本篇後，拓撲設計讀 Replication Topology；自動化工具讀 Orchestrator Failover；routing 讀 ProxySQL Routing Lab。

本文的驗收標準是：你能建立 sandbox、辨識 keyspace / shard / tablet / vtgate、跑基本 query，並記錄 resharding preview 的 evidence。

官方文件路由的核心責任是固定 sandbox 指令。實作前先查 Vitess local install docs；本文最後檢查日是 2026-05-22。

Concept Map

Concept map 的核心責任是先建立 Vitess vocabulary。

Vitess 的重點是 routing 與 resharding。Application 看到的是 vtgate；底下是多個 MySQL tablet 與 topology service。

Sandbox Setup

Sandbox setup 的核心責任是使用官方 sandbox 建立可丟棄環境。實際命令依 Vitess 版本調整，正式操作以 Vitess 官方文件為準。

1# Conceptual route. Use the current Vitess examples for exact commands.
2git clone https://github.com/vitessio/vitess.git
3cd vitess/examples/local
4./101_initial_cluster.sh

啟動後要記錄：

1. Vitess version。
2. Keyspace name。
3. Shard count。
4. vtgate host / port。
5. Tablet roles。

Query Through vtgate

Query through vtgate 的核心責任是確認 application 走 routing layer。

1mysql -h 127.0.0.1 -P 15306 -u user <<'SQL'
2SHOW DATABASES;
3USE commerce;
4SHOW TABLES;
5SELECT * FROM product LIMIT 5;
6SQL

Evidence 要包含 query result、target keyspace、vtgate endpoint 與 tablet health。Production migration 要確認 ORM / driver 對 vtgate 的相容性。

VSchema Review

VSchema review 的核心責任是理解 shard key 與 routing。

1# Conceptual command; exact path depends on sandbox.
2cat vschema_commerce_initial.json

審查問題：

1. 哪些 table 是 sharded。
2. shard key / vindex 是什麼。
3. lookup vindex 是否需要維護。
4. cross-shard query 是否存在。
5. sequence / id generation 如何處理。

VSchema 是 Vitess migration 的核心設計文件。選錯 shard key 會讓跨 shard transaction、hot shard 與 resharding 成本升高。

Resharding Preview

Resharding preview 的核心責任是看見 Vitess 的主要價值與操作成本。

Resharding evidence 欄位：

1source shard:
2target shards:
3workflow name:
4copy phase duration:
5replication lag:
6cutover time:
7validation query:
8rollback:

Resharding 是 production operation，不只是一次 migration。Runbook 要包含 throttling、lag、tablet health、cutover 與 application query validation。

Migration Decision

Migration decision 的核心責任是判斷何時從 MySQL 走向 Vitess / PlanetScale 類路線。

完成本篇後，設計細節讀 Vitess Sharding；managed route 讀 MySQL to PlanetScale。