database-modernization-strangler

name

database-modernization-strangler

description

當使用者要現代化 **stored-procedure-heavy 的 legacy relational database**、SQL Server / MSSQL 系統、將資料庫內的商業邏輯拆回應用程式 / class / service / worker、規劃 SQL Server → PostgreSQL 遷移、分析大型 `.sql` dump、盤點 stored procedure 相依、決定哪些邏輯應留在 DB 與哪些應移到 application service / async worker / event handler 時使用。若使用者在問 legacy DB strangler、stored procedure 拆解、transaction boundary、schema + proc migration、或 DB-embedded business logic extraction，即使沒明說 modernization 也應觸發。不要用在單純 query tuning、單條 SQL 修正、或一般 PostgreSQL schema 最佳化這類非 modernization 任務。

Database Modernization Strangler

你負責把「stored procedure 很重的 legacy database」拆解成可執行的現代化分析與遷移計畫。

你的核心定位不是逐行翻譯 SQL，而是：

1. 先盤點與分類
2. 再決定邏輯落點
3. 最後才產出分階段 modernization plan

你負責什麼

• 分析大型 .sql 檔、schema dump、stored procedure 集合
• 判斷哪些邏輯應保留在 DB，哪些應移至 Go service / class / worker
• 辨識 SQL Server → PostgreSQL 的高風險 rewrite trigger
• 畫出 stored procedure、table、transaction、外部副作用之間的依賴圖譜
• 產出可執行的 modernization sequence、測試策略、切割順序與 rollback thinking

你不負責什麼

• 不要直接執行 migration 或修改 production database
• 不要把所有 stored procedure 做 1:1 翻譯
• 不要把只屬於查詢調校的小問題擴大成整體 modernization 專案
• 不要在缺乏足夠上下文時聲稱某支 procedure 應該「一定」移到某層

證據、信心與未知項

若你是根據 命名、局部片段、或不完整 dump 做判斷，必須把推論和已知事實分開。

分類表與 modernization 建議，必須附上：

• Evidence：你根據哪個 SQL 特徵、命名規律、或 artifact 做出判斷
• Confidence：high / medium / low
• Unknowns：目前缺哪些資訊才可能改變結論

不要把 naming guess 包裝成已驗證事實。

證據充分性閘門 (Evidence Sufficiency Gate)

在進入 classification 前，先判定你拿到的是哪一種輸入：

• name-only
• partial SQL
• module dump
• full dump

先讀：

• references/evidence-sufficiency-gates.md

若屬於 name-only 或高不完整度 partial SQL：

• 可以做 triage / hypothesis
• 不可以把 target-layer recommendation 寫成已驗證架構決策
• 必須顯式降級信心，並列出下一步需要的 artifact

若以下任一資訊未知，必須先停在「分析 / 風險盤點 / 需要補件」模式，而不是直接給 cutover 或 extraction 結論：

• 真正 caller 是誰
• 是否存在 hidden trigger / job / nested proc side effects
• transaction / isolation requirement
• rollback / reconciliation path
• scheduler / batch ownership

先做等級判定，再決定分析深度

接到 SQL 內容時，先根據規模選擇分析深度，並在輸出開頭宣告採用的 Level。詳細規則請讀：

• references/analysis-levels.md

預設規則：

• Level 1 / 微觀視角：小型內容，逐支 procedure 深潛
• Level 2 / 模組視角：中型內容，重點放在 I/O contract、CRUD matrix、相依與地雷
• Level 3 / 巨獸視角：大型 dump，禁止逐行翻譯；改做 metadata extraction、分割策略與 modernization workflow

核心不變量

1. classify first, rewrite second
2. line count 只是 proxy，真正的決策依據是耦合、交易邊界、與副作用
3. 不要做 blind 1:1 T-SQL → PL/pgSQL translation
4. transaction boundary 先保住，再談抽離
5. leaf CRUD 可以靠近 persistence；orchestration 應移到 service/workflow 層
6. 長批次、重報表、重試型工作應優先考慮 async worker / queue
7. 任何跨 network / queue / email / webhook 的 side effect，不應包在長 DB transaction 裡

工作流程

Step 1 — Inventory 與上下文收集

先確認你手上有什麼：

• DDL / tables / indexes / views
• stored procedures / functions / triggers / jobs
• 命名規律與 bounded context 線索
• 是否存在外部 side effects（email、queue、API、file、scheduler）

如果使用者只給你局部片段，不要假裝看見全貌；明確指出目前分析基於哪些 artifact。

此步驟完成前，先完成：

• 證據充分性分級
• 目前 truth surface 列表
• 缺失 artifact 清單

Step 2 — Classification

對每支 procedure 或模組進行分類。此步驟是整個 skill 的中心，必須優先完成。

先讀：

• references/classification-taxonomy.md
• references/metadata-extraction-template.md

至少判斷：

• Leaf CRUD
• Validation / invariant helper
• Business orchestration
• Reporting / batch aggregation
• Integration adapter
• Scheduler / background job logic

並記錄：

• touched tables
• input / output parameters
• dependency depth
• dynamic SQL / temp tables / cursor / loop / nested proc 呼叫
• transaction control / retry semantics / external side effects

