小米開源工具SOAR&SOAR-WEB

一、簡介

1.1 SOAR

  SOAR 是一個對 SQL 進行優化和改寫的自動化工具。 由小米人工智能與雲平臺的數據庫團隊開發與維護。

下載地址：
https://github.com/XiaoMi/soar/releases/download/0.11.0/soar.linux-amd64

1.1.1 功能特點

• 跨平臺支持（支持 Linux, Mac 環境，Windows 環境理論上也支持，不過未全面測試）
• 目前只支持 MySQL 語法族協議的 SQL 優化
• 支持基於啓發式算法的語句優化
• 支持複雜查詢的多列索引優化（UPDATE, INSERT, DELETE, SELECT）
• 支持 EXPLAIN 信息豐富解讀
• 支持 SQL 指紋、壓縮和美化
• 支持同一張表多條 ALTER 請求合併
• 支持自定義規則的 SQL 改寫

1.1.2 產品對比

1.2 SOAR-WEB

  基於小米 soar 的開源 sql 分析與優化的 web 圖形化工具，支持 soar 配置的添加、修改、複製，多配置切換，配置的導出、導入與導入功能。

下載地址：
https://codeload.github.com/xiyangxixian/soar-web/zip/master

二、基本使用

2.1 SOAR

2.1.1 體系結構

2.1.2 配置文件說明

  配置文件爲yaml格式。一般情況下只需要配置online-dsn, test-dsn, log-output等少數幾個參數。即使不創建配置文件SOAR仍然會給出基本的啓發式建議。
  默認文件會按照/etc/soar.yaml, ./etc/soar.yaml, ./soar.yaml順序加載，找到第一個後不再繼續加載後面的配置文件。如需指定其他配置文件可以通過-config參數指定。
  關於數據庫權限online-dsn需要相應庫表的SELECT權限，test-dsn需要root最高權限。

# 線上環境配置
online-dsn:
  addr: 127.0.0.1:3306
  schema: sakila
  user: root
  password: 1t'sB1g3rt
  disable: false
# 測試環境配置
test-dsn:
  addr: 127.0.0.1:3307
  schema: test
  user: root
  password: 1t'sB1g3rt
  disable: false
# 是否允許測試環境與線上環境配置相同
allow-online-as-test: true
# 是否清理測試時產生的臨時文件
drop-test-temporary: true
# 語法檢查小工具
only-syntax-check: false
sampling-statistic-target: 100
sampling: false
# 日誌級別，[0:Emergency, 1:Alert, 2:Critical, 3:Error, 4:Warning, 5:Notice, 6:Informational, 7:Debug]
log-level: 7
log-output: ${your_log_dir}/soar.log
# 優化建議輸出格式
report-type: markdown
ignore-rules:
- ""
# 黑名單中的 SQL 將不會給評審意見。一行一條 SQL，可以是正則也可以是指紋，填寫指紋時注意問號需要加反斜線轉義。
blacklist: ${your_config_dir}/soar.blacklist
# 啓發式算法相關配置
max-join-table-count: 5
max-group-by-cols-count: 5
max-distinct-count: 5
max-index-cols-count: 5
max-total-rows: 9999999
spaghetti-query-length: 2048
allow-drop-index: false
# EXPLAIN相關配置
explain-sql-report-type: pretty
explain-type: extended
explain-format: traditional
explain-warn-select-type:
- ""
explain-warn-access-type:
- ALL
explain-max-keys: 3
explain-min-keys: 0
explain-max-rows: 10000
explain-warn-extra:
- ""
explain-max-filtered: 100
explain-warn-scalability:
- O(n)
query: ""
list-heuristic-rules: false
list-test-sqls: false
verbose: true

2.1.3 命令行參數

  幾乎所有配置文件中指定的參數都通通過命令行參數進行修改，且命令行參數優先級較配置文件優先級高。

soar -h

2.1.4 啓動

wget https://github.com/XiaoMi/soar/releases/download/0.9.0/soar.linux-amd64 -O soar
chmod a+x soar
開發調試
如下指令如果您沒有精力參與SOAR的開發可以跳過。

make deps 依賴檢查
make vitess 升級Vitess Parser依賴
make tidb 升級TiDB Parser依賴
make fmt 代碼格式化，統一風格
make lint 代碼質量檢查
make docker 啓動一個MySQL測試容器，可用於測試依賴元數據檢查的功能或不同版本MySQL差異
make test 運行所有的測試用例
make cover 代碼測試覆蓋度檢查
make doc 自動生成命令行參數中-list-XX相關文檔
make daily 每日構建，時刻跟進Vitess, TiDB依賴變化
make release 生成Linux, Windows, Mac發佈版本
安裝驗證
echo 'select * from film' | ./soar

2.1.5 常用命令

vi soar.yaml
# yaml format config file
online-dsn:
    addr:     127.0.0.1:3306
    schema:   sakila
    user:     root
    password: "1t'sB1g3rt"
    disable:  false

test-dsn:
    addr:     127.0.0.1:3306
    schema:   sakila
    user:     root
    password: "1t'sB1g3rt"
    disable:  false
