== PREFACE ==

The reason we have our own QtSql Sqlite driver here is because the one shipped
with Qt misses a bunch of multi-threading fixes crucial for Akonadi. Of course,
these changes should be pushed upstream eventually.

== INSTALL ==
When Sqlite is found, the custom driver will be build and installed in:

${CMAKE_INSTALL_PREFIX}/lib/plugins/sqldrivers or ${QT_PLUGINS_DIR}/sqldrivers
if you enable the INSTALL_QSQLITE_IN_QT_PREFIX option when running CMake.

The next thing you have to do is add that path (if it isn't already) to your
QT_PLUGIN_PATH environment variable.

Now you should be able to configure the QSQLITE3 driver in akonadiserverrc.

== PROBLEMS ==

One of the problematic code paths seems to be:

server/src/handler/fetch.cpp:161-201

In this part the code is iterating over the results of an still active SELECT
query and during this iteration it also tries to do INSERT/UPDATE queries. This
means that there is probably a SHARED lock for the reading and a PENDING lock
for the writing queries. For sqlite to be able to write to the db it needs an
EXCLUSIVE lock. A PENDING lock only gets inclusive when all SHARED locks are
gone.

A possible solution might be to store the results of the SELECT query into
memory, close the query and than start the inserts/updates.


== SQLITE INFO ==

From www.sqlite.org: (see qsqlite/src/qsql_sqlite.cpp:525-529)
Run-time selection of threading mode

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.

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.