本文是 MySQL overview 的 implementation-layer deep article。Overview 已說明 MySQL 在 OLTP 譜系的定位、本文聚焦 Vitess sharding — 4 個 component 協作的完整 sharding 系統。

問題情境：MySQL 寫吞吐撞上 single primary 上限

MySQL primary 單機極限大致 50K-100K WPS（依 schema / hardware）。超過這個級別、選項三條：

1. Application 層 sharding：每張 table 自己決定怎麼分片、application 寫 routing logic、跨 shard query / migration 都要自己處理
2. Vitess：proxy layer 自動 routing、cross-shard query 可選自動 split、resharding 自動化
3. Distributed SQL（CockroachDB / Spanner / Aurora DSQL）：跟 MySQL 不同 engine、application 改 driver

選 Vitess 的核心 driver：保留 MySQL wire protocol + 應用層幾乎不必改 + 透明分片。代價是 4 個 component 的 operational complexity — Vitess 的責任範圍是完整分散式系統，而非單純 proxy。

閱讀本文前可先對齊 Database Sharding 的 shard key、routing、resharding 與 cross-shard query 語意；容量失衡時再接 Hot Partition。

Vitess 四件套：每個 component 的責任

 1                        ┌─────────────────┐
 2   Application ────→    │     VTGate      │  ← 對外 MySQL wire protocol
 3                        │  (proxy + parse + route + aggregate)  │
 4                        └────┬─────┬──────┘
 5                             │     │
 6                ┌────────────┘     └──────────────┐
 7                ▼                                 ▼
 8        ┌──────────────┐                  ┌──────────────┐
 9        │   VTTablet   │                  │   VTTablet   │
10        │ (per-MySQL   │                  │ (per-MySQL   │
11        │  sidecar)    │                  │  sidecar)    │
12        └─────┬────────┘                  └─────┬────────┘
13              │                                 │
14              ▼                                 ▼
15        ┌──────────────┐                  ┌──────────────┐
16        │    MySQL     │                  │    MySQL     │
17        │  (Shard -80) │                  │  (Shard 80-) │
18        └──────────────┘                  └──────────────┘
19
20   Topology Service (etcd / Consul / ZooKeeper)
21   ↑↓ 所有 component 共享 metadata
22   VSchema：keyspace 結構、shard 範圍、Vindex 定義

VTGate — query routing layer

對 application 看起來像 MySQL（同樣 port、同樣 wire protocol、同樣 query 語法）、實際是 stateless proxy。每個 query VTGate：

1. Parse SQL → 找出 routing key（從 WHERE column 拿）
2. 查 VSchema → 計算 routing key 對應的 shard
3. 把 query 送該 shard 的 VTTablet
4. 等 response、aggregate（如果是 cross-shard query）、回 application

Stateless 設計 → VTGate 可以隨意 scale、放 N 個前面接 LB。多數 production 部署 3-10 個 VTGate per region。

VTTablet — per-MySQL agent

每個 MySQL instance 旁邊都跑一個 VTTablet。VTTablet 責任：

• 把 MySQL primary 標記、上報給 topology
• 接 VTGate 的 query、轉發給 local MySQL
• 跑 connection pool（VTGate 跟 VTTablet 之間少量連線、VTTablet 跟 local MySQL 共享 connection）
• 跑 query plan cache / transactional consistency check
• 處理 online schema change（Vitess 內建 OSC）
• 跟 VTOrc（fork of Orchestrator）配合做 failover

VTTablet 是 Vitess 跟 MySQL 唯一連接點 — 沒 VTTablet 直接連 MySQL 不在 Vitess 管理下。

VReplication — 跨 shard 資料移動

VReplication 是 Vitess 跨 shard / 跨 keyspace / 跨 cluster 資料移動引擎、底層用 MySQL binlog。用途：

• Resharding：把 shard -80 拆成 -40 + 40-80、VReplication 自動拆 binlog event 對應 shard
• Materialized view：cross-shard aggregation 預計算
• MoveTables：跨 keyspace 移 table（schema-level migration）
• VStream：CDC、binlog event 對外輸出（可接 Kafka / Debezium）

VReplication 的主要使用者是 Vitess operator，它和 application 行為直接相關（resharding 期間有 write split 行為）。

VSchema — sharding metadata

