<title>Using SQLite In Multi-Threaded Applications</title>
<tcl>hd_keywords {threading mode}</tcl>
<h2>SQLite And Multiple Threads</h2>
<p>SQLite support three different threading modes:</p>
<ol>
<li><p><b>Single-thread</b>.
In this mode, all mutexes are disabled and SQLite is unsafe to use in
more than a single thread at once.</p></li>
<li><p><b>Multi-thread</b>.
In this mode, SQLite can be safely used by multiple threads provided that
no single database connection is used simultaneously in two or more threads.
</p></li>
<li><p><b>Serialized</b>.
In serialized mode, SQLite can be safely used by multiple threads with no
restriction.</p></li>
</ol>
<p>
The threading mode can be selected at compile-time (when the SQLite
library is being compiled from source code) or at start-time (when the
application that intends to use SQLite is initializing) or at
run-time (when a new SQLite database connection is being created).
Generally speaking, run-time overrides start-time and start-time
overrides compile-time. Except, single-thread mode cannot be
overridden once selected.
</p>
<p>
The default mode is serialized.
</p>
<h3>Compile-time selection of threading mode</h3>
<p>
Use the [SQLITE_THREADSAFE] compile-time parameter to selected the
threading mode. If no [SQLITE_THREADSAFE] compile-time parameter is
present, then serialized mode is used.
This can be made explicit with
[SQLITE_THREADSAFE | -DSQLITE_THREADSAFE=1].
With
[SQLITE_THREADSAFE | -DSQLITE_THREADSAFE=0] the threading mode is
single-thread. With
[SQLITE_THREADSAFE | -DSQLITE_THREADSAFE=2] the threading mode is
multi-thread.
</p>
<p>
The return value of the [sqlite3_threadsafe()] interface is determined
by the compile-time threading mode selection. If single-thread mode
is selected at compile-time, then [sqlite3_threadsafe()] returns false.
If either the multi-thread or serialized modes are selected, then
[sqlite3_threadsafe()] returns true. The [sqlite3_threadsafe()]
interface predates the multi-thread mode and start-time and run-time
mode selection and so is unable to distinguish
between multi-thread and serialized mode nor is it able to report start-time
or run-time mode changes.
</p>
<p>
If single-thread mode is selected at compile-time, then critical
mutexing logic is omitted from the build and it is impossible to
enable either multi-thread or serialized modes at start-time or
run-time.
</p>
<h3>Start-time selection of threading mode</h3>
<p>
Assuming that the compile-time threading mode is not single-thread, then
the threading mode can be changed during initialization using the
[sqlite3_config()] interface. The [SQLITE_CONFIG_SINGLETHREAD] verb
puts SQLite into single-thread mode, the [SQLITE_CONFIG_MULTITHREAD]
verb sets multi-thread mode, and the [SQLITE_CONFIG_SERIALIZED] verb
sets serialized mode.
</p>
<h3>Run-time selection of threading mode</h3>
<p>If single-thread mode has not been selected at compile-time or start-time,
then individual database connections can be created as either multi-thread
or serialized. It is not possible to downgrade an individual database
connection to single-thread mode. Nor is it possible to escalate an
individual database connection if the compile-time or start-time mode
is single-thread.</p>
<p>The threading mode for an individual database connection is determined
by flags given as the third argument to [sqlite3_open_v2()]. The
[SQLITE_OPEN_NOMUTEX] flag causes the database connection to be in the
multi-thread mode and the [SQLITE_OPEN_FULLMUTEX] flag causes the connection
to be in serialized mode. If neither flag is specified or if
[sqlite3_open()] or [sqlite3_open16()] are used instead of
[sqlite3_open_v2()], then the default
mode determined by the compile-time and start-time settings is used.
</p>