echo "select title from sakila.film" | ./soar -test-dsn="root:1t'[email protected]:3306/sakila" -allow-online-as-test -log-output=soar.log

打印所有的啓發式規則
soar -list-heuristic-rules

忽略某些規則
soar -ignore-rules "ALI.001,IDX.*"

打印支持的報告格式
soar -list-report-types

以指定格式輸出報告
soar -report-type json

語法檢查工具
echo "select * from tb" | soar -only-syntax-check
echo $?
0

echo "select * frm tb" | soar -only-syntax-check
At SQL 1 : syntax error at position 13 near 'frm'
echo $?
1

慢日誌進行分析示例
pt-query-digest slow.log > slow.log.digest
# parse pt-query-digest's output which example script
python2.7 doc/example/digest_pt.py slow.log.digest > slow.md

SQL指紋
echo "select * from film where col='abc'" | soar -report-type=fingerprint
輸出
select * from film where col=?

將 UPDATE/DELETE/INSERT 語法轉爲 SELECT
echo "update film set title = 'abc'" | soar -rewrite-rules dml2select,delimiter  -report-type rewrite
輸出
select * from film;

合併多條ALTER語句
echo "alter table tb add column a int; alter table tb add column b int;" | soar -report-type rewrite -rewrite-rules mergealter
輸出
ALTER TABLE `tb` add column a int, add column b int ;

SQL美化
echo "select * from tbl where col = 'val'" | ./soar -report-type=pretty
輸出
SELECT
  *
FROM
  tbl
WHERE
  col  = 'val';
  
EXPLAIN信息分析報告
soar -report-type explain-digest << EOF
+----+-------------+-------+------+---------------+------+---------+------+------+-------+
| id | select_type | table | type | possible_keys | key  | key_len | ref  | rows | Extra |
+----+-------------+-------+------+---------------+------+---------+------+------+-------+
|  1 | SIMPLE      | film  | ALL  | NULL          | NULL | NULL    | NULL | 1131 |       |
+----+-------------+-------+------+---------------+------+---------+------+------+-------+
EOF
##  Explain信息

| id | select\_type | table | partitions | type | possible_keys | key | key\_len | ref | rows | filtered | scalability | Extra |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 1  | SIMPLE | *film* | NULL | ALL | NULL | NULL | NULL | NULL | 0 | 0.00% | ️ **O(n)** |  |


Explain信息解讀

SelectType信息解讀
* **SIMPLE**: 簡單SELECT(不使用UNION或子查詢等).
Type信息解讀

* ️ **ALL**: 最壞的情況, 從頭到尾全表掃描.

markdown 轉 HTML
通過指定-report-css, -report-javascript, -markdown-extensions, -markdown-html-flags這些參數，你還可以控制HTML的顯示格式。

cat test.md | soar -report-type md2html > test.html

清理測試環境殘餘的臨時庫表
如配置了-drop-test-temporary=false或soar異常中止，-test-dsn中會殘餘以optimizer_爲前綴的臨時庫表。手工清理這些庫表可以使用如下命令。

注意：爲了不影響正在進行的其他SQL評審，-cleanup-test-database中會刪除1小時前生成的臨時庫表。
./soar -cleanup-test-database

2.2 SOAR-WEB

2.2.1 環境需求

python3.x
Flask
pymysql
pycryptodome
pip install -r requirement.txt
注：若 Crypto 模塊找不到, 則需要在 python 的依賴庫目錄 Lib\site-packages 中將 crypto 重命名爲 Crypto 。

解壓縮（ Windows 可略過此步驟）：
sudo -y apt-get install unzip 或者 sudo yum -y install unzip 
unzip soar-web.zip
cd soar-web-matster

2.2.2 啓動

運行啓動腳本：
Windows： run.bat
Linux or Mac： bash run.sh

守護進程支持：
啓動服務：bash manage.sh start
關閉服務：bash manage.sh stop
重啓服務：bash manage.sh restart
注：當主機上存在多個 python 版本時, 需更改 run.sh, run.bat, manage.sh 中的 python 版本指定爲 3.x 的版本運行。

在瀏覽器上輸入 http://IP:5077 進行訪問。
如果需要改 IP 地址和端口號, 可在 config.py 中進行修改。

存儲： 
所有的配置都是保存在瀏覽器 Local Storage 中的，多人之間使用是互不影響的，自己只能看到自己的配置，更換瀏覽器或者清除瀏覽器會造成配置丟失。

數據庫連接：
數據庫連接成功後，soar 可以通過表結構提供更正確優質的 sql 評估建議， 配置的正確性決定了 soar 的服務質量。

線上線下環境問題：
線上環境作爲待 sql 評估環境，soar 在進行 sql 評估時，會根據 sql 語句，從 線上環境的數據庫連接實例 拷貝數據表到 測試環境的數據庫連接實例，然後在測試環境下執行 sql 語句進行分析。因此測試環境的數據庫連接實例需要有最高權限。如果沒有最高權限可能造成一些問題，如果沒有權限可以啓動一個空的 mysql docker 容器作爲測試環境。如果僅僅做測試用，可將線上線下環境指定爲一樣。

參考文檔

https://github.com/XiaoMi/soar
https://github.com/xiyangxixian/soar-web