VSchema 是 keyspace 內 哪張 table 怎麼 shard 的定義、JSON 格式存 topology service。例子：

 1{
 2  "sharded": true,
 3  "vindexes": {
 4    "hash": {
 5      "type": "hash"
 6    }
 7  },
 8  "tables": {
 9    "orders": {
10      "column_vindexes": [
11        {
12          "column": "user_id",
13          "name": "hash"
14        }
15      ]
16    },
17    "users": {
18      "column_vindexes": [
19        {
20          "column": "user_id",
21          "name": "hash"
22        }
23      ]
24    }
25  }
26}

orders.user_id 跟 users.user_id 用同一個 Vindex（hash）+ 同一個 column → 同 user_id 的 orders + users 落在同 shard、可以 JOIN 不跨 shard。

Vindex：Vitess 的 sharding function

Vindex 是 Vitess 的 shard key 計算函數。內建多種：

最常用：hash（primary key）+ lookup_hash（secondary access pattern）。

Keyspace / Shard / Tablet 階層

 1Keyspace (邏輯 database)
 2   └── Shards
 3        ├── -80 (shard range 0-128)
 4        │     ├── Primary tablet (1 MySQL primary)
 5        │     ├── Replica tablet × 2
 6        │     └── RDOnly tablet × 1 (analytics)
 7        └── 80- (shard range 128-256)
 8              ├── Primary tablet
 9              ├── Replica tablet × 2
10              └── RDOnly tablet × 1

Shard range 用 binary hex prefix（-80 表示 0 到 0x80、80- 表示 0x80 到 max）— 給 resharding 留 split 餘地（-80 可切成 -40 + 40-80）。

Tablet type：

• Primary：寫入入口
• Replica：read traffic（Vitess query rules 控制）
• RDOnly：純 analytics / backup / VReplication source、低 SLA、不上 production read traffic

配置 step-by-step（local cluster）

Production 通常用 Kubernetes operator（vitess-operator）部署、但理解概念用 local cluster 最快：

 1# 用 vtctldclient 操作（替代舊的 vtctlclient）
 2
 3# 1. 建 unsharded keyspace
 4vtctldclient CreateKeyspace --durability-policy=semi_sync commerce
 5
 6# 2. 從一個 MySQL primary 開始（unsharded）
 7vtctldclient ApplySchema --sql="CREATE TABLE orders (id INT PRIMARY KEY, user_id INT)" commerce
 8
 9# 3. 把 keyspace 改成 sharded、定義 VSchema
10vtctldclient ApplyVSchema --vschema='{
11  "sharded": true,
12  "vindexes": {"hash": {"type": "hash"}},
13  "tables": {
14    "orders": {
15      "column_vindexes": [{"column": "user_id", "name": "hash"}]
16    }
17  }
18}' commerce
19
20# 4. 觸發 resharding：unsharded → 2 shards (-80, 80-)
21vtctldclient Reshard --workflow=initial-shard create \
22  --source-shards="commerce/0" \
23  --target-shards="commerce/-80,commerce/80-"
24
25# 5. 等資料 copy 完（VReplication 跑）
26vtctldclient Workflow --keyspace=commerce show initial-shard
27
28# 6. SwitchTraffic：先切 RDOnly → 再切 Replica → 最後切 Primary
29vtctldclient Reshard --workflow=initial-shard switchtraffic \
30  --tablet-types="rdonly,replica"
31vtctldclient Reshard --workflow=initial-shard switchtraffic \
32  --tablet-types="primary"
33
34# 7. 完成、cleanup old shard
35vtctldclient Reshard --workflow=initial-shard complete

實際 production 走 Vitess Kubernetes operator、用 VitessCluster CRD 宣告 desired state、operator 自動操作上面這些 step。

5 個 Production 踩雷

1. Cross-shard transaction — Vitess 不支援 atomic（預設）

兩個 user 的 order 在不同 shard、BEGIN; UPDATE orders WHERE user_id=1; UPDATE orders WHERE user_id=2; COMMIT; 跨兩個 shard。Vitess 預設 不保證 atomic — 兩個 shard 各自 commit、可能一個成功一個失敗、application 看到 partial state。

修法：

• 避免 cross-shard transaction：schema design 讓 transaction boundary 落在單一 shard 內
• 啟用 atomic 2-phase commit（Vitess transaction_mode=TWOPC、實驗性、performance penalty 大）
• 大規模需要 atomic 的場景應該換 distributed SQL（CockroachDB / Spanner），讓資料庫層承擔跨節點一致性

2. VStream lag — Resharding 期間 CDC 落後

