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
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
|
<!DOCTYPE html>
<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>
<!-- path= -->
</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_search()'>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">
<select name="s" id="searchtype">
<option value="d">Search Documentation</option>
<option value="c">Search Changelog</option>
</select>
<input type="text" name="q" id="searchbox" value="">
<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 toggle_search() {
var w = document.getElementById("searchmenu");
if( w.style.display=="block" ){
w.style.display = "none";
} else {
w.style.display = "block";
setTimeout(function(){
document.getElementById("searchbox").focus()
}, 30);
}
}
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 || !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;
}
var antiRobot = 0;
function antiRobotGo(){
if( antiRobot!=3 ) return;
antiRobot = 7;
var j = document.getElementById("mtimelink");
if(j && j.hasAttribute("data-href")) j.href=j.getAttribute("data-href");
}
function antiRobotDefense(){
document.body.onmousedown=function(){
antiRobot |= 2;
antiRobotGo();
document.body.onmousedown=null;
}
document.body.onmousemove=function(){
antiRobot |= 2;
antiRobotGo();
document.body.onmousemove=null;
}
setTimeout(function(){
antiRobot |= 1;
antiRobotGo();
}, 100)
antiRobotGo();
}
antiRobotDefense();
</script>
<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.
<p>The newer ".eqp trace" command does everything that ".eqp full" does
and also turns on <a href="pragma.html#pragma_vdbe_trace">VDBE tracing</a>.
</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_TREETRACE
<li>-DSQLITE_ENABLE_WHERETRACE
</ul>
</li>
<p>The SQLITE_ENABLE_TREETRACE 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
".treetrace" and ".wheretrace" dot-commands in the command-line
shell, which provide low-level tracing output for the logic that
generates code for SELECT and DML statements and WHERE clauses, respectively.
<li>
<p><b>Call sqlite3ShowExpr() 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 abstract syntax 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. The following routines are available:
<ul>
<li> void sqlite3ShowExpr(const Expr*);
<li> void sqlite3ShowExprList(const ExprList*);
<li> void sqlite3ShowIdList(const IdList*);
<li> void sqlite3ShowSrcList(const SrcList*);
<li> void sqlite3ShowSelect(const Select*);
<li> void sqlite3ShowWith(const With*);
<li> void sqlite3ShowUpsert(const Upsert*);
<li> void sqlite3ShowTrigger(const Trigger*);
<li> void sqlite3ShowTriggerList(const Trigger*);
<li> void sqlite3ShowTriggerStep(const TriggerStep*);
<li> void sqlite3ShowTriggerStepList(const TriggerStep*);
<li> void sqlite3ShowWindow(const Window*);
<li> void sqlite3ShowWinFunc(const Window*);
</ul>
<p>These routines are not APIs and are subject to change. They are
for interactive debugging use only.</p>
</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 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 ".treetrace" 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_TREETRACE 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 ".treetrace" 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>Using the ".breakpoint" shell command</b>
<p>The ".breakpoint" command in the CLI does nothing but invoke the
procedure named "test_breakpoint()", which is a no-op.
<p>If you have a script and you want to start debugging at some point
half-way through that script, simply set a breakpoint in gdb (or whatever
debugger you are using) on the test_breakpoint() function, and add a
".breakpoint" command where you want to stop. When you reach that first
breakpoint, set whatever additional breakpoints are variable traces you
need.
<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 or MSAN or
some other heap memory debugging tool.
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>
<p align="center"><small><i>This page last modified on <a href="https://sqlite.org/docsrc/honeypot" id="mtimelink" data-href="https://sqlite.org/docsrc/finfo/pages/debugging.in?m=ffab87c7343ef0cf5">2022-04-06 18:55:14</a> UTC </small></i></p>
|
