Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Fixed #10031: updated SQLite database docs to more strongly indicate …

…the problems with versions before 3.3.6. Thanks, ramiro.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@10311 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit 1f74e3382fe8704270c4dcba49f2c25a433bfcc8 1 parent efd7141
Jacob Kaplan-Moss authored
81  docs/ref/databases.txt
@@ -351,44 +351,44 @@ will not work as expected for non-ASCII strings.
351 351
 
352 352
 .. _documented at sqlite.org: http://www.sqlite.org/faq.html#q18
353 353
 
354  
-Versions prior to 3.3.6
355  
-------------------------
  354
+SQLite 3.3.6 or newer strongly recommended
  355
+------------------------------------------
  356
+
  357
+Versions of SQLite 3.3.5 and older contains the following bugs:
  358
+
  359
+ * A bug when `handling`_ ``ORDER BY`` parameters. This can cause problems when
  360
+   you use the ``select`` parameter for the ``extra()`` QuerySet method. The bug
  361
+   can be identified by the error message ``OperationalError: ORDER BY terms
  362
+   must not be non-integer constants``.
  363
+
  364
+ * A bug when handling `aggregation`_ together with DateFields and
  365
+   DecimalFields.
  366
+
  367
+.. _handling: http://www.sqlite.org/cvstrac/tktview?tn=1768
  368
+.. _aggregation: http://code.djangoproject.com/ticket/10031
  369
+
  370
+SQLite 3.3.6 was released in April 2006, so most current binary distributions
  371
+for different platforms include newer version of SQLite usable from Python
  372
+through either the ``pysqlite2`` or the ``sqlite3`` modules.
  373
+
  374
+However, some platform/Python version combinations include older versions of
  375
+SQLite (e.g. the official binary distribution of Python 2.5 for Windows, 2.5.4
  376
+as of this writing, includes SQLite 3.3.4). There are (as of Django 1.1) even
  377
+some tests in the Django test suite that will fail when run under this setup.
356 378
 
357  
-Versions of SQLite 3.3.5 and older `contain a bug`_ when handling ``ORDER BY``
358  
-parameters. This can cause problems when you use the ``select`` parameter for
359  
-the ``extra()`` QuerySet method. The bug can be identified by the error message
360  
-``OperationalError: ORDER BY terms must not be non-integer constants``. The
361  
-problem can be solved updating SQLite to version 3.3.6 or newer, possibly also
362  
-updating the ``pysqlite2`` Python module in the process.
363  
-
364  
-.. _contain a bug: http://www.sqlite.org/cvstrac/tktview?tn=1768
365  
-
366  
-This has a very low impact because 3.3.6 was released in April 2006, so most
367  
-current binary distributions for different platforms include newer version of
368  
-SQLite usable from Python through either the ``pysqlite2`` or the ``sqlite3``
369  
-modules.
370  
-
371  
-However, in the case of Windows, the official binary distribution of the stable
372  
-release of Python 2.5 (2.5.2, as of this writing) includes SQLite 3.3.4, so the bug can
373  
-make itself evident in that platform. There are (as of Django 1.0) even three
374  
-tests in the Django test suite that will fail when run under this setup.  As
375  
-described above, this can be solved by downloading and installing a newer
376  
-version of ``pysqlite2`` (``pysqlite-2.x.x.win32-py2.5.exe``) that includes and
377  
-uses a newer version of SQLite. Python 2.6 ships with a newer version of
378  
-SQLite and is not affected by this issue.
379  
-
380  
-If you are on such a platform and find yourself needing to update
381  
-``pysqlite``/SQLite, you will also need to manually modify the
382  
-``django/db/backends/sqlite3/base.py`` file in the Django source tree so it
383  
-attempts to import ``pysqlite2`` before ``sqlite3`` and so it can take
384  
-advantage of the new ``pysqlite2``/SQLite versions.
  379
+As described :ref:`below<using-newer-versions-of-pysqlite>`, this can be solved
  380
+by downloading and installing a newer version of ``pysqlite2``
  381
+(``pysqlite-2.x.x.win32-py2.5.exe`` in the described case) that includes and
  382
+uses a newer version of SQLite. Python 2.6 for Windows ships with a version of
  383
+SQLite that is not affected by these issues.
385 384
 
386 385
 Version 3.5.9
387 386
 -------------
388 387
 
389  
-The Ubuntu "Intrepid Ibex" SQLite 3.5.9-3 package contains a bug that causes
390  
-problems with the evaluation of query expressions. If you are using Ubuntu
391  
-"Intrepid Ibex", you will need to find an alternate source for SQLite
  388
+The Ubuntu "Intrepid Ibex" (8.10) SQLite 3.5.9-3 package contains a bug that
  389