Resharding 過程 VReplication 大量寫 binlog event、application 本來在用 的 VStream（接 Kafka 等）共享同 binlog stream、可能 lag。Downstream consumer 看到 stale data 1-2 小時。

修法：

• Resharding 期間 暫停非關鍵 VStream（analytics ETL 可暫停、real-time recommendation 需要保留）
• 確認 binlog disk capacity > resharding 期間預估 binlog 量 × 2（buffer）
• Resharding 完成後 手動驗證 VStream offset 已 catch up，把驗證結果留成 cutover evidence

3. Vindex 不均勻 — Hot shard

Vindex 預設 hash 對 primary key 均勻分布、但對 natural key（country / region / company_id 等）可能不均勻。10 個 country、其中 1 個 country 佔 80% traffic、單一 shard 永遠 hot。

修法：

• Composite Vindex：combine country + user_id 兩 column 作為 shard key、user-level 仍均勻
• Synthetic shard key：application 層加 sharding_key=hash(actual_key) % N、控制分布
• 監控 per-shard QPS：vtctldclient ShowVDiff + Prometheus exporter
• Hot shard 出現後 Vitess 可以 resharding 解（split hot shard 為 2 個小 shard）、但工作量大

4. Resharding 切流量瞬間 deadlock

Resharding 最後的 SwitchTraffic 切 primary 階段、舊 shard 仍接 write、Vitess 切 routing、Application 一瞬間連兩個 shard、相同 user_id 寫入可能跑兩邊、deadlock 或 lost update。

修法：

• SwitchTraffic 用 ReverseTraffic 預備：先 switch、確認問題後可 reverse 回去
• 切流量 只在 known quiet period（夜間 / 週末早上）
• VTGate --retry-count=2 + --track-vtgate-deadlock-events：deadlock 自動 retry、不暴露給 application
• 真的失敗用 Reshard cancel 回 old state，讓 workflow 回到可驗證狀態

5. VReplication workflow 卡住 — cancel 前需要保護狀態

VReplication workflow 跑到 50% 但 某個 row 解析錯誤（schema mismatch / blob 大小超過 limit）、workflow stuck、進度條卡住、無 timeout。整個 resharding flow halt。

修法：

• 平時跑 staging 資料 dry-run、發現 schema 跟 blob 邊界問題
• Workflow 卡住時 vtctldclient Workflow show 看 last_message / row_state
• 手動修問題 row（直接 MySQL 改）後 resume workflow
• 大 cluster 建議 VReplication 跑前先 SchemaApply audit、確認 source / target schema 兼容

Vitess 跟自管 sharding 對照

Vitess 的 operational complexity 是它的代價。10-20 人 SRE 團隊撐得住、5 人團隊用 managed Vitess（PlanetScale） 更實際。

跟其他模組整合

跟 Replication topology

Vitess shard 內部仍用 MySQL replication（Replication Topology）— 每個 shard 有 primary + replica + rdonly。Vitess durability-policy 控制 primary 寫入是否等 replica ack（semi-sync）。

跟 OSC tool

Vitess 不用 gh-ost / pt-osc、用 VReplication-based online DDL。Vitess online DDL：

1vtctldclient ApplySchema --strategy=vitess \
2  --sql="ALTER TABLE orders ADD COLUMN status VARCHAR(20)" commerce

詳見 Online Schema Change Tools。

跟 ProxySQL

Vitess 取代 ProxySQL。VTGate 本身做 connection pool + query routing、不再需要 ProxySQL。混用會造成 routing 衝突（VTGate 期待自己決定 shard、ProxySQL 跟 VTGate 競爭）。詳見 ProxySQL 配置。

跟 Orchestrator

Vitess 用 VTOrc（fork of Orchestrator）作 failover、跟 Vitess topology metadata 整合。不用獨立 Orchestrator。詳見 Orchestrator failover 設計。

跟 PlanetScale（managed Vitess）

PlanetScale 是 Vitess managed service、隱藏 4 component operational complexity、加 branch-based schema workflow。詳見 PlanetScale migration playbook。

跟 Aurora MySQL

Aurora 跟 Vitess 是 不同 scale 路徑：

• Aurora：single-region scaling（storage / compute 分離、最高 ~128 TB）
• Vitess：horizontal sharding（無上限、靠加 shard scaling）

兩者承擔的容量與操作責任不同。超過 Aurora single-region 上限的場景才考慮 Vitess。詳見 Aurora vendor page。

