228 lines
8.2 KiB
HTML
228 lines
8.2 KiB
HTML
<!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;
|
|
}
|
|
</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.
|
|
|
|
<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_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 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>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>
|
|
|