1
# ############################################################################
7
mk-query-advisor - Scrutinize queries.
11
This POD sample simulates special POD stuff used by mk-query-advisor. The
12
format used here is not the same actually used in mk-query-advisor. This POD
13
sample is, therore, just for testing.
17
These are the check that mk-advisor can perform on a query. There are several
18
classes of checks, each described in its own seciton. You can add new checks
19
by adding new entires like the ones below. Read L<"CHECK SYNTAX"> to learn
20
the structure of these checks.
26
rule: colval matches \d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}\.
27
desc: IP address used as string. The string literal looks like an IP address
28
but is not used inside INET_ATON(). WHERE ip='127.0.0.1' is better as
29
ip=INET_ATON('127.0.0.1') if the column is numeric.
33
rule: colval matches (?:\d{2,4}-\d{1,2}-\d{1,2}|\d{4,6})
34
desc: Date literal is not quoted. WHERE col<2010-02-12 is valid but wrong;
35
the date should be quoted.
42
desc: SELECT *. Selecting specific columns is preferable to SELECT *.
48
rule: query matches ORDER BY RAND
49
desc: ORDER BY RAND(). ORDER BY RAND() is not preferred.
55
rule: INSERT without columns
56
desc: Blind INSERT. The INSERT does not specify columns. INSERT INTO tbl
57
(col1,col2) VALUES (1,2) is preferred to INSERT INTO tbl VALUES (1,2).
61
rule: query matches SQL_CALC_FOUND_ROWS
62
desc: SQL_CALC_FOUND_ROWS does not scale. SQL_CALC_FOUND_ROWS can cause
63
performance problems because it does not scale well.
67
Each check is a single paragraph (blank line before and after) with the
70
* id A unique ID used by the tool to identify the check
71
* level note, warn, or crit
72
* rule A special syntax telling the tool how to perform the check
73
* desc A terse, fuller and complete description of the check.
75
The check is two parts: CCC.NNN where CCC is the class abbreviation and NNN
76
is the next avaiable number. The classes are shown above, LIT for Literals,
77
TBL for Table List, etc. The numbers should never overlap or change.
79
The level is either note, warn or crit (for "critical").
81
The rule is a special, limited syntax that the tool translateis into code.
82
Each rule is a single sentence with a subject, verb and noun. These are:
85
======= ================================================================
86
query The whole text of the query (the SQL statement)
87
colval Any column value for any column
88
tbl Any table from anywhere
89
<DMS> Any Data Manipulation Statement in caps: SELECT, INSERT, DELETE,
90
etc. The rule only applies if the query is this type of
92
clause One of these MAGIC_clauses:
94
GROUP BY, ORDER BY, LIMIT
97
======= ================================================================
98
matches Perl regex match SUBJECT =~ m/NOUN/ims
99
with <DMS> subject has NOUN part
100
without <DMS> subject does not have NOUN part
103
======= ================================================================
104
where WHERE clause, used only with <DMS> subjects
105
columns Columns list of the query, used only with <DMS> subjects
106
<...> Anything after the verb, used with most verbs.
108
The description (desc) should have at least two period-terminate sentences.
109
The first sentece should be the terse definition of the check. The second
110
sentence should be the fuller defintion. Any more sentences are the complete
111
defintion of the check.
121
Define these check IDs. If L<"--verbose"> is zero (i.e. not specified) then
122
a terse definition is given. If one then a fuller definition is given. If
123
two then the complete definition is given.
125
=item --ignore-checks
129
Ignore these L<"CHECKS">.
133
cumulative; default: 0
135
Print more information.
141
The environment variable C<MKDEBUG> enables verbose debugging output in all of the
148
This manual page documents Ver @VERSION@ Distrib @DISTRIB@ $Revision: 1929 $.