diff options
Diffstat (limited to '')
| -rw-r--r-- | www/debugging.html | 253 |
1 files changed, 253 insertions, 0 deletions
diff --git a/www/debugging.html b/www/debugging.html new file mode 100644 index 0000000..4de2811 --- /dev/null +++ b/www/debugging.html @@ -0,0 +1,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> + |