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
This commit is contained in:
Jacob Kaplan-Moss 2009-04-01 01:36:44 +00:00
parent efd7141d70
commit 1f74e3382f
2 changed files with 51 additions and 36 deletions

View File

@ -351,44 +351,44 @@ will not work as expected for non-ASCII strings.
.. _documented at sqlite.org: http://www.sqlite.org/faq.html#q18
Versions prior to 3.3.6
------------------------
SQLite 3.3.6 or newer strongly recommended
------------------------------------------
Versions of SQLite 3.3.5 and older `contain a bug`_ when handling ``ORDER BY``
parameters. This can cause problems when you use the ``select`` parameter for
the ``extra()`` QuerySet method. The bug can be identified by the error message
``OperationalError: ORDER BY terms must not be non-integer constants``. The
problem can be solved updating SQLite to version 3.3.6 or newer, possibly also
updating the ``pysqlite2`` Python module in the process.
Versions of SQLite 3.3.5 and older contains the following bugs:
.. _contain a bug: http://www.sqlite.org/cvstrac/tktview?tn=1768
* A bug when `handling`_ ``ORDER BY`` parameters. This can cause problems when
you use the ``select`` parameter for the ``extra()`` QuerySet method. The bug
can be identified by the error message ``OperationalError: ORDER BY terms
must not be non-integer constants``.
This has a very low impact because 3.3.6 was released in April 2006, so most
current binary distributions for different platforms include newer version of
SQLite usable from Python through either the ``pysqlite2`` or the ``sqlite3``
modules.
* A bug when handling `aggregation`_ together with DateFields and
DecimalFields.
However, in the case of Windows, the official binary distribution of the stable
release of Python 2.5 (2.5.2, as of this writing) includes SQLite 3.3.4, so the bug can
make itself evident in that platform. There are (as of Django 1.0) even three
tests in the Django test suite that will fail when run under this setup. As
described above, this can be solved by downloading and installing a newer
version of ``pysqlite2`` (``pysqlite-2.x.x.win32-py2.5.exe``) that includes and
uses a newer version of SQLite. Python 2.6 ships with a newer version of
SQLite and is not affected by this issue.
.. _handling: http://www.sqlite.org/cvstrac/tktview?tn=1768
.. _aggregation: http://code.djangoproject.com/ticket/10031
If you are on such a platform and find yourself needing to update
``pysqlite``/SQLite, you will also need to manually modify the
``django/db/backends/sqlite3/base.py`` file in the Django source tree so it
attempts to import ``pysqlite2`` before ``sqlite3`` and so it can take
advantage of the new ``pysqlite2``/SQLite versions.
SQLite 3.3.6 was released in April 2006, so most current binary distributions
for different platforms include newer version of SQLite usable from Python
through either the ``pysqlite2`` or the ``sqlite3`` modules.
However, some platform/Python version combinations include older versions of
SQLite (e.g. the official binary distribution of Python 2.5 for Windows, 2.5.4
as of this writing, includes SQLite 3.3.4). There are (as of Django 1.1) even
some tests in the Django test suite that will fail when run under this setup.
As described :ref:`below<using-newer-versions-of-pysqlite>`, this can be solved
by downloading and installing a newer version of ``pysqlite2``
(``pysqlite-2.x.x.win32-py2.5.exe`` in the described case) that includes and
uses a newer version of SQLite. Python 2.6 for Windows ships with a version of
SQLite that is not affected by these issues.
Version 3.5.9
-------------
The Ubuntu "Intrepid Ibex" SQLite 3.5.9-3 package contains a bug that causes
problems with the evaluation of query expressions. If you are using Ubuntu
"Intrepid Ibex", you will need to find an alternate source for SQLite
The Ubuntu "Intrepid Ibex" (8.10) SQLite 3.5.9-3 package contains a bug that
causes problems with the evaluation of query expressions. If you are using
Ubuntu "Intrepid Ibex", you will need to update the package to version
3.5.9-3ubuntu1 or newer (recommended) or find an alternate source for SQLite
packages, or install SQLite from source.
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
3.6.3 (released September 22, 2008) or later, or downgrade to an earlier
version of SQLite.
.. _using-newer-versions-of-pysqlite:
Using newer versions of the SQLite DB-API 2.0 driver
----------------------------------------------------
.. versionadded:: 1.1
For versions of Python 2.5 or newer that include ``sqlite3`` in the standard
library Django will now use a ``pysqlite2`` interface in preference to
``sqlite3`` if it finds one is available.
This provides the ability to upgrade both the DB-API 2.0 interface or SQLite 3
itself to versions newer than the ones included with your particular Python
binary distribution, if needed.
.. _oracle-notes:
Oracle notes

View File

@ -80,7 +80,7 @@ installed.
* If you're using SQLite and either Python 2.3 or Python 2.4, you'll need
pysqlite_. Use version 2.0.3 or higher. Python 2.5 ships with an SQLite
wrapper in the standard library, so you don't need to install anything extra
in that case.
in that case. Please read the SQLite backend :ref:`notes<sqlite-notes>`.
* If you're using Oracle, you'll need a copy of cx_Oracle_, but please
read the database-specific notes for the
@ -106,7 +106,7 @@ Django will need permission to create a test database.
.. _compiled Windows version: http://stickpeople.com/projects/python/win-psycopg/
.. _MySQLdb: http://sourceforge.net/projects/mysql-python
.. _SQLite: http://www.sqlite.org/
.. _pysqlite: http://initd.org/pub/software/pysqlite/
.. _pysqlite: http://pysqlite.org/
.. _cx_Oracle: http://cx-oracle.sourceforge.net/
.. _Oracle: http://www.oracle.com/
@ -132,14 +132,14 @@ This file should also be located in your ``site-packages`` directory.
The location of the ``site-packages`` directory depends on the operating
system, and the location in which Python was installed. To find out your
system's ``site-packages`` location, execute the following:
.. code-block:: bash
python -c "from distutils.sysconfig import get_python_lib; print get_python_lib()"
(Note that this should be run from a shell prompt, not a Python interactive
prompt.)
.. _install-django-code:
Install the Django code
@ -190,7 +190,7 @@ Installing the development version
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. admonition:: Tracking Django development
If you decide to use the latest development version of Django,
you'll want to pay close attention to `the development timeline`_,
and you'll want to keep an eye on `the list of
@ -219,7 +219,7 @@ latest bug fixes and improvements, follow these instructions:
3. Next, make sure that the Python interpreter can load Django's code. There
are various ways of accomplishing this. One of the most convenient, on
Linux, Mac OSX or other Unix-like systems, is to use a symbolic link:
.. code-block:: bash
ln -s `pwd`/django-trunk/django SITE-PACKAGES-DIR/django
@ -248,7 +248,7 @@ latest bug fixes and improvements, follow these instructions:
4. On Unix-like systems, create a symbolic link to the file
``django-trunk/django/bin/django-admin.py`` in a directory on your system
path, such as ``/usr/local/bin``. For example:
.. code-block:: bash
ln -s `pwd`/django-trunk/django/bin/django-admin.py /usr/local/bin