From 35977667104d0a6b378d714c268f9870ebf3f107 Mon Sep 17 00:00:00 2001 From: martianzhang Date: Wed, 14 Nov 2018 14:22:29 +0800 Subject: [PATCH] update doc --- doc/cheatsheet.md | 46 ++++++++++++++++++++------------------------ doc/cheatsheet_en.md | 36 ++++++++++++++++------------------ doc/comparison.md | 1 - doc/comparison_en.md | 1 - doc/config.md | 11 ++++++----- doc/editor_plugin.md | 2 +- doc/install.md | 4 ++-- doc/install_en.md | 4 ++-- 8 files changed, 49 insertions(+), 56 deletions(-) diff --git a/doc/cheatsheet.md b/doc/cheatsheet.md index 24b7dc3..083a001 100644 --- a/doc/cheatsheet.md +++ b/doc/cheatsheet.md @@ -1,7 +1,7 @@ -[toc] - # 常用命令 +[toc] + ## 基本用法 ```bash @@ -45,54 +45,52 @@ echo "select title from sakila.film" | ./soar -test-dsn="root:1t'sB1g3rt@127.0.0 ## 打印所有的启发式规则 ```bash -$ soar -list-heuristic-rules +soar -list-heuristic-rules ``` ## 忽略某些规则 ```bash -$ soar -ignore-rules "ALI.001,IDX.*" +soar -ignore-rules "ALI.001,IDX.*" ``` ## 打印支持的报告格式 ```bash -$ soar -list-report-types +soar -list-report-types ``` ## 以指定格式输出报告 ```bash -$ soar -report-type json +soar -report-type json ``` ## 语法检查工具 ```bash -$ echo "select * from tb" | soar -only-syntax-check -$ echo $? +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 $? +echo "select * frm tb" | soar -only-syntax-check +At SQL 1 : syntax error at position 13 near 'frm' +echo $? 1 - ``` ## 慢日志进行分析示例 ```bash -$ pt-query-digest slow.log > slow.log.digest +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 +python2.7 doc/example/digest_pt.py slow.log.digest > slow.md ``` - ## SQL指纹 ```bash -$ echo "select * from film where col='abc'" | soar -report-type=fingerprint +echo "select * from film where col='abc'" | soar -report-type=fingerprint ``` 输出 @@ -101,10 +99,10 @@ $ echo "select * from film where col='abc'" | soar -report-type=fingerprint select * from film where col=? ``` -## 将UPDATE/DELETE/INSERT语法转为SELECT +## 将 UPDATE/DELETE/INSERT 语法转为 SELECT ```bash -$ echo "update film set title = 'abc'" | soar -rewrite-rules dml2select,delimiter -report-type rewrite +echo "update film set title = 'abc'" | soar -rewrite-rules dml2select,delimiter -report-type rewrite ``` 输出 @@ -113,11 +111,10 @@ $ echo "update film set title = 'abc'" | soar -rewrite-rules dml2select,delimite select * from film; ``` - ## 合并多条ALTER语句 ```bash -$ echo "alter table tb add column a int; alter table tb add column b int;" | soar -report-type rewrite -rewrite-rules mergealter +echo "alter table tb add column a int; alter table tb add column b int;" | soar -report-type rewrite -rewrite-rules mergealter ``` 输出 @@ -129,7 +126,7 @@ ALTER TABLE `tb` add column a int, add column b int ; ## SQL美化 ```bash -$ echo "select * from tbl where col = 'val'" | ./soar -report-type=pretty +echo "select * from tbl where col = 'val'" | ./soar -report-type=pretty ``` 输出 @@ -146,7 +143,7 @@ WHERE ## EXPLAIN信息分析报告 ```bash -$ soar -report-type explain-digest << EOF +soar -report-type explain-digest << EOF +----+-------------+-------+------+---------------+------+---------+------+------+-------+ | id | select_type | table | type | possible_keys | key | key_len | ref | rows | Extra | +----+-------------+-------+------+---------------+------+---------+------+------+-------+ @@ -174,12 +171,12 @@ EOF * ☠️ **ALL**: 最坏的情况, 从头到尾全表扫描. ``` -## markdown转HTML +## markdown 转 HTML 通过指定-report-css, -report-javascript, -markdown-extensions, -markdown-html-flags这些参数，你还可以控制HTML的显示格式。 ```bash -$ cat test.md | soar -report-type md2html > test.html +cat test.md | soar -report-type md2html > test.html ``` ## 清理测试环境残余的临时库表 @@ -191,4 +188,3 @@ $ cat test.md | soar -report-type md2html > test.html ```bash ./soar -cleanup-test-database ``` - diff --git a/doc/cheatsheet_en.md b/doc/cheatsheet_en.md index dc9ba76..50dda2a 100644 --- a/doc/cheatsheet_en.md +++ b/doc/cheatsheet_en.md @@ -1,7 +1,8 @@ -[toc] # Useful Commands +[toc] + ## Basic suggest ```bash @@ -35,36 +36,36 @@ echo "select title from sakila.film" | ./soar -test-dsn="root:1t'sB1g3rt@127.0.0 ## List supported heuristic rules ```bash -$ soar -list-heuristic-rules +soar -list-heuristic-rules ``` ## Ignore Rules ```bash -$ soar -ignore-rules "ALI.001,IDX.*" +soar -ignore-rules "ALI.001,IDX.*" ``` ## List supported report-type ```bash -$ soar -list-report-types +soar -list-report-types ``` ## Set report-type for output ```bash -$ soar -report-type json +soar -report-type json ``` ## Syntax Check ```bash -$ echo "select * from tb" | soar -only-syntax-check -$ echo $? +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 "select * frm tb" | soar -only-syntax-check +At SQL 1 : syntax error at position 13 near 'frm' $ echo $? 1 @@ -73,16 +74,15 @@ $ echo $? ## Slow log analyzing ```bash -$ pt-query-digest slow.log > slow.log.digest +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 +python2.7 doc/example/digest_pt.py slow.log.digest > slow.md ``` - ## SQL FingerPrint ```bash -$ echo "select * from film where col='abc'" | soar -report-type=fingerprint +echo "select * from film where col='abc'" | soar -report-type=fingerprint ``` Output @@ -94,7 +94,7 @@ select * from film where col=? ## Convert UPDATE/DELETE/INSERT into SELECT ```bash -$ echo "update film set title = 'abc'" | soar -rewrite-rules dml2select,delimiter -report-type rewrite +echo "update film set title = 'abc'" | soar -rewrite-rules dml2select,delimiter -report-type rewrite ``` Output @@ -103,11 +103,10 @@ Output select * from film; ``` - ## Merge ALTER SQLs ```bash -$ echo "alter table tb add column a int; alter table tb add column b int;" | soar -report-type rewrite -rewrite-rules mergealter +echo "alter table tb add column a int; alter table tb add column b int;" | soar -report-type rewrite -rewrite-rules mergealter ``` Output @@ -119,7 +118,7 @@ ALTER TABLE `tb` add column a int, add column b int ; ## SQL Pretty ```bash -$ echo "select * from tbl where col = 'val'" | ./soar -report-type=pretty +echo "select * from tbl where col = 'val'" | ./soar -report-type=pretty ``` Output @@ -138,6 +137,5 @@ WHERE md2html comes with other flags, such as `-report-css`, `-report-javascript`, `-markdown-extensions`, `-markdown-html-flags`, you can get more self control HTML report. ```bash -$ cat test.md | soar -report-type md2html > test.html +cat test.md | soar -report-type md2html > test.html ``` - diff --git a/doc/comparison.md b/doc/comparison.md index 90f7087..20c033d 100644 --- a/doc/comparison.md +++ b/doc/comparison.md @@ -10,4 +10,3 @@ | Trace | ✔️ | ❌ | ❌ | ❌ | ❌ | ❌ | | SQL在线执行 | ❌ | ❌ | ❌ | ❌ | ✔️ | ❌ | | 数据备份 | ❌ | ❌ | ❌ | ❌ | ✔️ | ❌ | - diff --git a/doc/comparison_en.md b/doc/comparison_en.md index 1aced8c..d789328 100644 --- a/doc/comparison_en.md +++ b/doc/comparison_en.md @@ -10,4 +10,3 @@ | Trace | ✔️ | ❌ | ❌ | ❌ | ❌ | ❌ | | Execute SQL Online | ❌ | ❌ | ❌ | ❌ | ✔️ | ❌ | | Backup Data | ❌ | ❌ | ❌ | ❌ | ✔️ | ❌ | - diff --git a/doc/config.md b/doc/config.md index 50ef2b1..72ee7b9 100644 --- a/doc/config.md +++ b/doc/config.md @@ -73,20 +73,21 @@ verbose: true 几乎所有配置文件中指定的参数都通通过命令行参数进行修改，且命令行参数优先级较配置文件优先级高。 ```bash -$ soar -h +soar -h ``` ### 命令行参数配置DSN -> 账号密码中如包含特殊符号(如：'@',':','/'等)可在配置文件中设置，存在特殊字符的情况不适合在命令行中使用。目前`soar`只支持tcp协议的MySQL数据库连接方式，如需要配置本机MySQL环境建议将`localhost`修改为'127.0.0.1'，并检查对应的'user'@'127.0.0.1'账号是否存在。 +> 账号密码中如包含特殊符号(如：'@',':','/'等)可在配置文件中设置，存在特殊字符的情况不适合在命令行中使用。目前`soar`只支持 tcp 协议的 MySQL 数据库连接方式，如需要配置本机MySQL环境建议将`localhost`修改为'127.0.0.1'，并检查对应的 'user'@'127.0.0.1' 账号是否存在。 ```bash -$ soar -online-dsn "user:password@ip:port/database" +soar -online-dsn "user:password@ip:port/database" -$ soar -test-dsn "user:password@ip:port/database" +soar -test-dsn "user:password@ip:port/database" ``` #### DSN格式支持 + * "user:password@127.0.0.1:3307/database" * "user:password@127.0.0.1:3307" * "user:password@127.0.0.1:/database" @@ -106,6 +107,6 @@ $ soar -test-dsn "user:password@ip:port/database" 不同类型的建议指定的Severity不同，严重程度数字由低到高依次排序。满分100分，扣到0分为止。L0不扣分只给出建议，L1扣5分，L2扣10分，每级多扣5分以此类推。当由时给出L1, L2两要建议时扣分叠加，即扣15分。 -如果您想给出不同的扣分建议或者对指引中的文字内容不满意可以为在git中提ISSUE，也可直接修改rules.go的相应配置然后重新编译自己的版本。 +如果您想给出不同的扣分建议或者对指引中的文字内容不满意可以为在 git 中提 ISSUE，也可直接修改 rules.go 的相应配置然后重新编译自己的版本。 注意：目前只有`markdown`和`html`两种`-report-type`支持评分输出显示，其他输出格式如有评分需求可以按上述规则自行计算。 diff --git a/doc/editor_plugin.md b/doc/editor_plugin.md index bf90010..f52556c 100644 --- a/doc/editor_plugin.md +++ b/doc/editor_plugin.md @@ -13,7 +13,7 @@ #### 安装插件后无任何变化 -安装了Syntastic没有任何显示，官方推荐通过如下配置来开启自动提示，不然用户无法看到SOAR给出的建议。 +安装了 Syntastic 没有任何显示，官方推荐通过如下配置来开启自动提示，不然用户无法看到SOAR给出的建议。 ```vim set statusline+=%#warningmsg# diff --git a/doc/install.md b/doc/install.md index b4e04ae..c2bcd5a 100644 --- a/doc/install.md +++ b/doc/install.md @@ -1,10 +1,10 @@ ## 下载二进制安装包 ```bash -wget https://github.com/XiaoMi/soar/releases/download/${tag}/soar.linux-amd64 -O soar +wget https://github.com/XiaoMi/soar/releases/download/${tag}/soar.${OS}-amd64 -O soar chmod a+x soar 如： -wget https://github.com/XiaoMi/soar/releases/download/v0.8.1/soar.linux-amd64 -O soar +wget https://github.com/XiaoMi/soar/releases/download/v0.9.0/soar.linux-amd64 -O soar chmod a+x soar ``` diff --git a/doc/install_en.md b/doc/install_en.md index 08363fa..9f1b203 100644 --- a/doc/install_en.md +++ b/doc/install_en.md @@ -1,10 +1,10 @@ ## Get Released Binary ```bash -wget https://github.com/XiaoMi/soar/releases/download/${tag}/soar.linux-amd64 -O soar +wget https://github.com/XiaoMi/soar/releases/download/${tag}/soar.${OS}-amd64 -O soar chmod a+x soar eg. -wget https://github.com/XiaoMi/soar/releases/download/v0.8.0/soar.linux-amd64 -O soar +wget https://github.com/XiaoMi/soar/releases/download/v0.9.0/soar.linux-amd64 -O soar chmod a+x soar ``` -- GitLab