本文是跨 vendor migration playbook、cross-link 到 MySQL 跟 PlanetScale。走 Migration playbook methodology Type E paradigm shift 結構。

從 application 連線 視角：跟 Aurora MySQL migration 一樣低、connection string 換就完事。從 schema management 視角：PlanetScale 強推 branch-based workflow — 改 schema 不再是「跑 gh-ost」、是「開 branch → Deploy Request → review → merge」。整個 schema change 工作流跟 git 同型、跟 application code review 同 workflow。

這是 workflow + schema-tooling shift — Aurora 是「同 workflow + managed」、PlanetScale 是「同 protocol + 不同 schema workflow + branch tooling」。Database paradigm（OLTP relational）跟 application change 都 Low、主要 shift 在 DBA / dev 操作介面。

為什麼是 Type E（Paradigm + Operational + Schema 多軸）

跑 6 維 diff dimension audit：

Paradigm + Operational + Schema 三軸 High。按優先序 Schema > Paradigm > Operational、預設選 Type A。但 讀者最關心 的是 schema workflow paradigm 轉變、不是 schema field translation — Type E 結構更貼合「不收斂、部分 adopt」的真實 migration 流程。

→ Type E paradigm shift、4-phase partial migration（多數 org 停 Phase 2-3 hybrid）。

Driver：Branch-based workflow + Vitess transparent sharding + zero DBA

從自管 MySQL 遷 PlanetScale 的核心 driver 有三條：

Branch-based schema workflow：

• 改 schema 開 branch（pscale branch create）、在 branch 上跑 ALTER、跑 application code 改、merge 進 main 前 Deploy Request review
• Deploy Request 顯示 schema diff、跟 GitHub PR 同概念
• Merge 後 PlanetScale 自動跑 no-downtime schema migration（內部 VReplication）
• 出問題可 revert（48 小時內、用 Vitess VReplication 反向 ship 資料）

這條 workflow 對 developer ergonomic 拉力大 — schema change 不再是「DBA 工作」、是「dev 自己處理、跟 code review 同流程」。

Vitess transparent sharding：

• PlanetScale 強制每個 cluster 走 Vitess（即使單 keyspace 看似 unsharded）
• 寫吞吐成長到需要 shard 時、加 shard 是 PlanetScale internal 操作、application 看不到
• 不用養 Vitess SRE 團隊

Zero DBA：

• PlanetScale 接管所有 ops（failover / backup / parameter / scaling）
• 跟 Aurora 同等級「managed」、加上 branch workflow

FK 處理：早期 Vitess（< 18）不支援 FK、PlanetScale 對應期間建議全 drop FK + 改 application enforcement。Vitess 18（2023 末）後加 FK 支援、PlanetScale 在合適 plan 內可啟用、但 cross-shard FK 仍受限。Phase 1 audit 重點不再是「全 drop FK」、而是「驗證 FK 行為（特別 cascade / cross-shard）跟自管 MySQL 預期一致」。

4-phase partial migration（不收斂）

Phase 1：FK 行為驗證 + schema audit、PlanetScale shadow cluster 起來

第一步是 FK 行為驗證 + schema layout audit。Vitess 18+ / PlanetScale 已支援 FK、但行為跟自管 MySQL 有差異：

• 列所有 FK：SELECT * FROM information_schema.KEY_COLUMN_USAGE WHERE REFERENCED_TABLE_NAME IS NOT NULL
• 對每個 FK 評估：
  • Cross-shard FK：PlanetScale 不允許 FK 跨 shard、parent 跟 child 必須同 shard（透過 Vindex 設計）
  • Cascade 行為：cross-shard DELETE cascade 在 PlanetScale 不執行、改 application 層處理
  • Native FK 啟用 vs application enforcement：依 Vitess 18+ 行為決定保留 FK 或改 app-level
• PlanetScale shadow cluster 起來、跑 application schema、用 Vitess Connector 從自管 binlog ship 資料

工作主要塊：

• FK 行為 audit + 改 cross-shard cascade（依 FK 數量、weeks 工作量）
• Schema dump → PlanetScale import（用 pscale shell）
• Vitess Connector 設定 binlog stream

完成標準：PlanetScale shadow cluster 有完整 production schema、cross-shard FK 已處理、binlog stream lag < 1 秒。

