SOAR 101 快速入門指南

soar開源兩週以來，在Github獲得了社群2700+顆星的支援，這期間有很多的開源社群同學參與到soar的成長當中，為我們提供了許多優秀的意見和建議。

我們希望能夠有更多的人來感受一下這款“SQL優化神器”能夠帶給你的方便和快捷，這篇文章將會對soar可以提供的功能以及一些使用場景做出介紹，並給出相關用例。

echo "select title from sakila.film" | ./soar -log-output=soar.log複製程式碼

soar可以通過管道的方式接受傳入的SQL，也可以通過-query的方式來傳入SQL或指定輸入源。使用方式示例如下：

# 從檔案讀取SQL 
./soar -query file.sql

# 從管道讀取SQL 
cat file.sql | ./soar複製程式碼

在日常使用的時候，如果您是為了快速獲得簡單SQL的評審結果，可以用命令列方式進行傳入。但我們建議使用檔案的方式進行傳入，來避免可能存在的轉義問題。

在之前的系列文章中我們提到了配置檔案的重要性，配置的正確性決定了soar的服務質量。使用者可以通過以下案例的方式來編輯soar的配置檔案。在不指定配置檔案的情況下，soar預設會從依次檢查/etc/soar.yaml，./etc/soar.yaml以及./soar.yaml這三個路徑，配置檔案優先順序依次遞減。

vi soar.yaml 
# yaml format config file 
online-dsn:
  addr: 127.0.0.1:3306
  schema: sakila
  user: root 
  password: "1t`sB1g3rt" 
  disable: falsetest-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`sB1g3rt@127.0.0.1:3306/sakila" -allow-online-as-test -log-output=soar.log複製程式碼

但通過命令列的方式輸入配置可能會存在轉義的問題，您也可以使用-config的方式來指定您需要的配置檔案。

echo "select title from sakila.film" | ./soar -config=mysoar.yaml -allow-online-as-test -log-output=soar.log複製程式碼

您可以通過-list-heuristic-rules的方式來檢視目前soar支援的全部啟發式規則建議，預設輸出的是markdown格式的文件，您可以重定向到一個檔案中進行檢視，soar提供的啟發式建議的相關文件就是通過這一方式生成的。

$ soar -list-heuristic-rules複製程式碼

soar中是可以通過配置-ignore-rules的方式來忽略某些建議的輸出。可以用正則的方式來進行全域性匹配，也可以指定某個特定的規則item來進行精準遮蔽，多條規則之間用逗號分離。

$ soar -ignore-rules "ALI.001,IDX.*"複製程式碼

soar支援多種輸出方式，預設情況下為markdown格式的輸出，您可以根據需要設定您的輸出方式，比如json，比如html等。

$ soar -report-type json複製程式碼

-reprot-type除了可以調整輸出格式，某些特定的功能也是以-report-type的方式來提供的。比如SQL重寫，比如fingerprint等。與檢視啟發式規則一樣，想要檢視soar支援的全部-report-type，可以通過-list-report-types的方式來檢視支援的全部使用方式。

$ soar -list-report-types複製程式碼

雖然soar的功能非常豐富，但是在某些特定情況下，比如寫了一條SQL卻並不能肯定語法是否是正確的，那麼可以通過soar提供的語法檢查工具來對SQL語法進行檢查，此時只會檢查語法的正確性而不會進行一步的評審。

$ echo "select * from tb" | soar -only-syntax-check 
$ echo $?0$ echo "select * fromtb" | soar -only-syntax-check
At SQL 0 : syntax error at position 16 near `fromtb`$ echo $? 
1複製程式碼

soar提供了一定的基於抽象語法樹實現的SQL重寫能力。雖然現在這一個功能尚處於研發測試階段，但是某些小的功能已經相對比較完善了，以下舉例幾個簡單地重寫使用場景。

在某些情況下，我們需要對非查詢語句進行效能分析，為了保證安全，我們可以先通過soar將這些語句轉化成等價的select語句，在對這些查詢語句進行進一步分析。

$ echo "update film set title = `abc`" | soar -rewrite-rules dml2select,delimiter -report-type rewrite複製程式碼

輸出

select * from film;複製程式碼

當線上資料庫環境需要需要進行更新操作時，為了讓某些線上改表工具正確的執行，我們應該將同一張表的多條alter語句合併為一條。soar提供了這樣的功能來方便研發人員或DBA進行合併。

$ 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 ;複製程式碼

有時我們獲取到了EXPLAIN資訊，但可能對於MySQL EXPLAIN的內容不熟悉。您可以將mysql輸出的EXPLAIN資訊交給soar，來幫助輔助解讀其中的資訊。這裡傳入的explain可以是普通的表格，也可以是MySQL的JSON格式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複製程式碼

預設輸出結果為markdown格式。

## 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工具，soar也自帶了markdown轉html這樣的功能，儘可能的讓所有人都能感受到soar原生報告的優雅。你還可以通過指定-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複製程式碼