SQL 格式化工具 — MySQL、PostgreSQL、BigQuery、Snowflake 線上

蝦皮 Shopee 的資料工程團隊橫跨新加坡與台北，透過 dbt 管理龐大的 BigQuery 資料倉儲。當一名工程師手動排版 200 行 CTE，另一位卻以單行貼回，diff 立刻爆出大量空白雜訊，遮蓋了真正的邏輯變更。中信金控在 Snowflake 資料倉儲專案中要求所有提交的查詢在 commit 前先過 sql-formatter，確保 PR 差異僅反映商業邏輯而非排版差異。91APP 的 BigQuery 電商分析管線同樣採用格式化作為 pre-commit hook，讓 dbt 模型審查聚焦在轉換邏輯而非縮排爭議，大幅縮短 review 循環。

SQL 格式化的運作原理

SQL 格式化是一種由詞法分析器驅動的重寫過程，會走訪查詢中的每個 token，並根據所選方言的規則重新輸出其周圍的空白。查詢語意從不改變，只有排版佈局不同。

選擇方言. MySQL 的反引號、PostgreSQL 的 :: 型別轉換、BigQuery 的點分隔表格路徑、T-SQL 的方括號識別碼——各自都需要能識別它們的分詞器。方言選擇器決定套用哪種語法規則。
對輸入進行分詞. 格式化工具將查詢拆分成 token 串流：關鍵字（SELECT、JOIN）、識別碼、字面值、運算子、括號及註解。字串字面值與加引號的識別碼會原樣傳遞，以確保方言特定語法正常運作。
套用版面規則. 頂層子句（SELECT、FROM、WHERE、GROUP BY、ORDER BY）各自從新行開始。選擇清單與欄位清單中以逗號分隔的運算式各佔一行，並以所選縮排單位縮排。
套用關鍵字大小寫. 關鍵字大小寫切換會將已識別的 SQL 關鍵字改寫為大寫、小寫，或原樣保留輸入的大小寫。識別碼從不受影響——欄位名稱與資料表名稱一律依照原始寫法輸出。
輸出格式化字串. token 串流會以縮排字元（2 個空格、4 個空格或定位字元）與所設定的換行規則重新拼接成單一字串。即時模式會在輸入時以 200 毫秒去抖動重新執行整個處理流程。

為何要美化輸出 SQL

Pull-request diff 的可讀性. 將 200 行 CTE 改寫成單行，會讓 code review 變成猜謎遊戲。一致的格式化能將 diff 限縮在你實際做的變更——新增欄位、額外的 JOIN、不同的 WHERE 條件——讓 reviewer 無需解開空白糾纏就能看清楚。
更容易除錯. 當查詢回傳錯誤的列數時，第一步就是逐行閱讀。格式化後的 SQL 會將每個 JOIN 放在獨立行，對齊 WHERE 條件，讓遺漏的 AND 或誤入的 OR 一眼就能看出。
一致的團隊風格. 大多數團隊會採用 SQL 風格指南（dbt Labs、GitLab、Mode Analytics 都有發布自己的版本），並希望每筆提交的查詢都遵循它。commit 前執行格式化，可將風格爭議從 review 中移除，只留下邏輯部分討論。
在文件中分享 SQL. Runbook、事件回顧與 Notion 文件都能從由上而下易讀的 SQL 中受益。格式化後的 SQL 能乾淨地貼入圍欄程式碼區塊，並在 PDF 匯出時整齊列印，不會在關鍵字中間出現尷尬的換行。

常見應用場景

每當查詢需要由非原作者閱讀時，SQL 格式化就會出現在分析工程、後端開發與維運工作中。

分析工程：在 dbt 專案中設置 pre-commit hook，自動重新格式化每個模型檔案，確保 PR diff 僅反映邏輯變更而非空白調整。
資料庫管理：貼上單行的慢查詢日誌條目，格式化後在撰寫事件回顧時逐一檢視 join 順序。
文件撰寫：從 Looker explore 或 Tableau workbook 取出查詢，格式化後放入 runbook，作為值班輪換可直接複製貼上的範例。

實際操作範例

將 SELECT u.id,u.email,COUNT(o.id) FROM users u LEFT JOIN orders o ON o.user_id=u.id WHERE u.created_at > '2024-01-01' GROUP BY u.id,u.email ORDER BY u.id; 貼入輸入窗格，方言設為 PostgreSQL、縮排 2 個空格、關鍵字大小寫設為大寫。輸出會將 SELECT、FROM、LEFT JOIN、WHERE、GROUP BY 和 ORDER BY 各自放在獨立行；選擇清單與 group-by 清單中的每個欄位各佔一行縮排；ON 條件比所屬的 JOIN 關鍵字再深一個縮排層級。

FAQ

支援哪些 SQL 方言？

方言下拉選單涵蓋：標準 SQL、MySQL、PostgreSQL、SQLite、MariaDB、Transact-SQL（SQL Server / Azure SQL）、BigQuery、Snowflake 和 Redshift。底層 sql-formatter 程式庫也能識別 DuckDB、Spark SQL、Hive、Trino、Db2、N1QL、PL/SQL、ClickHouse、TiDB 和 SingleStoreDB——即使確切目標不在列表中，選擇最接近的方言也能產出合理的輸出。識別碼、字串字面值與方言特定運算子（PostgreSQL @>、BigQuery SAFE. 前綴）均原樣保留。

這個工具會驗證我的 SQL 嗎？

不會。格式化工具是詞法重寫器，不是解析器。它對輸入進行分詞、套用版面規則並輸出結果；不會檢查查詢是否語意正確、參照的資料表是否存在，或語法在所選方言中是否合法。請透過實際資料庫（或 SQLFluff 等 SQL linter）執行格式化後的輸出以進行真正的正確性檢查。

為什麼我的關鍵字被改成大寫？

關鍵字大小寫下拉選單預設為大寫，這是大多數已發布 SQL 風格指南（dbt Labs、Mode、GitLab）的慣例。如果你的團隊以小寫寫 select / from，請切換至 小寫；若希望輸出保留你輸入的大小寫，請選 保留原樣。識別碼從不受影響——只有已識別的關鍵字集合才會被改寫。

我的查詢會上傳到任何地方嗎？

不會。隨附的 sql-formatter 程式庫在你的瀏覽器中執行，格式化在你的本機進行，查詢文字絕不經過網路傳輸。此頁面唯一的對外請求，是 tools.ultim8soft.com 上每個頁面都會發出的相同共用分析與廣告請求；SQL 文字本身不屬於其中任何一項。

一旦格式化工具接手，美化輸出 SQL 就不再是風格爭議。此工具完全在你的瀏覽器中執行，查詢絕不離開頁面，而驅動 sql-formatter npm 套件的同款方言感知詞法分析器負責重寫工作。

格式化 SQL 查詢 _

// 相關工具