Production case：YouTube / Vitess

Vitess 的 production 責任是把 MySQL shard 拓撲變成應用可查詢、可遷移、可操作的資料庫層。YouTube / Vitess 的公開歷史提供的工程訊號是 VTGate、VTTablet、VReplication 與 VSchema 這組元件分工：application query 進 VTGate、tablet 層包住 MySQL、VSchema 描述 routing / sharding 規則、VReplication 支援 resharding 與資料搬移。

這個案例要回收到三個操作判準。第一，Vitess 是一套 database control plane，而非單一 proxy；導入時要把 topology service、tablet lifecycle、backup、failover 與 schema workflow 一起納入 ownership。第二，VSchema 是 application contract，shard key、lookup vindex 與 cross-shard query 都會影響產品功能設計。第三，VReplication 讓 resharding 可操作，但它仍需要 capacity window、backfill 監控與 cutover plan。

Vitess 的 sibling 路由是 PostgreSQL Citus Distributed 與 1.11 全球分散式 OLTP。Citus 保留 PostgreSQL 生態並用 coordinator / worker 拆分資料；CockroachDB / Spanner 則用 distributed SQL 重新定義交易與一致性邊界。選型時要先判斷自己是在延伸 MySQL 投資，還是在重新選 global OLTP model。

何時用 Vitess

相關連結

• MySQL vendor overview
• MySQL Replication Topology（Vitess shard 內部）
• MySQL Online Schema Change Tools（Vitess 不用 gh-ost / pt-osc）
• MySQL ProxySQL 配置（Vitess 取代 ProxySQL）
• MySQL Orchestrator failover（VTOrc fork）
• PostgreSQL Citus Distributed（PG sibling、coordinator + worker 模型 vs Vitess VTGate + tablet）
• 1.11 全球分散式 OLTP（Vitess vs CockroachDB vs Spanner）
• Database Sharding（shard key、routing、resharding 與 cross-shard query）
• 官方：Vitess Documentation / Vitess Operator

本文是跨 vendor migration playbook、cross-link 到 Vitess sharding 跟 PlanetScale。走 Migration playbook methodology Type C operational hybrid 結構。

這條 migration 跟 → Aurora MySQL 相似（self-managed → managed），但 target 是 Vitess-native managed、保留 sharding 能力。同時加上 → PlanetScale from self-managed MySQL 的 branch workflow paradigm。

對 已花心力建 Vitess team 但 ops cost 太大 的 org 來說、這條 migration 比 Vitess → distributed SQL 風險低、保留 sharding investment。

為什麼是 Type C（不是 Type A 或 Type E）

跑 6 維 diff dimension audit：

Operational = High（其他 Low / Medium） → Type C operational hybrid。Branch workflow 是 Medium paradigm shift 但不是 dominant — 主要工作量在 operational ownership 轉移。

跟 自管 MySQL → PlanetScale（Type E paradigm shift）對比：那條 path 是 no-Vitess → Vitess + branch、要學 Vitess 概念 + branch；本條是 已有 Vitess + 加 branch、只學 branch、複雜度低很多。

Driver：Ops headcount + Branch workflow + Vitess feature 加速

從自管 Vitess 遷 PlanetScale 的核心 driver：

Ops headcount 削減：

• 自管 Vitess 通常需要 2-5 個 SRE/DBA 撐 production —VTGate / VTTablet / VReplication / VSchema 各有議題
• PlanetScale 把這層全部 outsource、團隊 ops headcount 可降到 < 1 FTE
• 對 50-200 人 eng team、ops cost saving 是顯著 driver

Branch workflow paradigm：

• 自管 Vitess 仍用 gh-ost / pt-osc 或 Vitess online DDL 跑 schema migration、是 DBA 主導
• PlanetScale branch workflow 把 schema migration 變 developer self-service、開 branch / Deploy Request / merge、跟 git workflow 同節奏
• 對 high-velocity engineering culture 是文化升級

Vitess upstream feature：

• PlanetScale team 是 Vitess 的主要 contributor、新 feature 通常 PlanetScale 先 ship
• 自管 Vitess 升級慢、PlanetScale 用戶看到新 feature 早 3-6 個月

不適合 跨雲 portability priority high 或 strict on-prem deployment 的 org — PlanetScale 是 cloud-only。

4-phase migration

Phase 1：Topology + VSchema audit

