| 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>Architecture of 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 |
<div class=fancy> |
| 119 |
<div class=nosearch> |
| 120 |
<div class="fancy_title"> |
| 121 |
Architecture of SQLite |
| 122 |
</div> |
| 123 |
</div> |
| 124 |
|
| 125 |
|
| 126 |
|
| 127 |
|
| 128 |
<h1>Introduction</h1> |
| 129 |
|
| 130 |
|
| 131 |
<p>This document describes the architecture of the SQLite library. |
| 132 |
The information here is useful to those who want to understand or |
| 133 |
modify the inner workings of SQLite. |
| 134 |
</p> |
| 135 |
|
| 136 |
<div class="rightsidebar imgcontainer"> |
| 137 |
<div style="max-width:367px;"><svg xmlns='http://www.w3.org/2000/svg' style='font-size:initial;' class="pikchr" width="367" height="453" viewBox="0 0 490.32 605.52" data-pikchr-date="20250319161943"> |
| 138 |
<path d="M2.16,293.76L236.16,293.76L236.16,2.16L2.16,2.16Z" style="fill:rgb(216,236,208);stroke-width:2.16;stroke:rgb(0,0,0);" /> |
| 139 |
<path d="M2.16,603.36L236.16,603.36L236.16,311.76L2.16,311.76Z" style="fill:rgb(208,236,232);stroke-width:2.16;stroke:rgb(0,0,0);" /> |
| 140 |
<path d="M254.16,347.76L488.16,347.76L488.16,2.16L254.16,2.16Z" style="fill:rgb(232,216,208);stroke-width:2.16;stroke:rgb(0,0,0);" /> |
| 141 |
<path d="M254.16,603.36L488.16,603.36L488.16,394.56L254.16,394.56Z" style="fill:rgb(224,236,200);stroke-width:2.16;stroke:rgb(0,0,0);" /> |
| 142 |
<path d="M38.16,92.16L200.16,92.16L200.16,38.16L38.16,38.16Z" style="fill:rgb(255,255,255);stroke-width:2.16;stroke:rgb(0,0,0);" /> |
| 143 |
<text x="119.16" y="65.16" text-anchor="middle" fill="rgb(0,0,0)" font-size="110%" dominant-baseline="central">Interface</text> |
| 144 |
<polygon points="119.16,120.96 114.84,109.44 123.48,109.44" style="fill:rgb(0,0,0)"/> |
| 145 |
<path d="M119.16,92.16L119.16,115.2" style="fill:none;stroke-width:2.16;stroke:rgb(0,0,0);" /> |
| 146 |
<path d="M38.16,174.96L200.16,174.96L200.16,120.96L38.16,120.96Z" style="fill:rgb(255,255,255);stroke-width:2.16;stroke:rgb(0,0,0);" /> |
| 147 |
<text x="119.16" y="135.209" text-anchor="middle" fill="rgb(0,0,0)" font-size="110%" dominant-baseline="central">SQL Command</text> |
| 148 |
<text x="119.16" y="160.711" text-anchor="middle" fill="rgb(0,0,0)" font-size="110%" dominant-baseline="central">Processor</text> |
| 149 |
<polygon points="119.16,203.76 114.84,192.24 123.48,192.24" style="fill:rgb(0,0,0)"/> |
| 150 |
<path d="M119.16,174.96L119.16,198" style="fill:none;stroke-width:2.16;stroke:rgb(0,0,0);" /> |
| 151 |
<path d="M38.16,257.76L200.16,257.76L200.16,203.76L38.16,203.76Z" style="fill:rgb(255,255,255);stroke-width:2.16;stroke:rgb(0,0,0);" /> |
| 152 |
<text x="119.16" y="230.76" text-anchor="middle" fill="rgb(0,0,0)" font-size="110%" dominant-baseline="central">Virtual Machine</text> |
| 153 |
<polygon points="119.16,347.76 114.84,336.24 123.48,336.24" style="fill:rgb(0,0,0)"/> |
| 154 |
<path d="M119.16,257.76L119.16,342" style="fill:none;stroke-width:2.16;stroke:rgb(0,0,0);" /> |
| 155 |
<path d="M38.16,401.76L200.16,401.76L200.16,347.76L38.16,347.76Z" style="fill:rgb(255,255,255);stroke-width:2.16;stroke:rgb(0,0,0);" /> |
| 156 |
<text x="119.16" y="374.76" text-anchor="middle" fill="rgb(0,0,0)" font-size="110%" dominant-baseline="central">B-Tree</text> |
| 157 |
<polygon points="119.16,430.56 114.84,419.04 123.48,419.04" style="fill:rgb(0,0,0)"/> |
| 158 |
<path d="M119.16,401.76L119.16,424.8" style="fill:none;stroke-width:2.16;stroke:rgb(0,0,0);" /> |
| 159 |
<path d="M38.16,484.56L200.16,484.56L200.16,430.56L38.16,430.56Z" style="fill:rgb(255,255,255);stroke-width:2.16;stroke:rgb(0,0,0);" /> |
| 160 |
<text x="119.16" y="457.56" text-anchor="middle" fill="rgb(0,0,0)" font-size="110%" dominant-baseline="central">Pager</text> |
| 161 |
<polygon points="119.16,513.36 114.84,501.84 123.48,501.84" style="fill:rgb(0,0,0)"/> |
| 162 |
<path d="M119.16,484.56L119.16,507.6" style="fill:none;stroke-width:2.16;stroke:rgb(0,0,0);" /> |
| 163 |
<path d="M38.16,567.36L200.16,567.36L200.16,513.36L38.16,513.36Z" style="fill:rgb(255,255,255);stroke-width:2.16;stroke:rgb(0,0,0);" /> |
| 164 |
<text x="119.16" y="540.36" text-anchor="middle" fill="rgb(0,0,0)" font-size="110%" dominant-baseline="central">OS Interface</text> |
| 165 |
<path d="M290.16,92.16L452.16,92.16L452.16,38.16L290.16,38.16Z" style="fill:rgb(255,255,255);stroke-width:2.16;stroke:rgb(0,0,0);" /> |
| 166 |
<text x="371.16" y="65.16" text-anchor="middle" fill="rgb(0,0,0)" font-size="110%" dominant-baseline="central">Tokenizer</text> |
| 167 |
<polygon points="371.16,120.96 366.84,109.44 375.48,109.44" style="fill:rgb(0,0,0)"/> |
| 168 |
<path d="M371.16,92.16L371.16,115.2" style="fill:none;stroke-width:2.16;stroke:rgb(0,0,0);" /> |
| 169 |
<path d="M290.16,174.96L452.16,174.96L452.16,120.96L290.16,120.96Z" style="fill:rgb(255,255,255);stroke-width:2.16;stroke:rgb(0,0,0);" /> |
| 170 |
<text x="371.16" y="147.96" text-anchor="middle" fill="rgb(0,0,0)" font-size="110%" dominant-baseline="central">Parser</text> |
| 171 |
<polygon points="371.16,203.76 366.84,192.24 375.48,192.24" style="fill:rgb(0,0,0)"/> |
| 172 |
<path d="M371.16,174.96L371.16,198" style="fill:none;stroke-width:2.16;stroke:rgb(0,0,0);" /> |
| 173 |
<path d="M290.16,311.76L452.16,311.76L452.16,203.76L290.16,203.76Z" style="fill:rgb(255,255,255);stroke-width:2.16;stroke:rgb(0,0,0);" /> |
| 174 |
<text x="371.16" y="245.009" text-anchor="middle" fill="rgb(0,0,0)" font-size="110%" dominant-baseline="central">Code</text> |
| 175 |
<text x="371.16" y="270.511" text-anchor="middle" fill="rgb(0,0,0)" font-size="110%" dominant-baseline="central">Generator</text> |
| 176 |
<path d="M290.16,484.56L452.16,484.56L452.16,430.56L290.16,430.56Z" style="fill:rgb(255,255,255);stroke-width:2.16;stroke:rgb(0,0,0);" /> |
| 177 |
<text x="371.16" y="457.56" text-anchor="middle" fill="rgb(0,0,0)" font-size="110%" dominant-baseline="central">Utilities</text> |
| 178 |
<path d="M290.16,567.36L452.16,567.36L452.16,513.36L290.16,513.36Z" style="fill:rgb(255,255,255);stroke-width:2.16;stroke:rgb(0,0,0);" /> |
| 179 |
<text x="371.16" y="540.36" text-anchor="middle" fill="rgb(0,0,0)" font-size="110%" dominant-baseline="central">Test Code</text> |
| 180 |
<polygon points="290.16,78.66 281.572,87.4699 277.897,79.6505" style="fill:rgb(0,0,0)"/> |
| 181 |
<path d="M200.16,120.96L284.947,81.1101" style="fill:none;stroke-width:2.16;stroke:rgb(0,0,0);" /> |
| 182 |
<polygon points="200.16,174.96 212.033,178.185 206.985,185.197" style="fill:rgb(0,0,0)"/> |
| 183 |
<path d="M290.16,239.76L204.834,178.326" style="fill:none;stroke-width:2.16;stroke:rgb(0,0,0);" /> |
| 184 |
<text x="20.16" y="147.96" text-anchor="middle" font-style="italic" fill="rgb(0,0,0)" font-size="110%" transform="rotate(-90 20.16,147.96)" dominant-baseline="central">Core</text> |
| 185 |
<text x="20.16" y="457.56" text-anchor="middle" font-style="italic" fill="rgb(0,0,0)" font-size="110%" transform="rotate(-90 20.16,457.56)" dominant-baseline="central">Backend</text> |
| 186 |
<text x="470.16" y="174.96" text-anchor="middle" font-style="italic" fill="rgb(0,0,0)" font-size="110%" transform="rotate(-90 470.16,174.96)" dominant-baseline="central">SQL Compiler</text> |
| 187 |
<text x="470.16" y="498.96" text-anchor="middle" font-style="italic" fill="rgb(0,0,0)" font-size="110%" transform="rotate(-90 470.16,498.96)" dominant-baseline="central">Accessories</text> |
| 188 |
</svg> |
| 189 |
</div> |
| 190 |
</div> |
| 191 |
|
| 192 |
<p> |
| 193 |
A nearby diagram shows the main components of SQLite |
| 194 |
and how they interoperate. The text below |
| 195 |
explains the roles of the various components. |
| 196 |
</p> |
| 197 |
|
| 198 |
<h1>Overview</h1> |
| 199 |
|
| 200 |
<p>SQLite works by compiling SQL text into <a href="opcode.html">bytecode</a>, then running |
| 201 |
that bytecode using a virtual machine. |
| 202 |
|
| 203 |
<p>The <a href="c3ref/prepare.html">sqlite3_prepare_v2()</a> and related interfaces act as a compiler |
| 204 |
for converting SQL text into bytecode. The <a href="c3ref/stmt.html">sqlite3_stmt</a> object is |
| 205 |
a container for a single bytecode program that implements a single |
| 206 |
SQL statement. The <a href="c3ref/step.html">sqlite3_step()</a> interface passes a bytecode program |
| 207 |
into the virtual machine, and runs the program until it either completes, |
| 208 |
or forms a row of result to be returned, or hits a fatal error, or is |
| 209 |
<a href="c3ref/interrupt.html">interrupted</a>. |
| 210 |
|
| 211 |
<h1>Interface</h1> |
| 212 |
|
| 213 |
<p>Much of the <a href="c3ref/intro.html">C-language Interface</a> is found in source |
| 214 |
files <a href='https://sqlite.org/src/file/src/main.c'>main.c</a>, <a href='https://sqlite.org/src/file/src/legacy.c'>legacy.c</a>, and |
| 215 |
<a href='https://sqlite.org/src/file/src/vdbeapi.c'>vdbeapi.c</a> |
| 216 |
though some routines are |
| 217 |
scattered about in other files where they can have access to data |
| 218 |
structures with file scope. |
| 219 |
The <a href="c3ref/free_table.html">sqlite3_get_table()</a> routine is implemented in <a href='https://sqlite.org/src/file/src/table.c'>table.c</a>. |
| 220 |
The <a href="c3ref/mprintf.html">sqlite3_mprintf()</a> routine is found in <a href='https://sqlite.org/src/file/src/printf.c'>printf.c</a>. |
| 221 |
The <a href="c3ref/complete.html">sqlite3_complete()</a> interface is in <a href='https://sqlite.org/src/file/src/complete.c'>complete.c</a>. |
| 222 |
The <a href="tclsqlite.html">TCL Interface</a> is implemented by <a href='https://sqlite.org/src/file/src/tclsqlite.c'>tclsqlite.c</a>. |
| 223 |
|
| 224 |
<p>To avoid name collisions, all external |
| 225 |
symbols in the SQLite library begin with the prefix <b>sqlite3</b>. |
| 226 |
Those symbols that are intended for external use (in other words, |
| 227 |
those symbols which form the API for SQLite) add an underscore, and |
| 228 |
thus begin with <b>sqlite3_</b>. Extension APIs sometimes add the |
| 229 |
extension name prior to the underscore; for example: |
| 230 |
<b>sqlite3rbu_</b> or <b>sqlite3session_</b>.</p> |
| 231 |
|
| 232 |
<h1>Tokenizer</h1> |
| 233 |
|
| 234 |
<p>When a string containing SQL statements is to be evaluated it is |
| 235 |
first sent to the tokenizer. |
| 236 |
The tokenizer breaks |
| 237 |
the SQL text into tokens and hands those tokens |
| 238 |
one by one to the parser. The tokenizer is hand-coded in |
| 239 |
the file <file>tokenize.c</b>. |
| 240 |
|
| 241 |
<p>Note that in this design, the tokenizer calls the parser. People |
| 242 |
who are familiar with YACC and BISON may be accustomed to doing things the |
| 243 |
other way around — having the parser call the tokenizer. Having |
| 244 |
the tokenizer call the parser is better, though, because it can be made |
| 245 |
threadsafe and it runs faster.</p> |
| 246 |
|
| 247 |
<h1>Parser</h1> |
| 248 |
|
| 249 |
<p>The parser assigns meaning to tokens based on |
| 250 |
their context. The parser for SQLite is generated using the |
| 251 |
<a href="lemon.html">Lemon parser generator</a>. |
| 252 |
Lemon does the same job as YACC/BISON, but it uses |
| 253 |
a different input syntax which is less error-prone. |
| 254 |
Lemon also generates a parser which is reentrant and thread-safe. |
| 255 |
And Lemon defines the concept of a non-terminal destructor so |
| 256 |
that it does not leak memory when syntax errors are encountered. |
| 257 |
The grammar file that drives Lemon and that defines the SQL language |
| 258 |
that SQLite understands is found in <a href='https://sqlite.org/src/file/src/parse.y'>parse.y</a>. |
| 259 |
|
| 260 |
<p>Because |
| 261 |
Lemon is a program not normally found on development machines, the |
| 262 |
complete source code to Lemon (just one C file) is included in the |
| 263 |
SQLite distribution in the "tool" subdirectory. |
| 264 |
</p> |
| 265 |
|
| 266 |
<h1>Code Generator</h1> |
| 267 |
|
| 268 |
<p>After the parser assembles tokens into a parse tree, |
| 269 |
the code generator runs to analyze the parse tree and generate |
| 270 |
<a href="opcode.html">bytecode</a> that performs the work of the SQL statement. |
| 271 |
The <a href="c3ref/stmt.html">prepared statement</a> object is a container for this bytecode. |
| 272 |
There are many files in the code generator, including: |
| 273 |
<a href='https://sqlite.org/src/file/src/attach.c'>attach.c</a>, |
| 274 |
<a href='https://sqlite.org/src/file/src/auth.c'>auth.c</a>, |
| 275 |
<a href='https://sqlite.org/src/file/src/build.c'>build.c</a>, |
| 276 |
<a href='https://sqlite.org/src/file/src/delete.c'>delete.c</a>, |
| 277 |
<a href='https://sqlite.org/src/file/src/expr.c'>expr.c</a>, |
| 278 |
<a href='https://sqlite.org/src/file/src/insert.c'>insert.c</a>, |
| 279 |
<a href='https://sqlite.org/src/file/src/pragma.c'>pragma.c</a>, |
| 280 |
<a href='https://sqlite.org/src/file/src/select.c'>select.c</a>, |
| 281 |
<a href='https://sqlite.org/src/file/src/trigger.c'>trigger.c</a>, |
| 282 |
<a href='https://sqlite.org/src/file/src/update.c'>update.c</a>, |
| 283 |
<a href='https://sqlite.org/src/file/src/vacuum.c'>vacuum.c</a>, |
| 284 |
<a href='https://sqlite.org/src/file/src/where.c'>where.c</a>, |
| 285 |
<a href='https://sqlite.org/src/file/src/wherecode.c'>wherecode.c</a>, and |
| 286 |
<a href='https://sqlite.org/src/file/src/whereexpr.c'>whereexpr.c</a>. |
| 287 |
In these files is where most of the serious magic happens. |
| 288 |
<a href='https://sqlite.org/src/file/src/expr.c'>expr.c</a> handles code generation for expressions. |
| 289 |
<b>where*.c</b> handles code generation for WHERE clauses on |
| 290 |
SELECT, UPDATE and DELETE statements. The files <a href='https://sqlite.org/src/file/src/attach.c'>attach.c</a>, |
| 291 |
<a href='https://sqlite.org/src/file/src/delete.c'>delete.c</a>, <a href='https://sqlite.org/src/file/src/insert.c'>insert.c</a>, <a href='https://sqlite.org/src/file/src/select.c'>select.c</a>, |
| 292 |
<a href='https://sqlite.org/src/file/src/trigger.c'>trigger.c</a> |
| 293 |
<a href='https://sqlite.org/src/file/src/update.c'>update.c</a>, and <a href='https://sqlite.org/src/file/src/vacuum.c'>vacuum.c</a> handle the code generation |
| 294 |
for SQL statements with the same names. (Each of these files calls routines |
| 295 |
in <a href='https://sqlite.org/src/file/src/expr.c'>expr.c</a> and <a href='https://sqlite.org/src/file/src/where.c'>where.c</a> as necessary.) All other |
| 296 |
SQL statements are coded out of <a href='https://sqlite.org/src/file/src/build.c'>build.c</a>. |
| 297 |
The <a href='https://sqlite.org/src/file/src/auth.c'>auth.c</a> file implements the functionality of |
| 298 |
<a href="c3ref/set_authorizer.html">sqlite3_set_authorizer()</a>.</p> |
| 299 |
|
| 300 |
<p>The code generator, and especially the logic in <b>where*.c</b> |
| 301 |
and in <a href='https://sqlite.org/src/file/src/select.c'>select.c</a>, is sometimes called the |
| 302 |
<a href="optoverview.html">query planner</a>. For any particular SQL statement, there might be |
| 303 |
hundreds, thousands, or millions of different algorithms to compute |
| 304 |
the answer. The query planner is an AI that strives to select the |
| 305 |
best algorithm from these millions of choices. |
| 306 |
|
| 307 |
<h1>Bytecode Engine</h1> |
| 308 |
|
| 309 |
<p>The <a href="opcode.html">bytecode</a> program created by the code generator is run by |
| 310 |
a virtual machine. |
| 311 |
|
| 312 |
<p>The virtual machine itself is entirely contained in a single |
| 313 |
source file <a href='https://sqlite.org/src/file/src/vdbe.c'>vdbe.c</a>. The |
| 314 |
<a href='https://sqlite.org/src/file/src/vdbe.h'>vdbe.h</a> header file defines an interface |
| 315 |
between the virtual machine and the rest of the SQLite library and |
| 316 |
<a href='https://sqlite.org/src/file/src/vdbeInt.h'>vdbeInt.h</a> which defines structures and interfaces that |
| 317 |
are private to the virtual machine itself. |
| 318 |
Various other <b>vdbe*.c</b> files are helpers to the virtual machine. |
| 319 |
The <a href='https://sqlite.org/src/file/src/vdbeaux.c'>vdbeaux.c</a> file contains utilities used by the virtual |
| 320 |
machine and interface modules used by the rest of the library to |
| 321 |
construct VM programs. The <a href='https://sqlite.org/src/file/src/vdbeapi.c'>vdbeapi.c</a> file contains external |
| 322 |
interfaces to the virtual machine such as the |
| 323 |
<a href="c3ref/bind_blob.html">sqlite3_bind_int()</a> and <a href="c3ref/step.html">sqlite3_step()</a>. Individual values |
| 324 |
(strings, integer, floating point numbers, and BLOBs) are stored |
| 325 |
in an internal object named "Mem" which is implemented by |
| 326 |
<a href='https://sqlite.org/src/file/src/vdbemem.c'>vdbemem.c</a>.</p> |
| 327 |
|
| 328 |
<p> |
| 329 |
SQLite implements SQL functions using callbacks to C-language routines. |
| 330 |
Even the built-in SQL functions are implemented this way. Most of |
| 331 |
the built-in SQL functions (ex: <a href="lang_corefunc.html#abs">abs()</a>, <a href="lang_aggfunc.html#count">count()</a>, |
| 332 |
<a href="lang_corefunc.html#substr">substr()</a>, and so forth) can be found in the <a href='https://sqlite.org/src/file/src/func.c'>func.c</a> source |
| 333 |
file. |
| 334 |
Date and time conversion functions are found in <a href='https://sqlite.org/src/file/src/date.c'>date.c</a>. |
| 335 |
Some functions such as <a href="lang_corefunc.html#coalesce">coalesce()</a> and <a href="lang_corefunc.html#typeof">typeof()</a> are implemented |
| 336 |
as bytecode directly by the code generator. |
| 337 |
</p> |
| 338 |
|
| 339 |
<h1>B-Tree</h1> |
| 340 |
|
| 341 |
<p>An SQLite database is maintained on disk using a B-tree implementation |
| 342 |
found in the <a href='https://sqlite.org/src/file/src/btree.c'>btree.c</a> source file. Separate B-trees are used for |
| 343 |
each table and each index in the database. All B-trees are stored in the |
| 344 |
same disk file. The <a href="fileformat2.html">file format</a> details are stable and well-defined and |
| 345 |
are guaranteed to be compatible moving forward.</p> |
| 346 |
|
| 347 |
<p>The interface to the B-tree subsystem and the rest of the SQLite library |
| 348 |
is defined by the header file <a href='https://sqlite.org/src/file/src/btree.h'>btree.h</a>. |
| 349 |
</p> |
| 350 |
|
| 351 |
<h1>Page Cache</h1> |
| 352 |
|
| 353 |
<p>The B-tree module requests information from the disk in fixed-size |
| 354 |
pages. The default <a href="pragma.html#pragma_page_size">page_size</a> is 4096 bytes but can be any power of |
| 355 |
two between 512 and 65536 bytes. |
| 356 |
The page cache is responsible for reading, writing, and |
| 357 |
caching these pages. |
| 358 |
The page cache also provides the rollback and atomic commit abstraction |
| 359 |
and takes care of locking of the database file. The |
| 360 |
B-tree driver requests particular pages from the page cache and notifies |
| 361 |
the page cache when it wants to modify pages or commit or rollback |
| 362 |
changes. The page cache handles all the messy details of making sure |
| 363 |
the requests are handled quickly, safely, and efficiently.</p> |
| 364 |
|
| 365 |
<p>The primary page cache implementation is in the |
| 366 |
<a href='https://sqlite.org/src/file/src/pager.c'>pager.c</a> file. <a href="wal.html">WAL mode</a> logic is in the separate |
| 367 |
<a href='https://sqlite.org/src/file/src/wal.c'>wal.c</a> file. In-memory caching is implemented by the |
| 368 |
<a href='https://sqlite.org/src/file/src/pcache.c'>pcache.c</a> and <a href='https://sqlite.org/src/file/src/pcache1.c'>pcache1.c</a> files. |
| 369 |
The interface between the page cache subsystem |
| 370 |
and the rest of SQLite is defined by the header file <a href='https://sqlite.org/src/file/src/pager.h'>pager.h</a>. |
| 371 |
</p> |
| 372 |
|
| 373 |
<h1>OS Interface</h1> |
| 374 |
|
| 375 |
<p> |
| 376 |
In order to provide portability across operating systems, |
| 377 |
SQLite uses an abstract object called the <a href="vfs.html">VFS</a>. Each VFS provides methods |
| 378 |
for opening, reading, writing, and closing files on disk, and for other |
| 379 |
OS-specific tasks such as finding the current time, or obtaining randomness |
| 380 |
to initialize the built-in pseudo-random number generator. |
| 381 |
SQLite currently provides VFSes for unix (in the <a href='https://sqlite.org/src/file/src/os_unix.c'>os_unix.c</a> |
| 382 |
file) and Windows (in the <a href='https://sqlite.org/src/file/src/os_win.c'>os_win.c</a> file). |
| 383 |
</p> |
| 384 |
|
| 385 |
<h1>Utilities</h1> |
| 386 |
|
| 387 |
<p> |
| 388 |
Memory allocation, caseless string comparison routines, |
| 389 |
portable text-to-number conversion routines, and other utilities |
| 390 |
are located in <a href='https://sqlite.org/src/file/src/util.c'>util.c</a>. |
| 391 |
Symbol tables used by the parser are maintained by hash tables found |
| 392 |
in <a href='https://sqlite.org/src/file/src/hash.c'>hash.c</a>. The <a href='https://sqlite.org/src/file/src/utf.c'>utf.c</a> source file contains Unicode |
| 393 |
conversion subroutines. |
| 394 |
SQLite has its own private implementation of |
| 395 |
<a href="printf.html">printf()</a> (with |
| 396 |
some extensions) in <a href='https://sqlite.org/src/file/src/printf.c'>printf.c</a> and its own |
| 397 |
pseudo-random number generator (PRNG) in <a href='https://sqlite.org/src/file/src/random.c'>random.c</a>. |
| 398 |
</p> |
| 399 |
|
| 400 |
<h1>Test Code</h1> |
| 401 |
|
| 402 |
<p> |
| 403 |
Files in the "src/" folder of the source tree whose names begin with |
| 404 |
<b>test</b> are for testing only and are not included in a standard |
| 405 |
build of the library. |
| 406 |
</p> |
| 407 |
|
| 408 |
<p align="center"><small><i>This page was last updated on 2025-05-31 13:08:22Z </small></i></p> |
| 409 |
|