+causes problems with the evaluation of query expressions. If you are using
  390
+Ubuntu "Intrepid Ibex", you will need to update the package to version
  391
+3.5.9-3ubuntu1 or newer (recommended) or find an alternate source for SQLite
392 392
 packages, or install SQLite from source.
393 393
 
394 394
 At one time, Debian Lenny shipped with the same malfunctioning SQLite 3.5.9-3
@@ -411,6 +411,21 @@ You should avoid using this version of SQLite with Django. Either upgrade to
411 411
 3.6.3 (released September 22, 2008) or later, or downgrade to an earlier
412 412
 version of SQLite.
413 413
 
  414
+.. _using-newer-versions-of-pysqlite:
  415
+
  416
+Using newer versions of the SQLite DB-API 2.0 driver
  417
+----------------------------------------------------
  418
+
  419
+.. versionadded:: 1.1
  420
+
  421
+For versions of Python 2.5 or newer that include ``sqlite3`` in the standard
  422
+library Django will now use a ``pysqlite2`` interface in preference to
  423
+``sqlite3`` if it finds one is available.
  424
+
  425
+This provides the ability to upgrade both the DB-API 2.0 interface or SQLite 3
  426
+itself to versions newer than the ones included with your particular Python
  427
+binary distribution, if needed.
  428
+
414 429
 .. _oracle-notes:
415 430
 
416 431
 Oracle notes
14  docs/topics/install.txt
@@ -80,7 +80,7 @@ installed.
80 80
 * If you're using SQLite and either Python 2.3 or Python 2.4, you'll need
81 81
   pysqlite_. Use version 2.0.3 or higher. Python 2.5 ships with an SQLite
82 82
   wrapper in the standard library, so you don't need to install anything extra
83  
-  in that case.
  83
+  in that case. Please read the SQLite backend :ref:`notes<sqlite-notes>`.
84 84
 
85 85
 * If you're using Oracle, you'll need a copy of cx_Oracle_, but please
86 86
   read the database-specific notes for the
@@ -106,7 +106,7 @@ Django will need permission to create a test database.
106 106
 .. _compiled Windows version: http://stickpeople.com/projects/python/win-psycopg/
107 107
 .. _MySQLdb: http://sourceforge.net/projects/mysql-python
108 108
 .. _SQLite: http://www.sqlite.org/
109  
-.. _pysqlite: http://initd.org/pub/software/pysqlite/
  109
+.. _pysqlite: http://pysqlite.org/
110 110
 .. _cx_Oracle: http://cx-oracle.sourceforge.net/
111 111
 .. _Oracle: http://www.oracle.com/
112 112
 
@@ -132,14 +132,14 @@ This file should also be located in your ``site-packages`` directory.
132 132
     The location of the ``site-packages`` directory depends on the operating
133 133
     system, and the location in which Python was installed. To find out your
134 134
     system's ``site-packages`` location, execute the following:
135  
-    
  135
+
136 136
     .. code-block:: bash
137 137
 
138 138
         python -c "from distutils.sysconfig import get_python_lib; print get_python_lib()"
139 139
 
140 140
     (Note that this should be run from a shell prompt, not a Python interactive
141 141
     prompt.)
142  
-    
  142
+
143 143
 .. _install-django-code:
144 144
 
145 145
 Install the Django code
@@ -190,7 +190,7 @@ Installing the development version
190 190
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
191 191
 
192 192
 .. admonition:: Tracking Django development
193  
-    
  193
+
194 194
     If you decide to use the latest development version of Django,
195 195
     you'll want to pay close attention to `the development timeline`_,
196 196
     and you'll want to keep an eye on `the list of
@@ -219,7 +219,7 @@ latest bug fixes and improvements, follow these instructions:
219 219
 3. Next, make sure that the Python interpreter can load Django's code. There
220 220
    are various ways of accomplishing this.  One of the most convenient, on
221 221
    Linux, Mac OSX or other Unix-like systems, is to use a symbolic link:
222  
-   
  222
+
223 223
    .. code-block:: bash
224 224
 
225 225
        ln -s `pwd`/django-trunk/django SITE-PACKAGES-DIR/django
@@ -248,7 +248,7 @@ latest bug fixes and improvements, follow these instructions:
248 248
 4. On Unix-like systems, create a symbolic link to the file
249 249
    ``django-trunk/django/bin/django-admin.py`` in a directory on your system
250 250
    path, such as ``/usr/local/bin``. For example:
251  
-   
  251
+
252 252
    .. code-block:: bash
253 253
 
254 254
        ln -s `pwd`/django-trunk/django/bin/django-admin.py /usr/local/bin

0 notes on commit 1f74e33

Please sign in to comment.
Something went wrong with that request. Please try again.