Documentation Source Text

[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>
................................................................................
connection separately, you might want to consider using the
[sqlite3_auto_extension()] interface to register your extensions and
to cause them to be automatically started as each database connection
is opened.  You only have to register each extension once, and you can
do so near the beginning of your main() routine.  Using the
[sqlite3_auto_extension()] interface to register your extensions makes
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>

[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].

<p>To clarify: an extension for which the initialization function returns
SQLITE_OK_LOAD_PERMANENTLY continues to exist in memory after the database
connection closes.  However, the extension is <em>not</em> automatically
registered with subsequent database connections.  This make it possible
to load extensions that implement new [VFSes].
To persistently load and register an extension that implements new SQL
functions, collating sequences, and/or virtual tables, such that those
added capabilities are available to all subsequent database connections,
then the initialization routine should also invoke [sqlite3_auto_extension()]
on a subfunction that will register those services.

<p>The [https://sqlite.org/src/file/ext/misc/vfsstat.c|vfsstat.c] extension
show an example of a loadable extension that persistently registers both
a new VFS and a new virtual table.  The
[https://sqlite.org/src/info/77b5b4235c9f7f11?ln=801-819|sqlite3_vfsstat_init()]
initialization routine in that extension is called only once, when the
extension is first loaded.  It registers the new "vfslog" VFS just that
one time, and it returns SQLITE_OK_LOAD_PERMANENTLY so that the code used
to implement the "vfslog" VFS will remain in memory. The initialization routine
also invokes [sqlite3_auto_extension()] on a pointer to the "vstatRegister()"
function so that all subsequent database connections will invoke the
"vstatRegister()" function as they start up, and hence register the
"vfsstat" virtual table.  

<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>
................................................................................
connection separately, you might want to consider using the
[sqlite3_auto_extension()] interface to register your extensions and
to cause them to be automatically started as each database connection
is opened.  You only have to register each extension once, and you can
do so near the beginning of your main() routine.  Using the
[sqlite3_auto_extension()] interface to register your extensions makes
your extensions work as if they were built into the core SQLite - they
automatically exist 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>