|Version 28 (modified by 15 years ago) ( diff ),|
The SQLite library
Trac 0.9 works best with SQLite 3.x, like SQLite 3.2.8 or SQLite 3.3.x (latest is 3.3.8).
The latest stable version of SQLite can be obtained on the SQLite download page.
Building SQLite yourself
Note: If you want to use Trac in a multi-threaded setup
by using either TracModPython or TracStandalone, be sure to build a
thread-safe version of SQLite, by using the
If you use a non thread-safe library, which is unfortunately what you
get by default on non-windows platforms, you face the risk to get
persistent database locks (see #2170).
The Pysqlite2 bindings
The most stable version is now 2.3.2.
Detailed information about older releases:
- either the 1.x release branch of PySqlite
- version 1.1.6 as of this writing,
- version 1.1.7 required if using SQLite ≥ 3.3.3
- or, better, the newer 2.0.x release branch
- version ≥ 2.0.5 preferred,
- 2.0.3 has been reported to cause crashes on Windows
- version 2.0.7 required if using SQLite ≥ 3.3.3
- the 2.1.3 version appears to work well with Trac. This release branch features a new statement cache and a better handling of concurrent write operations.
- the 2.2.0 version appears to work with Trac as well (I tested the 2.4 egg from initd on Windows, and on Linux I built it from source, linking with sqlite-3.3.4; so far both are working perfectly)
- The source tarballs for the versions listed above are available from the initd.org Downloads page.
- If you're using Linux, you're certainly interested in getting one of the [Pysqlite:PysqlitePackages].
Upgrading SQLite from 2.x to 3.x
The following information is copied from http://dev.ctor.org/pkcs1/wiki/TracUpgrade
The database formats used by SQLite 2.x and sqlite 3.x are incompatible. If you upgrade your SQLite version (this can also happen implicitly if you upgrade from PySQLite 1.0.x to 1.1.x or 2.x), then you must convert your database.
To do this, install both SQLite 2.8 and SQLite 3.x (they have different filenames so can coexist in the same directory). Then use the following commands (Windows):
$ mv trac.db trac2.db $ sqlite trac2.db .dump | sqlite3 trac.db
Then when you're happy with the conversion and tested everything you can delete the trac2.db file.
Upgrading SQLite from 3.x.y to 3.x.z
It's almost the same as above. The following shows you how to upgrade from 3.2.8 to 3.3.4:
$ mv trac.db trac-old.db $ LD_LIBRARY_PATH=/opt/sqlite-3.2.8/lib /opt/sqlite-3.2.8/bin/sqlite3 \ trac-old.db .dump | \ LD_LIBRARY_PATH=/opt/sqlite-3.3.4/lib /opt/sqlite-3.3.4/bin/sqlite3 trac.db
From time to time, there are reports about problems related to Pysqlite and/or SQLite. This section willl guide you through understanding and fixing those issues, should those problems also happen to you.
Determine actual SQLite and PySqlite version
Troubleshooting is greatly helped by knowing exactly what versions are used for
sqlite inside your Python interpreter. Especially on *nix systems, a number of different versions might exist - and the actual versions linked and used might not be what you think.
To test what your Python installation uses, try this inside an interpreter:
>>> import trac.db.sqlite_backend >>> trac.db.sqlite_backend._ver (3, 1, 3) >>> trac.db.sqlite_backend.have_pysqlite 2 >>> trac.db.sqlite_backend.sqlite.version '2.3.2'
PySqlite is version 2 (2.3.2), compiled and linked to use version SQLite 3.1.3.
Another way to test the bindings with PySqlite 2 is to use:
>>> from pysqlite2 import dbapi2 as sqlite
This test should not fail.
OperationalError: unsupported file format
This probably is symptomatic of a mismatch between the SQLite library and the SQLite database format.
And this might be caused by a different version of PHP's pdo_sqlite module when you use Trac in mod_python mode. Check your pdo_sqlite module's version, or if ok, you may simply disable it (see /etc/php.d/pdo_sqlite.ini). (Note that sqlite 3.3.x and 3.2.x does not have compatibility.)
DatabaseError: file is encrypted or is not a database
Typical error seen when accessing a SQLite 2.x database file with a SQLite 3.x library.
OperationalError: SQL logic error or missing database
This can indicate that the database was corrupted.
A procedure similar to upgrading can be used in order to recover such a database:
sqlite3 corrupted.db .dump | sqlite3 recovered.db
(see #2598, for example)
This can also be the symptom of errors due to constraint violations
OperationalError: database is locked
There are numerous reasons why you can get this.
First, if this only happens occasionally and if the Trac server is still reachable after a second attempt, then it's not really a problem. This simply can happen and indicates that some other user was writing to the database at the same time your request triggerd an attempted to write. There are probably a few things that could be enhanced in the future to handle this situation, like automatic retry, see #3446.
Also, is this error is somehow inevitable with SQLite, we should make the error message a bit more "user friendly" (#3503).
The lock error is also much more frequent if SQLite is used in a multi-threaded environment (like TracStandalone or TracModPython) but the library was not compiled to be thread-safe. See above, building from source, and #2170.
The real problem with this occurs when all requests to Trac end up with this error. This indicates a permanent lock situation, which is not normal. Here are the known possible reasons for this:
- there was a crash related to some other part of the system, like due to the svn bindings, and the SQLite journal file (which is the materialization of the lock), was left behind. Simply removing the journal file will take care of the lock situation. Of course, you'll have to fix the faulty part of system in order to get rid of the crashes (e.g. see #1590).
- The Pysqlite version is older than 2.0.5 and/or Trac is pre0.9. Upgrading Trac and Pysqlite will solve the issue (see #2345)
See also: SQLite:DatabaseIsLocked.
ProgrammingError: library routine called out of sequence
This happens on MacOS X, and is still an open issue (see #2969)
See also: SQLite:LibraryRoutineCalledOutOfSequence.
Warning: You can only execute one statement at a time.
This is typically an error which happens when the pysqlite package
you're using is loading at runtime a
sqlite3.so library which has
a different version than the one against which pysqlite was built
(e.g. see #2993).
DatabaseError: database is full
Besides the obvious reason (no space left on the partition where
the trac db resides), you probably ran out of space in either
/var/tmp, where SQLite apparently needs to write too.
See #2356, #ps20.
NameError: global name 'sqlite' is not defined
This error usually comes from an invalid PySqlite installation:
The Python interpreter is not able to import the sqlite module.
... File ".../python2.3/site-packages/trac/db.py", line 321, in init_db cnx = sqlite.connect(path, timeout=int(params.get('timeout', 10000))) NameError: global name 'sqlite' is not defined ...
- Check that the sqlite Python module can be load from a Python interpreter
python >>> import sqlite
- Check that the Python intepreter that is run from the web server can find this module.
The default path for this module is
<python_lib_dir>/site-packages. If you've installed the module in another directory, make sure the
sys.pathvariable is set up with this directory (more on this in TracCgi, TracModPython, TracFastCgi).
A common mistake is to install PySqlite for one Python interpreter, and run the server with another Python interpreter: both interpreters do not use the same paths to search for modules.
_sqlite.so: Undefined symbol "PyGILState_Ensure"
If after the import test you encounter this message it most likely means that your Python was not compiled with threads support. On FreeBSD this is easily verified by doing a
grep -i threads /var/db/ports/python24/options. If it comes back with a
WITHOUT_THREADS=true you need to configure Python to be compiled with threads by executing
make config in the appropriate Python ports directory and subsequently recompile and replace Python.
Some old Python 2.3 versions (like on SuSE 9.0) have a bug related to gc and weakrefs, which might be triggered by Trac.
Segmentation faults can also happen in multi-threaded servers using a SQLite library which has not been configured to be multi-thread safe (see above).
Summary of Known Issues
P.S. Note that despite of all of the above, for some (most?) users, SQLite/Pysqlite works flawlessly :)