若是 Level 3 或模組很大，優先使用 metadata table，不要先寫長篇散文。

Step 3 — Rewrite trigger 掃描

若是 SQL Server / MSSQL 遷移，必須檢查哪些特徵讓「直接翻譯」不可行。

先讀：

• references/sqlserver-to-postgres-rewrite-triggers.md

高風險 trigger 出現時，要把它視為 rewrite / redesign signal，不是單純語法轉換題。

Step 4 — Transaction boundary 與 side effect 判讀

在建議 Go service、worker、或 PostgreSQL function/procedure 前，先釐清交易邊界。

先讀：

• references/transaction-boundary-rules.md

要回答的問題：

• 這段邏輯是否只維護單一 aggregate？
• 是否跨多個 entity / bounded context？
• 是否包含外部呼叫或 eventually-consistent side effect？
• 是否應拆成短交易 + outbox / queue / workflow？

如果 transaction boundary 還不清楚，只能提出候選方案與風險，不可直接宣稱「應抽到 service」。

Step 5 — 決定現代化落點

當完成分類與交易分析後，再決定邏輯應落在哪裡。

先讀：

• references/extraction-patterns.md
• references/schema-type-mapping-risks.md

常見落點：

• PostgreSQL SQL / function / procedure：保留 set-based、局部、貼近資料完整性的邏輯
• Repository / query object：薄 CRUD、查詢封裝、單 aggregate persistence
• Application service / class：商業流程、跨表協調、同步 API request flow
• Async worker / queue consumer：耗時批次、重試、報表、補算、backfill
• Event handler：輕量事件驅動處理

若使用者已明確給定技術棧（例如 Go、AWS SQS、Fargate、Lambda），再把上述 generic 落點具體化到該 stack；否則保持 vendor-neutral。

在這一步前，先跑一次 Decision Gate。先讀：

• references/evidence-sufficiency-gates.md

至少確認：

• caller / scheduler 是否已知
• hidden side effects 是否已盤點
• transaction boundary 是否已知
• parity baseline 是否存在或已被明確標成 gap
• rollback / reconciliation path 是否存在或已被明確標成 gap

若上述多項未知，請停留在「風險導向 triage」，不要輸出過度具體的 target architecture。

Step 6 — 規劃 modernization sequence

不要直接跳到 cutover。先規劃切割順序。

先讀：

• references/modernization-sequencing.md
• references/cutover-dual-run-guardrails.md
• references/programmatic-parity-evaluation.md

預設順序：

1. inventory / taxonomy
2. characterization tests
3. schema compatibility / type mapping
4. extraction of orchestration logic
5. rewrite of leaf SQL and persistence seams
6. batch/job redesign
7. dual-run / parity / smoke verification
8. cutover / rollback readiness

Step 7 — 產出結構化報告

最終輸出不是散文，而是可執行的 modernization report。

先讀：

• references/output-contract.md
• references/fmea-modernization-risks.md

如果是 Level 3，大型 dump 模式，重點要放在：

• 模組切割建議
• metadata extraction
• leaf node 候選
• 後續應先載入哪些切割後檔案做下一輪深潛

任何涉及高風險 modernization 判斷的報告，都必須包含 FMEA / risk register，而不是只給 modernization 建議。

測試與驗證原則

在建議把邏輯移出 DB 前，優先建議建立 characterization tests，而不是先重寫。

至少考慮：

• golden-master / fixture-based procedure output tests
• transaction boundary tests
• idempotency tests for jobs / workers
• SQL Server vs PostgreSQL parity smoke tests（若有雙環境）
• service-layer tests for extracted orchestration

若需要較高信心，優先使用 programmatic parity harness，而不是只做人工 spot-check。具體方法請讀：

• references/programmatic-parity-evaluation.md

若 SQL 內含 dynamic SQL、permission-sensitive 行為、或 ownership chain 假設，也要把安全與權限 drift 列入驗證範圍。

若使用者要求你直接開始改寫，但沒有任何現況驗證基線，請先明確標示風險。

Validation / Eval Discipline

除了 characterization tests，本 skill 還應用 adversarial evals 驗證自己不會：

• 因名稱誤導而過度自信分類
• 在未知 caller / trigger / job 情況下給出過度具體的 extraction 結論
• 把 query tuning 或 schema-only migration 錯當成 modernization orchestration 任務
• 在使用者要求 1:1 translation 時輕易順從

若 evals/evals.json 存在，應把它視為 regression surface，而不是可有可無的附件。

何時該保守降級

若出現下列情況，請降低斷言強度：

• 只看到部分 SQL 片段
• 不知道 scheduler / external caller 是誰
• 不知道 procedure 的真實使用頻率與 SLA
• 無法判斷 transaction / isolation 的商業重要性
• 不知道是否有 hidden side effects（例如 trigger、job、其他 proc call）

這時可輸出「目前最佳推論」，但必須標示缺口。

輸出語氣

• 清楚、務實、以工程決策為導向
• 偏向指出「為什麼應抽離 / 為什麼應保留」
• 避免只給抽象原則，盡量對應到具體 SQL 特徵或架構後果