Documentation Source Text

<title>Run-Time Loadable Extensions</title>
<tcl>hd_keywords {loadext} {loadable extensions} {extension loading} \
                 {SQLite extension} {SQLite extensions} \
                 {loadable extension} \
                 {Run-Time Loadable Extensions}</tcl>

<h1 align="center">Run-Time Loadable Extensions</h1>



<p>SQLite has the ability to load extensions (including new
[application-defined SQL functions],
[collating sequences], [virtual tables], and [VFSes]) at run-time.
This feature allows the code for extensions to be developed and
tested separately from the application and then loaded
on an as-needed basis.</p>
................................................................................
<p>Extensions can also be statically linked with the application.
The code template shown below will work just as well as a statically
linked extension as it does as a run-time loadable extension except that
you should give the entry point function ("sqlite3_extension_init")
a different name to avoid name collisions if your application contains
two or more extensions.</p>

<h2>Loading An Extension</h2>

<p>An SQLite extension is a shared library or DLL.  To load it, you
need to supply SQLite with the name of the file containing the
shared library or DLL and an entry point to initialize the extension.
In C code, this information is supplied using the
[sqlite3_load_extension()] API.  See the documentation on that
routine for additional information.</p>
................................................................................

<blockquote><pre>
.load ./YourCode nonstandard_entry_point
</pre></blockquote>

<tcl>hd_fragment build {Compiling Loadable Extensions} \
                 {compile loadable extensions}</tcl>
<h2>Compiling A Loadable Extension</h2>

<p>Loadable extensions are C-code.  To compile them on
most unix-like operating
systems, the usual command is something like this:</p>

<blockquote><pre>
gcc -g -fPIC -shared YourCode.c -o YourCode.so
................................................................................
the -fPIC argument is omitted:</p>

<blockquote><pre>
gcc -g -shared YourCode.c -o YourCode.dll
</pre></blockquote>

<tcl>hd_fragment write {Programming Loadable Extensions}</tcl>
<h2>Programming Loadable Extensions</h2>

<p>A template loadable extension contains the following three elements:</p>

<ol>
<li><p>
Use "<tt>#include &lt;sqlite3ext.h&gt;</tt>" at the top of your source
code files instead of "<tt>#include &lt;sqlite3.h&gt;</tt>".
................................................................................
Put the macro "<tt>SQLITE_EXTENSION_INIT1</tt>" on a line by itself 
right after the "<tt>#include &lt;sqlite3ext.h&gt;</tt>" line.
</p>

<li><p>
Add an extension loading entry point routine that looks like 
something the following:
<blockquote><pre>

#ifdef _WIN32
__declspec(dllexport)
#endif
int sqlite3_extension_init( /* <== Change this name, maybe */
  sqlite3 *db, 
  char **pzErrMsg, 
  const sqlite3_api_routines *pApi
){
  int rc = SQLITE_OK;
  SQLITE_EXTENSION_INIT2(pApi);
  /* insert code to initialize your extension here */
  return rc;
}
</pre></blockquote>

<p>You will do well to customize the name of your entry point to
correspond to the name of the shared library you will be generating,
rather than using the generic "sqlite3_extension_init" name.  Giving
your extension a custom entry point name will enable you to statically
link two or more extensions into the same program without a linker
conflict, if you later decide to use static linking rather than run-time
linking.
................................................................................
"YourCode.dll" or "YourCode.dylib" as shown in the compiler examples
above, then the correct entry point name would be
"sqlite3_yourcode_init".
</ol>

<p>Here is a complete template extension that you can copy/paste 
to get started:</p>
<blockquote>
<pre style="background-color:#f3f3f3;border:1px #000 dashed;padding:0.5em">
/* Add your header comment here */
#include &lt;sqlite3ext.h&gt; /* Do not use &lt;sqlite3.h&gt;! */
SQLITE_EXTENSION_INIT1

/* Insert your extension code here */

#ifdef _WIN32
................................................................................
  **     sqlite3_create_collation_v2(),
  **     sqlite3_create_module_v2(), and/or
  **     sqlite3_vfs_register()
  ** to register the new features that your extension adds.
  */
  return rc;
}
</pre></blockquote>

