Edgewall Software

Changes between Version 12 and Version 13 of PySqlite


Ignore:
Timestamp:
Apr 8, 2006, 8:34:41 PM (18 years ago)
Author:
Christian Boos
Comment:

Lots of refactoring + started new troubleshooting section

Legend:

Unmodified
Added
Removed
Modified

  • PySqlite

    v12 v13  
    22
    33[http://initd.org/tracker/pysqlite PySqlite] is a Python binding
    4 ''for'' the [http://www.sqlite.org SQLite] light-weight database engine,
     4for the [http://www.sqlite.org SQLite] light-weight database engine,
    55which is Trac's default DatabaseBackend.
    66
    7 It '''should''' still be possible to use the old SQLite 2.8.x (everything except search seems to work)
    8 with the Pysqlite [http://initd.org/pub/software/pysqlite/releases/1.0/1.0.1 1.0.1],
    9 but Trac 0.9 works best with '''SQLite 3.2.8'''. The compatible
    10 Python bindings are:
     7== Installation ==
     8=== The SQLite library ===
     9
     10Trac 0.9 works best with '''[http://www.sqlite.org/version3.html SQLite 3.x]''',
     11like SQLite 3.2.8 or SQLite 3.3.x.
     12
     13Pay attention to
     14[http://www.sqlite.org/formatchng.html database format changes]
     15when upgrading the SQLite library.
     16See below how to [wiki:PySqlite#Upgradingsqlite upgrade] your database,
     17if needed.
     18
     19 ''It should still be possible to use the old SQLite 2.8.x version:
     20 everything seems to work (except the search, see #2960)
     21 You should then use an equally old Pysqlite version, namely
     22 [http://initd.org/pub/software/pysqlite/releases/1.0/1.0.1 1.0.1].''
     23
     24==== Downloading SQLite ====
     25
     26The latest stable version of SQLite can be obtained on the
     27[http://www.sqlite.org/download.html SQLite download] page.
     28
     29==== Building SQLite yourself ====
     30'''Note:''' If you want to use Trac in a multi-threaded setup
     31by using either TracModPython or TracStandalone, be sure to build a
     32'''thread-safe version of SQLite''', by using the `--enable-threadsafe`
     33configuration switch.
     34If you use a non thread-safe library, which is unfortunately what you
     35get by default on non-windows platforms, you face the risk to get
     36persistent database locks (see #2170).
     37
     38=== The Pysqlite2 bindings ===
     39
     40The most stable versions are '''2.0.7''' and '''2.1.3'''.
     41
     42'''2.2.0''' is probably rock solid as well, but it's a bit too early to tell.
     43
     44Detailed release information:
    1145 * either the 1.x release branch of PySqlite
    1246   * version 1.1.6 as of this writing,
    … …  
    2458   are working perfectly)
    2559
    26 Recent versions are available from the
     60==== Downloading Pysqlite ====
     61The versions listed above are available from the
    2762[http://initd.org/tracker/pysqlite/wiki#Downloads initd.org Downloads] page.
    2863
    2964
    30 '''Note:''' If you want to use Trac in a multi-threaded setup
    31 by using either TracModPython or TracStandalone, be sure to build a
    32 '''thread-safe version of SQLite''', by using the `--enable-threadsafe`
    33 configuration switch.
    34 If you use a non thread-safe library, which is unfortunately what you
    35 get by default on non-windows platforms, you face the risk to get
    36 persistent database locks (see #2170).
    37 
    38 
    39 == Upgrading SQLite from 2.x to 3.x ==
     65== Upgrading SQLite ==
     66=== Upgrading SQLite from 2.x to 3.x ===
    4067The following information is copied from http://dev.ctor.org/pkcs1/wiki/TracUpgrade
    4168
    … …  
    5077Then when you're happy with the conversion and tested everything  you can delete the trac2.db file.
    5178
    52  '''Note:'''
    53  A similar procedure (`sqlite3 corrupted.db .dump | sqlite3 recovered.db`)
    54  can also be used to recover a corrupted database file (see #2598, for example).
     79=== Upgrading SQLite from 3.x.y to 3.x.z ===
     80
     81It's almost the same as above.
     82The following shows you how to upgrade from 3.2.8 to 3.3.4:
     83
     84{{{
     85 $ mv trac.db trac-old.db
     86 $ LD_LIBRARY_PATH=/opt/sqlite-3.2.8/lib /opt/sqlite-3.2.8/bin/sqlite3 \
     87     trac-old.db .dump | \
     88   LD_LIBRARY_PATH=/opt/sqlite-3.3.4/lib /opt/sqlite-3.3.4/bin/sqlite3 trac.db
     89}}}
    5590
    5691
    57 For more information see http://www.sqlite.org/version3.html
     92== Troubleshooting ==
     93
     94From time to time, there are reports about problems related to
     95Pysqlite and/or SQLite. This section willl guide you through
     96understanding and fixing those issues, should those problems
     97also happen to you.
     98
     99=== `OperationalError: unsupported file format` ===
     100
     101  ''This probably is symptomatic of a mismatch between the SQLite library and the SQLite database format.''
     102
     103See [http://permalink.gmane.org/gmane.comp.version-control.subversion.trac.general/7540 Trac-ML:7540]
     104
     105=== `OperationalError: SQL logic error or missing database` ===
     106
     107  ''This can indicate that the database was corrupted.''
     108
     109A procedure similar to upgrading can be used in order to recover
     110such a database:
     111{{{
     112sqlite3 corrupted.db .dump | sqlite3 recovered.db
     113}}}
     114
     115(see #2598, for example)
     116
     117  ''This can also be the symptom of errors due to constraint violations''
     118
     119And this ''might'' correspond to an open bug. See #2902 and #2570.
     120
     121=== `OperationalError: database is locked` ===
     122
     123There are numerous reasons why you can get this.
     124
     125First, if this only happens occasionally and if the Trac server
     126is still reachable after a second attempt, then it's not really
     127a problem. This simply can happen and indicates that some
     128other user was writing to the database at the same time your
     129request triggerd an attempted to write.
     130There are probably a few things that could be enhanced in the
     131future to handle this situation, like automatic retry (or improve
     132the session code).
     133
     134The lock error is also much more frequent if SQLite is used in a
     135multi-threaded environment (like TracStandalone or TracModPython)
     136but the library was not compiled to be thread-safe.
     137See above [wiki:PySqlite#Buildingsqliteyourself building from source]
     138and #2170.
     139
     140The real problem with this occurs when ''all'' requests to Trac
     141end up with this error. This indicates a permanent lock situation,
     142which is not normal. Here are the known possible reasons for this:
     143 * there was a crash related to some other part of the system,
     144   like due to the svn bindings, and the SQLite journal file
     145   (which is the materialization of the lock), was left behind.
     146   Simply removing the journal file will take care of the lock
     147   situation. Of course, you'll have to fix the faulty part of
     148   system in order to get rid of the crashes (e.g. see #1590).
     149 * The Pysqlite version is older than 2.0.5 and/or Trac is pre0.9.
     150   Upgrading Trac and Pysqlite will solve the issue (see #2345)
     151
     152=== `ProgrammingError: library routine called out of sequence` ===
     153
     154This happens on MacOS X, and is still an open issue (see #2969)
     155
     156=== `Segmentation Fault` ===
     157
     158Some old Python 2.3 versions (like on SuSE 9.0) have a bug
     159related to gc and weakrefs, which might be triggered by Trac.
     160
     161([http://projects.edgewall.com/trac/ticket/2170#change_8 details])
     162
     163
     164'''P.S. Note that despite of all of the above, for some (most?) users, SQLite/Pysqlite works flawlessly :)'''