1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html><head>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<link href="sqlite.css" rel="stylesheet">
<title>Hints for Debugging SQLite</title>
</head>
<body>
<div class=nosearch>
<a href="index.html">
<img class="logo" src="images/sqlite370_banner.gif" alt="SQLite" border="0">
</a>
<div><!-- IE hack to prevent disappearing logo --></div>
<div class="tagline desktoponly">
Small. Fast. Reliable.<br>Choose any three.
</div>
<div class="menu mainmenu">
<ul>
<li><a href="index.html">Home</a>
<li class='mobileonly'><a href="javascript:void(0)" onclick='toggle_div("submenu")'>Menu</a>
<li class='wideonly'><a href='about.html'>About</a>
<li class='desktoponly'><a href="docs.html">Documentation</a>
<li class='desktoponly'><a href="download.html">Download</a>
<li class='wideonly'><a href='copyright.html'>License</a>
<li class='desktoponly'><a href="support.html">Support</a>
<li class='desktoponly'><a href="prosupport.html">Purchase</a>
<li class='search' id='search_menubutton'>
<a href="javascript:void(0)" onclick='toggle_div("searchmenu")'>Search</a>
</ul>
</div>
<div class="menu submenu" id="submenu">
<ul>
<li><a href='about.html'>About</a>
<li><a href='docs.html'>Documentation</a>
<li><a href='download.html'>Download</a>
<li><a href='support.html'>Support</a>
<li><a href='prosupport.html'>Purchase</a>
</ul>
</div>
<div class="searchmenu" id="searchmenu">
<form method="GET" action="search">
<span class="desktoponly">Search for:</span> <input type="text" name="q">
<input type="submit" value="Go">
</form>
</div>
</div>
<script>
function toggle_div(nm) {
var w = document.getElementById(nm);
if( w.style.display=="block" ){
w.style.display = "none";
}else{
w.style.display = "block";
}
}
function div_off(nm){document.getElementById(nm).style.display="none";}
window.onbeforeunload = function(e){div_off("submenu");}
/* Disable the Search feature if we are not operating from CGI, since */
/* Search is accomplished using CGI and will not work without it. */
if( !location.origin.match || !location.origin.match(/http/) ){
document.getElementById("search_menubutton").style.display = "none";
}
/* Used by the Hide/Show button beside syntax diagrams, to toggle the */
function hideorshow(btn,obj){
var x = document.getElementById(obj);
var b = document.getElementById(btn);
if( x.style.display!='none' ){
x.style.display = 'none';
b.innerHTML='show';
}else{
x.style.display = '';
b.innerHTML='hide';
}
return false;
}
</script>
</div>
<h1 align='center'>Debugging Hints</h1>
<p>
The following is a random assortment of techniques used by the
SQLite developers to trace, examine, and understand the behavior of the
core SQLite library.
<p>
These techniques are designed to aid in understanding the
core SQLite library itself, not applications that merely use SQLite.
<ol>
<li>
<p><b>Use the ".eqp full" option on the <a href="cli.html">command-line shell</a></b>
<p>When you have a SQL script that you are debugging or trying
to understand, it is often useful to run it in the <a href="cli.html">command-line shell</a>
with the ".eqp full" setting. When ".eqp" is set to FULL, the shell
automatically shows the <a href="lang_explain.html">EXPLAIN</a> and <a href="eqp.html">EXPLAIN QUERY PLAN</a> output for
each command prior to actually running that command.
<p>For added readability, also set ".echo on" so that the output contains
the original SQL text.
</li>
<li>
<p><b>Use compile-time options to enable debugging features.</b>
<p>Suggested compile-time options include:
<ul>
<li><a href="compile.html#debug">-DSQLITE_DEBUG</a>
<li><a href="compile.html#enable_explain_comments">-DSQLITE_ENABLE_EXPLAIN_COMMENTS</a>
<li>-DSQLITE_ENABLE_SELECTTRACE
<li>-DSQLITE_ENABLE_WHERETRACE
</ul>
</li>
<p>The SQLITE_ENABLE_SELECTTRACE and SQLITE_ENABLE_WHERETRACE options
are not documented in <a href="compile.html">compile-time options</a> document because they
are not officially supported. What they do is activate the
".selecttrace" and ".wheretrace" dot-commands in the command-line
shell, which provide low-level tracing output for the logic that
generates code for SELECT statements and WHERE clauses, respectively.
<li>
<p><b>Call sqlite3TreeViewExpr() and similar from the debugger.</b>
<p>When compiled with <a href="compile.html#debug">SQLITE_DEBUG</a>, SQLite includes routines that will
print out various internal parse tree structures as ASCII-art graphs.
This can be very useful in a debugging in order to understand the variables
that SQLite is working with.
<p>For example, in gdb, to see the complete hierarchy of an Expr node
(that is to say, the Expr node and all of its children), given a pointer
"pExpr" to that node, type:
<codeblock>
print sqlite3TreeViewExpr(0, pExpr, 0)
</codeblock>
<p>The two "0" parameters do server a purpose in some contexts, but for
using these routine to print a parse tree as ASCII-art on the terminal,
they should both be "0".
<p>Other similar tree-display routines include:
<ul>
<li>sqlite3TreeViewSelect(0, pSelect, 0)
<li>sqlite3TreeViewExprList(0, pList, 0, 0)
</ul>
</li>
<li>
<p><b>Breakpoints on test_addoptrace</b>
<p>When debugging the <a href="opcode.html">bytecode</a> generator, it is often useful to know
where a particular opcode is being generated. To find this easily,
run the script in a debugger. Set a breakpoint on the "test_addoptrace"
routine. Then run the "PRAGMA vdbe_addoptrace=ON;" followed by the
SQL statement in question. Each opcode will be displayed as it is
appended to the VDBE program, and the breakpoint will fire immediately
thereafter. Step until reaching the opcode and question then look backwards
in the stack to see where and how it was generated.
<p>This only works when compiled with <a href="compile.html#debug">SQLITE_DEBUG</a>.
</li>
<li>
<p><b>Using the ".selecttrace" and ".wheretrace" shell commands</b>
<p>When the command-line shell and the core SQLite library are
both compiled with <a href="compile.html#debug">SQLITE_DEBUG</a> and
SQLITE_ENABLE_SELECTTRACE and SQLITE_ENABLE_WHERETRACE, then the
shell has two commands used to turn on debugging facilities for the
most intricate parts of the code generator - the logic dealing with
SELECT statements and WHERE clauses, respectively.
The ".selecttrace" and ".wheretrace" commands each take a numeric
argument which can be expressed in hexadecimal. Each bit turns on
various parts of debugging. Values of "0xfff" and "0xff" are commonly
used. Use an argument of "0" to turn all tracing output back off.
</li>
<li>
<p><b>Disable the <a href="malloc.html#lookaside">lookaside memory allocator</a></b>
<p>When looking for memory allocation problems (memory leaks, use-after-free
errors, buffer overflows, etc) it is sometimes useful to disable the
<a href="malloc.html#lookaside">lookaside memory allocator</a> then run the test under valgrind.
The lookaside memory allocator can
be disabled at start-time using the <a href="c3ref/c_config_covering_index_scan.html#sqliteconfiglookaside">SQLITE_CONFIG_LOOKASIDE</a>
interface. The <a href="cli.html">command-line shell</a> will use that interface to
disable lookaside if it is started with the "--lookaside 0 0"
command line option.
</li>
</ol>
|