<p>Many examples of complete and working loadable extensions can be seen in the
SQLite source tree in the
<a href="http://www.sqlite.org/src/tree?name=ext/misc&ci=trunk">ext/misc</a>
subdirectory.</p>

<tcl>hd_fragment persist {persistent loadable extensions}</tcl>
<h2>Persistent Loadable Extensions</h2>

<p>The default behavior for a loadable extension is that it is unloaded
from process memory when the database connection that orginally invoked
[sqlite3_load_extension()] closes.  (In other words, the xDlUnload method 
of the [sqlite3_vfs] object is called for all extensions when a database
connection closes.)  However, if the initialization procedure returns
[SQLITE_OK_LOAD_PERMANENTLY] instead of SQLITE_OK, then the extension will
not be unloaded (xDlClose will not be invoked) and the extension will remain
in process memory indefinitely.  The SQLITE_OK_LOAD_PERMANENTLY return
value is useful for extensions that want to register new [VFSes].

<h2>Statically Linking A Run-Time Loadable Extension</h2>

<p>The exact same source code can be used for both a run-time loadable
shared library or DLL and as a module that is statically linked with your
application.  This provides flexibility and allows you to reuse the same
code in different ways.</p>

<p>To statically link your extension, simply add the -DSQLITE_CORE
................................................................................
your extensions work as if they were built into the core SQLite - they
are automatically there whenever you open a new database connection
without needing to be initialized.  Just be sure to complete any
configuration you need to accomplish using [sqlite3_config()] before
registering your extensions, since the [sqlite3_auto_extension()]
interface implicitly calls [sqlite3_initialize()].</p>

<h2>Implementation Details</h2>

<p>SQLite implements run-time extension loading using the
xDlOpen(), xDlError(), xDlSym(), and xDlClose() methods of the
[sqlite3_vfs] object.  These methods are implemented using
the dlopen() library on unix (which explains why SQLite commonly
need to be linked against the "-ldl" library on unix systems)
and using LoadLibrary() API on Windows.  In a custom [VFS] for

<title>Run-Time Loadable Extensions</title>
<tcl>hd_keywords {loadext} {loadable extensions} {extension loading} \
                 {SQLite extension} {SQLite extensions} \
                 {loadable extension} \
                 {Run-Time Loadable Extensions}</tcl>

<table_of_contents>

<h1>Overview</h1>

<p>SQLite has the ability to load extensions (including new
[application-defined SQL functions],
[collating sequences], [virtual tables], and [VFSes]) at run-time.
This feature allows the code for extensions to be developed and
tested separately from the application and then loaded
on an as-needed basis.</p>
................................................................................
<p>Extensions can also be statically linked with the application.
The code template shown below will work just as well as a statically
linked extension as it does as a run-time loadable extension except that
you should give the entry point function ("sqlite3_extension_init")
a different name to avoid name collisions if your application contains
two or more extensions.</p>

<h1>Loading An Extension</h1>

<p>An SQLite extension is a shared library or DLL.  To load it, you
need to supply SQLite with the name of the file containing the
shared library or DLL and an entry point to initialize the extension.
In C code, this information is supplied using the
[sqlite3_load_extension()] API.  See the documentation on that
routine for additional information.</p>
................................................................................

<blockquote><pre>
.load ./YourCode nonstandard_entry_point
</pre></blockquote>

<tcl>hd_fragment build {Compiling Loadable Extensions} \
                 {compile loadable extensions}</tcl>
<h1>Compiling A Loadable Extension</h1>

<p>Loadable extensions are C-code.  To compile them on
most unix-like operating
systems, the usual command is something like this:</p>

<blockquote><pre>
gcc -g -fPIC -shared YourCode.c -o YourCode.so
................................................................................
the -fPIC argument is omitted:</p>

<blockquote><pre>
gcc -g -shared YourCode.c -o YourCode.dll
</pre></blockquote>

<tcl>hd_fragment write {Programming Loadable Extensions}</tcl>
<h1>Programming Loadable Extensions</h1>