Phase 2：Read traffic 切 PlanetScale

跟 Aurora migration Phase 2 同概念：read query 切 PlanetScale connection string、寫入仍自管 MySQL。

差異：

• PlanetScale connection 有 per-plan rate limit（Scaler Plan: 10K connections、Enterprise: 100K）
• 必須走 PlanetScale connection pool（不是直接連、有 SSL handshake overhead）
• 監控 pscale_io_read_query_throttled_total 確認沒撞 plan limit

跑 2-4 週、確認：

• PlanetScale read latency 跟自管 replica latency 接近（PlanetScale Boost cache 可能比自管快）
• Vitess Connector stream 穩定
• Application 對 PlanetScale row read 量符合 cost forecast

Phase 3：Schema workflow 切 PlanetScale + write cutover

關鍵 paradigm shift：停 gh-ost / pt-osc、改用 PlanetScale branch workflow。

訓練步驟：

1. 第一個 small schema change 用 PlanetScale branch + Deploy Request 跑
2. 開發團隊熟悉 pscale branch create / pscale deploy-request create CLI
3. CI integration：把 PlanetScale CLI 加進 deploy pipeline
4. 退役 gh-ost / pt-osc CI integration

完成 schema workflow 訓練後 write cutover：

1# 1. PlanetScale 把 shadow cluster promote 為 primary（用 PlanetScale console / API）
2# 透過 PlanetScale Console 啟用 production write 或用 `pscale` CLI 對應 promotion 命令
3# （CLI 命令名稱隨 pscale 版本變動、以 pscale --help 為準）
4
5# 2. Application connection string 切 PlanetScale writer
6# 自管 → mysql://primary.example.com:3306/production
7# PlanetScale → mysql://...@xxx.connect.psdb.cloud/production?sslaccept=strict
8
9# 3. Vitess Connector 反向（PlanetScale → 自管）作為 rollback insurance

完成標準：寫入流量 100% 進 PlanetScale、自管 MySQL 接 PlanetScale binlog（rollback buffer）。

Phase 4：自管 MySQL 退役 / 保留作 rollback buffer

跟 Aurora migration Phase 4 同模式：

• 自管保留 30-90 天作 cold buffer
• 確認 PlanetScale cost forecast 跟 actual 一致（per-row read / write 計費可能超預期）
• 確認 branch workflow 在 production team 內 adopt（不是「PlanetScale 在用、但團隊還是用 gh-ost on staging」這種 stuck 狀態）

多數 org 在 Phase 3 停留更久（半年-一年）— Vitess Connector 反向 binlog ship 是穩定 rollback path、Phase 4 不急。

5 個 Production 踩雷

1. Cross-shard FK — PlanetScale 跟 native MySQL 行為不同

Vitess 18+ / PlanetScale 已支援 FK、但 cross-shard cascade 不執行。同 shard 內 FK 跟 native MySQL 一致；parent 跟 child 跨 shard 時、ON DELETE CASCADE 在 PlanetScale 不會跨 shard 觸發 child delete、結果 application 看到 orphan row。

修法：

• Phase 1 audit 出哪些 FK 跨 shard（Vindex 設計決定 parent / child 是否同 shard）
• 同 shard FK：直接保留、行為跟自管 MySQL 一致
• Cross-shard cascade：改 application 層 transaction 內 explicit DELETE child、或 background reconciliation job（定期掃 orphan）
• 把 parent / child 強制同 shard（用相同 Vindex column）是預防 cross-shard FK 議題的根本解

2. Deploy Request 思維轉換不到位 — 團隊仍用「跑 ALTER」心智模型

DBA / SRE 習慣 直接連 PlanetScale 跑 ALTER —但 PlanetScale 在 production branch 上 禁止 DDL（必須走 Deploy Request）。失敗訊息 not actionable（ERROR: not authorized）、DBA 找不到原因、production maintenance 卡住。

修法：

• Phase 3 訓練步驟 不能跳：找一個 small schema change 在 staging 走完整 branch workflow、團隊每個 DBA / SRE 都 hands-on 過
• 在 ops runbook 寫明 production schema change must go through Deploy Request、列 CLI 命令模板
• 緊急 schema change（事故中）也走 branch + Deploy Request、PlanetScale 可加速 Deploy（不能 bypass workflow）

