~percona-toolkit-dev/percona-toolkit/pt-agent

« back to all changes in this revision

Viewing changes to t/lib/samples/pod/pod_sample_mqa.txt

  • Committer: Daniel Nichter
  • Date: 2011-06-24 17:22:06 UTC
  • Revision ID: daniel@percona.com-20110624172206-c7q4s4ad6r260zz6
Add lib/, t/lib/, and sandbox/.  All modules are updated and passing on MySQL 5.1.

Show diffs side-by-side

added added

removed removed

Lines of Context:
 
1
# ############################################################################
 
2
 
 
3
=pod
 
4
 
 
5
=head1 NAME
 
6
 
 
7
mk-query-advisor - Scrutinize queries.
 
8
 
 
9
=head1 SYNOPSIS
 
10
 
 
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.
 
14
 
 
15
=head1 CHECKS
 
16
 
 
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.
 
21
 
 
22
=head2 Literals
 
23
 
 
24
id:    LIT.001
 
25
level: note
 
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.
 
30
 
 
31
id:    LIT.002
 
32
level: warn
 
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.
 
36
 
 
37
=head2 Table List
 
38
 
 
39
id:    TBL.001
 
40
level: note
 
41
rule:  tbl matches *
 
42
desc:  SELECT *.  Selecting specific columns is preferable to SELECT *.
 
43
 
 
44
=head2 Clauses
 
45
 
 
46
id:    CLA.001
 
47
level: note
 
48
rule:  query matches ORDER BY RAND
 
49
desc:  ORDER BY RAND().  ORDER BY RAND() is not preferred.
 
50
 
 
51
=head2 Query
 
52
 
 
53
id:    QRY.001
 
54
level: note
 
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).
 
58
 
 
59
id:    QRY.002
 
60
level: note
 
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.
 
64
 
 
65
=head1 CHECK SYNTAX
 
66
 
 
67
Each check is a single paragraph (blank line before and after) with the
 
68
following attributes:
 
69
 
 
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.
 
74
 
 
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.
 
78
 
 
79
The level is either note, warn or crit (for "critical").
 
80
 
 
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:
 
83
 
 
84
  SUBJECT    REFERS TO
 
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
 
91
             statement.
 
92
  clause     One of these MAGIC_clauses:
 
93
  
 
94
               GROUP BY, ORDER BY, LIMIT
 
95
 
 
96
  VERB       DOES
 
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
 
101
 
 
102
  NOUN       DESCRIBES
 
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.
 
107
 
 
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.
 
112
 
 
113
=head1 OPTIONS
 
114
 
 
115
=over
 
116
 
 
117
=item --define
 
118
 
 
119
type: array
 
120
 
 
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.
 
124
 
 
125
=item --ignore-checks
 
126
 
 
127
type: array
 
128
 
 
129
Ignore these L<"CHECKS">.
 
130
 
 
131
=item --verbose
 
132
 
 
133
cumulative; default: 0
 
134
 
 
135
Print more information.
 
136
 
 
137
=back
 
138
 
 
139
=head1 ENVIRONMENT
 
140
 
 
141
The environment variable C<MKDEBUG> enables verbose debugging output in all of the
 
142
Maatkit tools:
 
143
 
 
144
   MKDEBUG=1 mk-....
 
145
 
 
146
=head1 VERSION
 
147
 
 
148
This manual page documents Ver @VERSION@ Distrib @DISTRIB@ $Revision: 1929 $.
 
149
 
 
150
=cut