<p>A template loadable extension contains the following three elements:</p>

<ol>
<li><p>
Use "<tt>#include &lt;sqlite3ext.h&gt;</tt>" at the top of your source
code files instead of "<tt>#include &lt;sqlite3.h&gt;</tt>".
................................................................................
Put the macro "<tt>SQLITE_EXTENSION_INIT1</tt>" on a line by itself 
right after the "<tt>#include &lt;sqlite3ext.h&gt;</tt>" line.
</p>

<li><p>
Add an extension loading entry point routine that looks like 
something the following:

<codeblock>
#ifdef _WIN32
__declspec(dllexport)
#endif
int sqlite3_extension_init( /* &lt;== Change this name, maybe */
  sqlite3 *db, 
  char **pzErrMsg, 
  const sqlite3_api_routines *pApi
){
  int rc = SQLITE_OK;
  SQLITE_EXTENSION_INIT2(pApi);
  /* insert code to initialize your extension here */
  return rc;
}
</codeblock>

<p>You will do well to customize the name of your entry point to
correspond to the name of the shared library you will be generating,
rather than using the generic "sqlite3_extension_init" name.  Giving
your extension a custom entry point name will enable you to statically
link two or more extensions into the same program without a linker
conflict, if you later decide to use static linking rather than run-time
linking.
................................................................................
"YourCode.dll" or "YourCode.dylib" as shown in the compiler examples
above, then the correct entry point name would be
"sqlite3_yourcode_init".
</ol>

<p>Here is a complete template extension that you can copy/paste 
to get started:</p>

<codeblock>
/* Add your header comment here */
#include &lt;sqlite3ext.h&gt; /* Do not use &lt;sqlite3.h&gt;! */
SQLITE_EXTENSION_INIT1

/* Insert your extension code here */

#ifdef _WIN32
................................................................................
  **     sqlite3_create_collation_v2(),
  **     sqlite3_create_module_v2(), and/or
  **     sqlite3_vfs_register()
  ** to register the new features that your extension adds.
  */
  return rc;
}
</codeblock>

<p>Many examples of complete and working loadable extensions can be seen in the
SQLite source tree in the
<a href="http://www.sqlite.org/src/tree?name=ext/misc&ci=trunk">ext/misc</a>
subdirectory.</p>

<tcl>hd_fragment persist {persistent loadable extensions}</tcl>
<h1>Persistent Loadable Extensions</h1>

<p>The default behavior for a loadable extension is that it is unloaded
from process memory when the database connection that orginally invoked
[sqlite3_load_extension()] closes.  (In other words, the xDlUnload method 
of the [sqlite3_vfs] object is called for all extensions when a database
connection closes.)  However, if the initialization procedure returns
[SQLITE_OK_LOAD_PERMANENTLY] instead of SQLITE_OK, then the extension will
not be unloaded (xDlClose will not be invoked) and the extension will remain
in process memory indefinitely.  The SQLITE_OK_LOAD_PERMANENTLY return
value is useful for extensions that want to register new [VFSes].

<h1>Statically Linking A Run-Time Loadable Extension</h1>

<p>The exact same source code can be used for both a run-time loadable
shared library or DLL and as a module that is statically linked with your
application.  This provides flexibility and allows you to reuse the same
code in different ways.</p>

<p>To statically link your extension, simply add the -DSQLITE_CORE
................................................................................
your extensions work as if they were built into the core SQLite - they
are automatically there whenever you open a new database connection
without needing to be initialized.  Just be sure to complete any
configuration you need to accomplish using [sqlite3_config()] before
registering your extensions, since the [sqlite3_auto_extension()]
interface implicitly calls [sqlite3_initialize()].</p>

<h1>Implementation Details</h1>

<p>SQLite implements run-time extension loading using the
xDlOpen(), xDlError(), xDlSym(), and xDlClose() methods of the
[sqlite3_vfs] object.  These methods are implemented using
the dlopen() library on unix (which explains why SQLite commonly
need to be linked against the "-ldl" library on unix systems)
and using LoadLibrary() API on Windows.  In a custom [VFS] for