3. Schema diff 邊界 — PlanetScale 看不到 application-level INSERT changes

Deploy Request 顯示 schema-level diff（CREATE / ALTER / DROP）、不顯示 data diff。如果 branch 上有 INSERT 進去（測試資料 / seed data）、merge 進 main 時 資料不會搬（只搬 schema）、application 預期有資料但 production 沒。

修法：

• 把 seed data INSERT 放 application migration / fixture、不在 PlanetScale branch 內
• 用 PlanetScale CLI export branch data 跟 import to main（手動操作）作為 escape hatch
• 教育團隊：PlanetScale branch = schema branch、不是 git-like data branch

4. Branch lifecycle ops cost — 100 個 stale branch

每個 PR 都開一個 PlanetScale branch、PR merge 後忘記刪、累積 100 個 stale branch。每個 branch 佔 storage cost、PlanetScale plan limit 也限制 branch 數量。

修法：

• CI integration：PR close 自動 pscale branch delete <branch-name>
• 設 branch retention policy（30 天無活動自動刪）
• 監控 pscale branch list | wc -l 數量、超 threshold alert
• 把 branch lifecycle 寫進 team playbook（不是 PlanetScale 教、是團隊內部規範）

5. 無 SUPER privilege — 部分操作不可行

PlanetScale connection 拿到的 MySQL user 沒有 SUPER privilege。需要 SUPER 的操作直接失敗：

• SET GLOBAL（不能改 runtime variable）
• KILL 別人的 query（PlanetScale console 提供 alt 介面）
• SHOW MASTER STATUS / SHOW SLAVE STATUS（PlanetScale 抽象掉、不暴露）
• INSTALL PLUGIN（managed、不允許）
• STOP SLAVE / START SLAVE（Vitess 內部）

修法：

• 評估 application 跟 ops tool 是否依賴 SUPER privilege
• 改用 PlanetScale console / API 等價操作
• 部分監控 query（SHOW SLAVE STATUS）用 PlanetScale 內建 dashboard 代替

Schema translation 主要工作量塊

雖然 Type E 結構不以 schema translation 為主、但 schema diff 在 Phase 1 仍佔多數時間：

容量與成本對照

PlanetScale 計費 很不同：

PlanetScale 適合 小-中規模 + high developer productivity priority：

• 流量 < 10K WPS：cost 接近自管、developer productivity 顯著提升
• 流量 10-50K WPS：cost 開始貴、但 ops saving 仍大於 cost increase
• 流量 > 100K WPS：PlanetScale Enterprise 議價、要 commit pricing

對 high-traffic 場景 cost forecast 必須跑 真實 workload trace — PlanetScale 提供 pscale analytics 預估 read / write 量、用 production binlog replay 在 staging 跑、估算 row read / write 計費。

何時不要遷

• FK 是 application core constraint：cascade DELETE / SET NULL 廣泛使用、application 改不動
• 大量 SUPER-required ops 自動化：DBA tools / monitoring 寫死 SUPER、改不動
• OS-level customization 需求：跟 Aurora 一樣、PlanetScale 完全 managed
• 流量極大 + 預算敏感：> 100K WPS row read 計費可能比 EC2 貴 5x、需要 Enterprise commit pricing
• 跨雲 portability 是 requirement：PlanetScale 跑在自家 cloud（背後 AWS / GCP）、不像自管 Vitess 可跨雲

跟 Aurora MySQL 對比（同 batch 的選擇）

選擇邏輯：

• AWS-heavy ecosystem + 不想 schema workflow paradigm shift → Aurora
• Developer-first culture + 想 branch-based schema workflow + 接受 FK 限制 → PlanetScale

兩者不互斥、有 org 用 Aurora 給 OLTP core、PlanetScale 給 newer microservices（branch workflow 帶價值）。

相關連結

• 平行 batch：→ Aurora MySQL migration playbook（同 batch、不同 paradigm）
• 上游：MySQL vendor overview / Vitess sharding 設計
• 跨章節：6.13 Performance Regression Gate — Deploy Request workflow 對 release gate 的影響
• 既有 vendor 對照：Aurora vendor page / PlanetScale 官方
• 方法論：Migration Playbook Methodology（Type E paradigm shift 結構說明）
• 官方：PlanetScale Migration Guide

本文是跨 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