把當前自管 Vitess cluster 完整盤點：

 1# Vitess cluster topology
 2vtctldclient GetKeyspaces
 3vtctldclient GetShards <keyspace>
 4vtctldclient GetTablets
 5
 6# VSchema
 7vtctldclient GetVSchema <keyspace>
 8
 9# 跨 keyspace VReplication workflow
10vtctldclient GetWorkflows

對每個 keyspace 檢查：

• Shard 數量：PlanetScale plan 對 shard 數量有 limit（Enterprise 才能超大規模）
• VSchema features：自管可能用 PlanetScale 不支援的 Vindex（custom Vindex）
• Foreign key：Vitess 18+（2023 末）才支援 FK、自管 Vitess 大多 < 18、cluster 內已 application-enforced；遷 PlanetScale 後可選擇啟用 native FK（同 shard 內）或繼續 application enforcement
• Stored procedure / trigger：PlanetScale 受限、確認是否 application 依賴

完成標準：寫 blocker list（PlanetScale 不支援的功能）+ compatibility list（功能對應）。

Phase 2：Dual cluster + binlog stream

PlanetScale 內建 Vitess Connector、從外部 MySQL（包括其他 Vitess cluster）binlog stream import：

1# 1. 用 PlanetScale CLI 建 cluster
2pscale database create production --region us-east
3
4# 2. Import schema（從自管 Vitess export）
5pscale shell production main < schema.sql
6
7# 3. 設 Vitess Connector 從自管 cluster import 資料
8# （透過 PlanetScale Console）

Vitess Connector 從自管 VTTablet 的 MySQL primary 讀 binlog、寫進 PlanetScale。Lag 通常 < 1 秒。

跑 1-2 週、確認：

• Schema 完整 migrate
• VSchema 對應正確（Vindex 行為一致）
• Lag 穩定

Phase 3：Application read 切 PlanetScale

跟 Aurora migration Phase 2 同概念。Application read query 切 PlanetScale endpoint：

• 連 PlanetScale connection string（xxx.connect.psdb.cloud）
• 仍寫自管 Vitess、Vitess Connector 同步 PlanetScale

跑 2-4 週、驗證：

• Query result 一致
• PlanetScale read latency 接近自管（PlanetScale Boost cache 可能加速）
• PlanetScale row read 計費跟預估一致

Phase 4：Write cutover + 自管 Vitess 退役

 1# 1. PlanetScale 把 cluster promote 為 primary（透過 Console）
 2# 透過 PlanetScale Console 啟用 production write 或用 `pscale` CLI 對應 promotion 命令
 3# （CLI 命令名稱隨 pscale 版本變動、以 pscale --help 為準）
 4
 5# 2. Application 寫 connection string 切 PlanetScale
 6# 自管 Vitess → PlanetScale
 7
 8# 3. Vitess Connector 反向（PlanetScale → 自管）作為 rollback buffer
 9
10# 4. 跑 1-2 週確認、開始 decommission 自管 Vitess

Decommission 自管 Vitess 是大工程：

• VTGate / VTTablet pods 一個個關
• VReplication workflow 停掉
• MySQL backend 保留作 cold backup 1-3 月、然後 EBS snapshot + terminate

完成標準：所有 traffic 在 PlanetScale、自管 Vitess 資源全 release、ops headcount confirm 下降。

5 個 Production 踩雷

1. VSchema 不完全兼容 — Custom Vindex 必須改

自管 Vitess 可能用了 custom Vindex（自寫 Go plugin）、PlanetScale 不支援 custom Vindex（只支援 built-in：hash / lookup_hash / unicode 等）。

修法：

• Phase 1 audit 出所有 custom Vindex
• 對每個 custom Vindex 評估能否用 built-in 替代
• 不能替代的、考慮 application 層 logic 取代 Vindex（application 自己算 shard key）
• 或 暫不遷該 keyspace、保留自管 Vitess 跑 custom Vindex keyspace、其他遷 PlanetScale

2. Branch workflow 訓練不到位 — DBA 仍用「Vitess online DDL」心智模型

自管 Vitess team 習慣 vtctldclient ApplySchema --strategy=vitess 跑 online DDL、遷 PlanetScale 後仍想直接這樣 — 但 PlanetScale production branch 禁止 schema change、必須走 Deploy Request。

修法：

