Debian Codegraph @

www/debugging.html

raw
1 <!DOCTYPE html>
2 <html><head>
3 <meta name="viewport" content="width=device-width, initial-scale=1.0">
4 <meta http-equiv="content-type" content="text/html; charset=UTF-8">
5 <link href="sqlite.css" rel="stylesheet">
6 <title>Hints for Debugging SQLite</title>
7 <!-- path= -->
8 </head>
9 <body>
10 <div class=nosearch>
11 <a href="index.html">
12 <img class="logo" src="images/sqlite370_banner.svg" alt="SQLite" border="0">
13 </a>
14 <div><!-- IE hack to prevent disappearing logo --></div>
15 <div class="tagline desktoponly">
16 Small. Fast. Reliable.<br>Choose any three.
17 </div>
18 <div class="menu mainmenu">
19 <ul>
20 <li><a href="index.html">Home</a>
21 <li class='mobileonly'><a href="javascript:void(0)" onclick='toggle_div("submenu")'>Menu</a>
22 <li class='wideonly'><a href='about.html'>About</a>
23 <li class='desktoponly'><a href="docs.html">Documentation</a>
24 <li class='desktoponly'><a href="download.html">Download</a>
25 <li class='wideonly'><a href='copyright.html'>License</a>
26 <li class='desktoponly'><a href="support.html">Support</a>
27 <li class='desktoponly'><a href="prosupport.html">Purchase</a>
28 <li class='search' id='search_menubutton'>
29 <a href="javascript:void(0)" onclick='toggle_search()'>Search</a>
30 </ul>
31 </div>
32 <div class="menu submenu" id="submenu">
33 <ul>
34 <li><a href='about.html'>About</a>
35 <li><a href='docs.html'>Documentation</a>
36 <li><a href='download.html'>Download</a>
37 <li><a href='support.html'>Support</a>
38 <li><a href='prosupport.html'>Purchase</a>
39 </ul>
40 </div>
41 <div class="searchmenu" id="searchmenu">
42 <form method="GET" action="search">
43 <select name="s" id="searchtype">
44 <option value="d">Search Documentation</option>
45 <option value="c">Search Changelog</option>
46 </select>
47 <input type="text" name="q" id="searchbox" value="">
48 <input type="submit" value="Go">
49 </form>
50 </div>
51 </div>
52 <script>
53 function toggle_div(nm) {
54 var w = document.getElementById(nm);
55 if( w.style.display=="block" ){
56 w.style.display = "none";
57 }else{
58 w.style.display = "block";
59 }
60 }
61 function toggle_search() {
62 var w = document.getElementById("searchmenu");
63 if( w.style.display=="block" ){
64 w.style.display = "none";
65 } else {
66 w.style.display = "block";
67 setTimeout(function(){
68 document.getElementById("searchbox").focus()
69 }, 30);
70 }
71 }
72 function div_off(nm){document.getElementById(nm).style.display="none";}
73 window.onbeforeunload = function(e){div_off("submenu");}
74 /* Disable the Search feature if we are not operating from CGI, since */
75 /* Search is accomplished using CGI and will not work without it. */
76 if( !location.origin || !location.origin.match || !location.origin.match(/http/) ){
77 document.getElementById("search_menubutton").style.display = "none";
78 }
79 /* Used by the Hide/Show button beside syntax diagrams, to toggle the */
80 function hideorshow(btn,obj){
81 var x = document.getElementById(obj);
82 var b = document.getElementById(btn);
83 if( x.style.display!='none' ){
84 x.style.display = 'none';
85 b.innerHTML='show';
86 }else{
87 x.style.display = '';
88 b.innerHTML='hide';
89 }
90 return false;
91 }
92 var antiRobot = 0;
93 function antiRobotGo(){
94 if( antiRobot!=3 ) return;
95 antiRobot = 7;
96 var j = document.getElementById("mtimelink");
97 if(j && j.hasAttribute("data-href")) j.href=j.getAttribute("data-href");
98 }
99 function antiRobotDefense(){
100 document.body.onmousedown=function(){
101 antiRobot |= 2;
102 antiRobotGo();
103 document.body.onmousedown=null;
104 }
105 document.body.onmousemove=function(){
106 antiRobot |= 2;
107 antiRobotGo();
108 document.body.onmousemove=null;
109 }
110 setTimeout(function(){
111 antiRobot |= 1;
112 antiRobotGo();
113 }, 100)
114 antiRobotGo();
115 }
116 antiRobotDefense();
117 </script>
118
119
120 <h1 align='center'>Debugging Hints</h1>
121
122 <p>
123 The following is a random assortment of techniques used by the
124 SQLite developers to trace, examine, and understand the behavior of the
125 core SQLite library.
126
127 <p>
128 These techniques are designed to aid in understanding the
129 core SQLite library itself, not applications that merely use SQLite.
130
131 <ol>
132 <li>
133 <p><b>Use the ".eqp full" option on the <a href="cli.html">command-line shell</a></b>
134
135 <p>When you have a SQL script that you are debugging or trying
136 to understand, it is often useful to run it in the <a href="cli.html">command-line shell</a>
137 with the ".eqp full" setting. When ".eqp" is set to FULL, the shell
138 automatically shows the <a href="lang_explain.html">EXPLAIN</a> and <a href="eqp.html">EXPLAIN QUERY PLAN</a> output for
139 each command prior to actually running that command.
140
141 <p>For added readability, also set ".echo on" so that the output contains
142 the original SQL text.
143
144 <p>The newer ".eqp trace" command does everything that ".eqp full" does
145 and also turns on <a href="pragma.html#pragma_vdbe_trace">VDBE tracing</a>.
146 </li>
147
148 <li>
149 <p><b>Use compile-time options to enable debugging features.</b>
150
151 <p>Suggested compile-time options include:
152 <ul>
153 <li><a href="compile.html#debug">-DSQLITE_DEBUG</a>
154 <li><a href="compile.html#enable_explain_comments">-DSQLITE_ENABLE_EXPLAIN_COMMENTS</a>
155 <li>-DSQLITE_ENABLE_TREETRACE
156 <li>-DSQLITE_ENABLE_WHERETRACE
157 </ul>
158 </li>
159
160 <p>The SQLITE_ENABLE_TREETRACE and SQLITE_ENABLE_WHERETRACE options
161 are not documented in the <a href="compile.html">compile-time options</a> document because they
162 are not officially supported. What they do is activate the
163 ".treetrace" and ".wheretrace" dot-commands in the command-line
164 shell, which provide low-level tracing output for the logic that
165 generates code for SELECT and DML statements and WHERE clauses, respectively.
166
167 <li>
168 <p><b>Call sqlite3ShowExpr() and similar from the debugger.</b>
169
170 <p>When compiled with <a href="compile.html#debug">SQLITE_DEBUG</a>, SQLite includes routines that will
171 print out various internal abstract syntax tree structures as ASCII-art graphs.
172 These routines can be useful during debugging to understand the variables
173 that SQLite is working with. The following routines are available:
174
175 <ul>
176 <li> void sqlite3ShowExpr(const Expr*);
177 <li> void sqlite3ShowExprList(const ExprList*);
178 <li> void sqlite3ShowIdList(const IdList*);
179 <li> void sqlite3ShowSrcList(const SrcList*);
180 <li> void sqlite3ShowSelect(const Select*);
181 <li> void sqlite3ShowWith(const With*);
182 <li> void sqlite3ShowUpsert(const Upsert*);
183 <li> void sqlite3ShowTrigger(const Trigger*);
184 <li> void sqlite3ShowTriggerList(const Trigger*);
185 <li> void sqlite3ShowTriggerStep(const TriggerStep*);
186 <li> void sqlite3ShowTriggerStepList(const TriggerStep*);
187 <li> void sqlite3ShowWindow(const Window*);
188 <li> void sqlite3ShowWinFunc(const Window*);
189 </ul>
190
191 <p>These routines are not APIs and are subject to change. They are
192 for interactive debugging use only.</p>
193 </li>
194
195 <li>
196 <p><b>Breakpoints on test_addoptrace</b>
197
198 <p>When debugging the <a href="opcode.html">bytecode</a> generator, it is often useful to know
199 where a particular opcode is being generated. To find this easily,
200 run the script in a debugger. Set a breakpoint on the "test_addoptrace"
201 routine. Then run the "PRAGMA vdbe_addoptrace=ON;" followed by the
202 SQL statement in question. Each opcode will be displayed as it is
203 appended to the VDBE program, and the breakpoint will fire immediately
204 thereafter. Step until reaching the opcode then look backwards
205 in the stack to see where and how it was generated.
206
207 <p>This only works when compiled with <a href="compile.html#debug">SQLITE_DEBUG</a>.
208 </li>
209
210 <li>
211 <p><b>Using the ".treetrace" and ".wheretrace" shell commands</b>
212
213 <p>When the command-line shell and the core SQLite library are
214 both compiled with <a href="compile.html#debug">SQLITE_DEBUG</a> and
215 SQLITE_ENABLE_TREETRACE and SQLITE_ENABLE_WHERETRACE, then the
216 shell has two commands used to turn on debugging facilities for the
217 most intricate parts of the code generator - the logic dealing with
218 SELECT statements and WHERE clauses, respectively.
219 The ".treetrace" and ".wheretrace" commands each take a numeric
220 argument which can be expressed in hexadecimal. Each bit turns on
221 various parts of debugging. Values of "0xfff" and "0xff" are commonly
222 used. Use an argument of "0" to turn all tracing output back off.
223 </li>
224
225 <li>
226 <p><b>Using the ".breakpoint" shell command</b>
227
228 <p>The ".breakpoint" command in the CLI does nothing but invoke the
229 procedure named "test_breakpoint()", which is a no-op.
230
231 <p>If you have a script and you want to start debugging at some point
232 half-way through that script, simply set a breakpoint in gdb (or whatever
233 debugger you are using) on the test_breakpoint() function, and add a
234 ".breakpoint" command where you want to stop. When you reach that first
235 breakpoint, set whatever additional breakpoints or variable traces you
236 need.
237
238 <li>
239 <p><b>Disable the <a href="malloc.html#lookaside">lookaside memory allocator</a></b>
240
241 <p>When looking for memory allocation problems (memory leaks, use-after-free
242 errors, buffer overflows, etc) it is sometimes useful to disable the
243 <a href="malloc.html#lookaside">lookaside memory allocator</a> then run the test under valgrind or MSAN or
244 some other heap memory debugging tool.
245 The lookaside memory allocator can
246 be disabled at start-time using the <a href="c3ref/c_config_covering_index_scan.html#sqliteconfiglookaside">SQLITE_CONFIG_LOOKASIDE</a>
247 interface. The <a href="cli.html">command-line shell</a> will use that interface to
248 disable lookaside if it is started with the "--lookaside 0 0"
249 command line option.
250 </li>
251 </ol>
252 <p align="center"><small><i>This page was last updated on 2025-05-31 13:08:22Z </small></i></p>
253