Debian Codegraph @

www/loadext.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>Run-Time Loadable Extensions</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 Run-Time Loadable Extensions
122 </div>
123 <details class="fancy_toc">
124 <summary>Table Of Contents</summary>
125 <div id="toc_sub"><div class="fancy-toc1"><a href="#overview">1. Overview</a></div>
126 <div class="fancy-toc1"><a href="#loading_an_extension">2. Loading An Extension</a></div>
127 <div class="fancy-toc1"><a href="#compiling_a_loadable_extension">3. Compiling A Loadable Extension</a></div>
128 <div class="fancy-toc1"><a href="#programming_loadable_extensions">4. Programming Loadable Extensions</a></div>
129 <div class="fancy-toc2"><a href="#example_extensions">4.1. Example Extensions</a></div>
130 <div class="fancy-toc1"><a href="#persistent_loadable_extensions">5. Persistent Loadable Extensions</a></div>
131 <div class="fancy-toc1"><a href="#statically_linking_a_run_time_loadable_extension">6. Statically Linking A Run-Time Loadable Extension</a></div>
132 <div class="fancy-toc1"><a href="#implementation_details">7. Implementation Details</a></div>
133 </div>
134 </details>
135 </div>
136
137
138
139
140
141 <h1 id="overview"><span>1. </span>Overview</h1>
142
143 <p>SQLite has the ability to load extensions (including new
144 <a href="appfunc.html">application-defined SQL functions</a>,
145 <a href="datatype3.html#collation">collating sequences</a>, <a href="vtab.html">virtual tables</a>, and <a href="vfs.html">VFSes</a>) at run-time.
146 This feature allows the code for extensions to be developed and
147 tested separately from the application and then loaded
148 on an as-needed basis.</p>
149
150 <p>Extensions can also be statically linked with the application.
151 The code template shown below will work just as well as a statically
152 linked extension as it does as a run-time loadable extension except that
153 you should give the entry point function ("sqlite3_extension_init")
154 a different name to avoid name collisions if your application contains
155 two or more extensions.</p>
156
157 <h1 id="loading_an_extension"><span>2. </span>Loading An Extension</h1>
158
159 <p>An SQLite extension is a shared library or DLL. To load it, you
160 need to supply SQLite with the name of the file containing the
161 shared library or DLL and an entry point to initialize the extension.
162 In C code, this information is supplied using the
163 <a href="c3ref/load_extension.html">sqlite3_load_extension()</a> API. See the documentation on that
164 routine for additional information.</p>
165
166 <p>Note that different operating systems use different filename
167 suffixes for their shared libraries. Windows uses ".dll", Mac uses
168 ".dylib", and most unixes other than mac use ".so". If you want to
169 make your code portable, you can omit the suffix from the shared
170 library filename and the appropriate suffix will be added automatically
171 by the <a href="c3ref/load_extension.html">sqlite3_load_extension()</a> interface.</p>
172
173 <p>There is also an SQL function that can be used to load extensions:
174 <a href="lang_corefunc.html#load_extension">load_extension(X,Y)</a>. It works just like the <a href="c3ref/load_extension.html">sqlite3_load_extension()</a>
175 C interface.</p>
176
177 <p>Both methods for loading an extension allow you to specify
178 the name of an entry point for the extension.
179 You can leave this argument blank - passing in
180 a NULL pointer for the <a href="c3ref/load_extension.html">sqlite3_load_extension()</a> C-language interface
181 or omitting the second argument for the <a href="lang_corefunc.html#load_extension">load_extension()</a> SQL interface -
182 and the extension loader logic will attempt to figure out the entry point
183 on its own. It will first try the generic extension name
184 "sqlite3_extension_init". If that does not work, it constructs an
185 entry point using the template "sqlite3_X_init" where the X is replaced
186 by the lowercase equivalent of every ASCII character in the filename
187 after the last "/" and before the first following "." omitting the
188 first three characters if they happen to be "lib". So, for example,
189 if the filename is "/usr/lib/libmathfunc-4.8.so" the entry point name
190 would be "sqlite3_mathfunc_init". Or if the filename is
191 "./SpellFixExt.dll" then the entry point would be called
192 "sqlite3_spellfixext_init".
193
194 </p><p>For security reasons, extension loading is turned off by default.
195 In order to use either the C-language or SQL extension loading functions,
196 one must first enable extension loading using the
197 <a href="c3ref/db_config.html">sqlite3_db_config</a>(db,<a href="c3ref/c_dbconfig_defensive.html#sqlitedbconfigenableloadextension">SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION</a>,1,NULL)
198 C-language API in your application.</p>
199
200 <p>From the <a href="cli.html">command-line shell</a>, extensions can be loaded using the
201 ".load" dot-command. For example:
202
203 </p><blockquote><pre>
204 .load ./YourCode
205 </pre></blockquote>
206
207 <p>Note that the command-line shell program has already enabled
208 extension loading for you (by calling the <a href="c3ref/enable_load_extension.html">sqlite3_enable_load_extension()</a>
209 interface as part of its setup) so the command above works without
210 any special switches, setup, or other complications.</p>
211
212 <p>The ".load" command with one argument invokes sqlite3_load_extension()
213 with the zProc parameter set to NULL, causing SQLite to first look for
214 an entry point named "sqlite3_extension_init" and then "sqlite3_X_init"
215 where "X" is derived from the filename. If your extension has an entry
216 point with a different name, simply supply that name as the second
217 argument. For example:</p>
218
219 <blockquote><pre>
220 .load ./YourCode nonstandard_entry_point
221 </pre></blockquote>
222
223 <a name="build"></a>
224
225 <h1 id="compiling_a_loadable_extension"><span>3. </span>Compiling A Loadable Extension</h1>
226
227 <p>Loadable extensions are C-code. To compile them on
228 most unix-like operating
229 systems, the usual command is something like this:</p>
230
231 <blockquote><pre>
232 gcc -g -fPIC -shared YourCode.c -o YourCode.so
233 </pre></blockquote>
234
235 <p>Macs are unix-like, but they do not follow the usual shared library
236 conventions. To compile a shared library on a Mac, use a command like
237 this:</p>
238
239 <blockquote><pre>
240 gcc -g -fPIC -dynamiclib YourCode.c -o YourCode.dylib
241 </pre></blockquote>
242
243 <p>If when you try to load your library you get back an error message
244 that says "mach-o, but wrong architecture" then you might need to add
245 command-line options "-arch i386" or "arch x86_64" to gcc, depending
246 on how your application is built.</p>
247
248 <p>To compile on Windows using MSVC, a command similar to the following
249 will usually work:</p>
250
251 <blockquote><pre>
252 cl YourCode.c -link -dll -out:YourCode.dll
253 </pre></blockquote>
254
255 <p>To compile for Windows using MinGW, the command line is just like it
256 is for unix except that the output file suffix is changed to ".dll" and
257 the -fPIC argument is omitted:</p>
258
259 <blockquote><pre>
260 gcc -g -shared YourCode.c -o YourCode.dll
261 </pre></blockquote>
262
263 <a name="write"></a>
264
265 <h1 id="programming_loadable_extensions"><span>4. </span>Programming Loadable Extensions</h1>
266
267 <p>A template loadable extension contains the following three elements:</p>
268
269 <ol>
270 <li><p>
271 Use "<tt>#include &lt;sqlite3ext.h&gt;</tt>" at the top of your source
272 code files instead of "<tt>#include &lt;sqlite3.h&gt;</tt>".
273 </p>
274
275 </li><li><p>
276 Put the macro "<tt>SQLITE_EXTENSION_INIT1</tt>" on a line by itself
277 right after the "<tt>#include &lt;sqlite3ext.h&gt;</tt>" line.
278 </p>
279
280 </li><li><p>
281 Add an extension loading entry point routine that looks something like
282 the following:
283
284 </p><div class="codeblock"><pre>#ifdef _WIN32
285 __declspec(dllexport)
286 #endif
287 int sqlite3_extension_init( /* &lt;== Change this name, maybe */
288 sqlite3 *db,
289 char **pzErrMsg,
290 const sqlite3_api_routines *pApi
291 ){
292 int rc = SQLITE_OK;
293 SQLITE_EXTENSION_INIT2(pApi);
294 /* insert code to initialize your extension here */
295 return rc;
296 }
297 </pre></div>
298
299 <p>You will do well to customize the name of your entry point to
300 correspond to the name of the shared library you will be generating,
301 rather than using the generic "sqlite3_extension_init" name. Giving
302 your extension a custom entry point name will enable you to statically
303 link two or more extensions into the same program without a linker
304 conflict, if you later decide to use static linking rather than run-time
305 linking.
306 If your shared library ends up being named "YourCode.so" or
307 "YourCode.dll" or "YourCode.dylib" as shown in the compiler examples
308 above, then the correct entry point name would be
309 "sqlite3_yourcode_init".
310 </p></li></ol>
311
312 <p>Here is a complete template extension that you can copy/paste
313 to get started:</p>
314
315 <div class="codeblock"><pre>/* Add your header comment here */
316 #include &lt;sqlite3ext.h&gt; /* Do not use &lt;sqlite3.h&gt;! */
317 SQLITE_EXTENSION_INIT1
318
319 /* Insert your extension code here */
320
321 #ifdef _WIN32
322 __declspec(dllexport)
323 #endif
324 /* TODO: Change the entry point name so that "extension" is replaced by
325 ** text derived from the shared library filename as follows: Copy every
326 ** ASCII alphabetic character from the filename after the last "/" through
327 ** the next following ".", converting each character to lowercase, and
328 ** discarding the first three characters if they are "lib".
329 */
330 int sqlite3_extension_init(
331 sqlite3 *db,
332 char **pzErrMsg,
333 const sqlite3_api_routines *pApi
334 ){
335 int rc = SQLITE_OK;
336 SQLITE_EXTENSION_INIT2(pApi);
337 /* Insert here calls to
338 ** sqlite3_create_function_v2(),
339 ** sqlite3_create_collation_v2(),
340 ** sqlite3_create_module_v2(), and/or
341 ** sqlite3_vfs_register()
342 ** to register the new features that your extension adds.
343 */
344 return rc;
345 }
346 </pre></div>
347
348 <h2 id="example_extensions"><span>4.1. </span>Example Extensions</h2>
349
350 <p>Many examples of complete and working loadable extensions can be
351 seen in the SQLite source tree in the
352 <a href="https://sqlite.org/src/file/ext/misc">ext/misc</a> subdirectory.
353 Each file in that directory is a separate extension. Documentation
354 is provided by a header comment on the file.
355 Here are brief notes on a few of the extensions in
356 the <a href="https://sqlite.org/src/file/ext/misc">ext/misc</a> subdirectory:
357
358 </p><ul>
359 <li><p>
360 <a href="https://sqlite.org/src/file/ext/misc/carray.c">carray.c</a> &mdash;
361 Implementation of the <a href="carray.html">carray table-valued function</a>.
362 </p></li><li><p>
363 <a href="https://sqlite.org/src/file/ext/misc/compress.c">compress.c</a> &mdash;
364 Implementation of <a href="appfunc.html">application-defined SQL functions</a> compress() and
365 uncompress() that do zLib compression of text or blob content.
366 </p></li><li><p>
367 <a href="https://sqlite.org/src/file/ext/misc/rot13.c">rot13.c</a> &mdash;
368 Implementation of a <a href="https://en.wikipedia.org/wiki/ROT13">rot13()</a>
369 SQL function. This is a very simple example of an extension function
370 and is useful as a template for creating new extensions.
371 </p></li><li><p>
372 <a href="https://sqlite.org/src/file/ext/misc/series.c">series.c</a> &mdash;
373 Implementation of the generate_series <a href="vtab.html">virtual table</a> and
374 <a href="vtab.html#tabfunc2">table-valued function</a>. This is a relatively simple example of a
375 virtual table implementation which can serve as a template for writing
376 new virtual tables.
377 </p></li></ul>
378
379 <p>Other and more complex extensions can be found in subfolders
380 under <a href="https://sqlite.org/src/file/ext">ext/</a> other than ext/misc/.
381
382 <a name="persist"></a>
383
384 </p><h1 id="persistent_loadable_extensions"><span>5. </span>Persistent Loadable Extensions</h1>
385
386 <p>The default behavior for a loadable extension is that it is unloaded
387 from process memory when the database connection that originally invoked
388 <a href="c3ref/load_extension.html">sqlite3_load_extension()</a> closes. (In other words, the xDlClose method
389 of the <a href="c3ref/vfs.html">sqlite3_vfs</a> object is called for all extensions when a database
390 connection closes.) However, if the initialization procedure returns
391 <a href="rescode.html#ok_load_permanently">SQLITE_OK_LOAD_PERMANENTLY</a> instead of SQLITE_OK, then the extension will
392 not be unloaded (xDlClose will not be invoked) and the extension will remain
393 in process memory indefinitely. The SQLITE_OK_LOAD_PERMANENTLY return
394 value is useful for extensions that want to register new <a href="vfs.html">VFSes</a>.
395
396 </p><p>To clarify: an extension for which the initialization function returns
397 SQLITE_OK_LOAD_PERMANENTLY continues to exist in memory after the database
398 connection closes. However, the extension is <em>not</em> automatically
399 registered with subsequent database connections. This makes it possible
400 to load extensions that implement new <a href="vfs.html">VFSes</a>.
401 To persistently load and register an extension that implements new SQL
402 functions, collating sequences, and/or virtual tables, such that those
403 added capabilities are available to all subsequent database connections,
404 then the initialization routine should also invoke <a href="c3ref/auto_extension.html">sqlite3_auto_extension()</a>
405 on a subfunction that will register those services.
406
407 </p><p>The <a href="https://sqlite.org/src/file/ext/misc/vfsstat.c">vfsstat.c</a> extension
408 show an example of a loadable extension that persistently registers both
409 a new VFS and a new virtual table. The
410 <a href="https://sqlite.org/src/info/77b5b4235c9f7f11?ln=801-819">sqlite3_vfsstat_init()</a>
411 initialization routine in that extension is called only once, when the
412 extension is first loaded. It registers the new "vfslog" VFS just that
413 one time, and it returns SQLITE_OK_LOAD_PERMANENTLY so that the code used
414 to implement the "vfslog" VFS will remain in memory. The initialization routine
415 also invokes <a href="c3ref/auto_extension.html">sqlite3_auto_extension()</a> on a pointer to the "vstatRegister()"
416 function so that all subsequent database connections will invoke the
417 "vstatRegister()" function as they start up, and hence register the
418 "vfsstat" virtual table.
419
420 <a name="statext"></a>
421
422 </p><h1 id="statically_linking_a_run_time_loadable_extension"><span>6. </span>Statically Linking A Run-Time Loadable Extension</h1>
423
424 <p>The exact same source code can be used for both a run-time loadable
425 shared library or DLL and as a module that is statically linked with your
426 application. This provides flexibility and allows you to reuse the same
427 code in different ways.</p>
428
429 <p>To statically link your extension, simply add the -DSQLITE_CORE
430 compile-time option. The SQLITE_CORE macro causes the SQLITE_EXTENSION_INIT1
431 and SQLITE_EXTENSION_INIT2 macros to become no-ops. Then modify your
432 application to invoke the entry point directly, passing in a NULL pointer
433 as the third "pApi" parameter.</p>
434
435 <p>It is particularly important to use an entry point name that is
436 based on the extension filename, rather than the generic
437 "sqlite3_extension_init" entry point name, if you will be statically
438 linking two or more extensions. If you use the generic name, there
439 will be multiple definitions of the same symbol and the link will fail.</p>
440
441 <p>If you will be opening multiple database connections in your application,
442 rather than invoking the extension entry points for each database
443 connection separately, you might want to consider using the
444 <a href="c3ref/auto_extension.html">sqlite3_auto_extension()</a> interface to register your extensions and
445 to cause them to be automatically started as each database connection
446 is opened. You only have to register each extension once, and you can
447 do so near the beginning of your main() routine. Using the
448 <a href="c3ref/auto_extension.html">sqlite3_auto_extension()</a> interface to register your extensions makes
449 your extensions work as if they were built into the core SQLite - they
450 automatically exist whenever you open a new database connection
451 without needing to be initialized. Just be sure to complete any
452 configuration you need to accomplish using <a href="c3ref/config.html">sqlite3_config()</a> before
453 registering your extensions, since the <a href="c3ref/auto_extension.html">sqlite3_auto_extension()</a>
454 interface implicitly calls <a href="c3ref/initialize.html">sqlite3_initialize()</a>.</p>
455
456 <h1 id="implementation_details"><span>7. </span>Implementation Details</h1>
457
458 <p>SQLite implements run-time extension loading using the
459 xDlOpen(), xDlError(), xDlSym(), and xDlClose() methods of the
460 <a href="c3ref/vfs.html">sqlite3_vfs</a> object. These methods are implemented using
461 the dlopen() library on unix (which explains why SQLite commonly
462 needs to be linked against the "-ldl" library on unix systems)
463 and using LoadLibrary() API on Windows. In a custom <a href="vfs.html">VFS</a> for
464 unusual systems, these methods can all be omitted, in which case
465 the run-time extension loading mechanism will not work (though
466 you will still be able to statically link the extension code, assuming
467 the entry pointers are uniquely named).
468 SQLite can be compiled with
469 <a href="compile.html#omit_load_extension">SQLITE_OMIT_LOAD_EXTENSION</a> to omit the extension loading code
470 from the build.
471 </p><p align="center"><small><i>This page was last updated on 2025-11-13 07:12:58Z </small></i></p>
472