• Phase 3 訓練步驟：team 每個 DBA / SRE 都跑過完整 branch + Deploy Request workflow
• 寫 team runbook：production schema change must 走 branch
• 緊急 schema change（事故中）也走 branch、PlanetScale 可加速 Deploy

3. SUPER privilege 移除 — 自管 admin tool 失效

自管 Vitess 用 SUPER privilege 跑 admin script、PlanetScale 沒給 SUPER。常見失效：

• 自寫 monitor script 跑 SHOW SLAVE STATUS、PlanetScale 抽象掉
• 自寫 backup script 跑 FLUSH TABLES WITH READ LOCK、PlanetScale 不允許
• 自寫 cleanup script 跑 KILL QUERY、PlanetScale 受限

修法：

• Phase 1 audit 所有 admin script
• 改用 PlanetScale Console / CLI / API 等價操作
• PlanetScale 提供的 monitoring 介面替代自管監控

4. Connection limit — PlanetScale plan 比預期緊

PlanetScale Scaler Plan: 10K connection、Enterprise: 100K。自管 Vitess VTGate 通常設 50K-200K connection、遷 PlanetScale 後 hit limit。

修法：

• Phase 1 connection forecast：peak hour 多少 active connection
• 升 PlanetScale plan（Scaler Pro / Enterprise）
• 或在 application 端加 connection pool（HikariCP / pgBouncer 等價）降低 connection count

5. Cost model 翻盤 — Per-row read 計費超預期

PlanetScale 計費是 per row read / written。自管 Vitess cost = EC2 + EBS（線性 with infrastructure scale）。遷 PlanetScale 後計費跟 application access pattern 直接相關。

常見 surprise：

• Heavy analytics query（COUNT *、aggregation）讀大量 row、計費高
• N+1 query pattern（application 跑很多小 SELECT）讀很多 row、計費高
• Read-heavy workload 沒 Boost cache、每次 query 都 hit billing

修法：

• Phase 1 cost forecast：用 pscale analytics 預估 row read / write 量、估算月帳
• Phase 2 期間實際對 PlanetScale 跑 traffic、看實際 billing
• Heavy analytics 改 材料化 view / async aggregation、不是每次 query
• 高 read frequency 開 Boost cache（額外 cost、但比 row read 便宜）

Capability mapping

容量與成本對照

對 200 人 eng team 用自管 Vitess（10 shard、20 TB 資料、50K WPS）：

對中型規模、PlanetScale 通常 break-even 或更便宜。對極大規模（> 200K WPS / > 100 TB）PlanetScale Enterprise 需要 commit pricing、不一定划算。

何時不要遷

• 跨雲 / on-prem 是 requirement：PlanetScale cloud-only
• Custom Vindex / 特殊 plugin 大量使用：兼容度低、改造工作量大
• 規模極大 > 500K WPS / > 200 TB：PlanetScale plan 對應 Enterprise commit、議價辛苦
• 強合規 / 資料主權限制：金融 / 政府 / 醫療場景、PlanetScale 不一定能 cover compliance
• 既有 Vitess team 強 + ops cost 低：如果 ops 已經精實、不必為 outsource 而 outsource

跟其他模組整合

跟 Vitess sharding

本 migration 保留 Vitess sharding 概念、application code 視角幾乎不變。Phase 1 audit 是 Vitess concept 對應 PlanetScale concept、不是 拆 Vitess 換 distributed SQL。

跟 → PlanetScale (from self-managed MySQL)

本 migration 是 Vitess → PlanetScale、前者是 MySQL → PlanetScale。差異：

• MySQL → PlanetScale (Type E)：要學 Vitess 概念 + branch workflow + FK 處理
• Vitess → PlanetScale (Type C)：只學 branch workflow + ops outsource、保留所有 Vitess investment

選哪條 path 取決於起點。

跟 Major Version Upgrade

從自管 Vitess 上 MySQL 5.7 遷 PlanetScale 也是 同時跨 major version（PlanetScale 跑 8.0+ Vitess）。Application 必須同時處理 5.7 → 8.0 paradigm shift（charset / auth）。

相關連結

• MySQL vendor overview
• Vitess Sharding（self-managed source）
• → PlanetScale from self-managed MySQL（不同起點）
• → Aurora MySQL（另一條 self-managed → managed path）
• Major Version Upgrade（5.7 → 8.0 同期考量）
• 方法論：Migration Playbook Methodology（Type C operational hybrid）
• 官方：PlanetScale Migration Guide / Vitess Operator

本文的驗收標準是：你能建立 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。