Author: jacob Date: 2009-03-31 21:37:04 -0500 (Tue, 31 Mar 2009) New Revision: 10312
Modified: django/branches/releases/1.0.X/ django/branches/releases/1.0.X/docs/ref/databases.txt django/branches/releases/1.0.X/docs/topics/install.txt Log: [1.0.X] Fixed #10031: updated SQLite database docs to more strongly indicate the problems with versions before 3.3.6. Thanks, ramiro. Backport of r10311 from trunk. Property changes on: django/branches/releases/1.0.X ___________________________________________________________________ Name: svnmerge-integrated - /django/trunk:1-9097,9099-9102,9104-9109,9111,9113-9144,9146-9151,9153-9156,9158-9159,9161-9187,9189-9247,9249-9262,9264-9277,9279-9298,9301-9302,9305-9331,9333-9343,9345,9347,9350-9352,9355-9396,9399-9462,9466-9469,9471-9488,9491-9526,9529,9533-9536,9539-9550,9556-9557,9559-9560,9562-9568,9570-9591,9595-9619,9621-9624,9626-9636,9638-9642,9644-9645,9647-9689,9691-9699,9703-9706,9709-9713,9716-9723,9725-9726,9730-9738,9740-9741,9750-9751,9757-9758,9761-9762,9767-9768,9770-9780,9782-9784,9789-9790,9793-9798,9801-9802,9806-9807,9809-9813,9821-9837,9842-9843,9847-9859,9861,9863-9875,9877-9881,9883-9887,9899-9903,9906-9909,9912,9914,9916-9917,9919-9920,9922-9927,9929,9931-9937,9939,9942-9943,9945-9950,9953-9954,9956-9962,9966-9977,9979-9984,9986-9988,9990,9992,9994,9996-9998,10003,10007,10009,10013,10015,10017,10022,10024,10031,10036-10037,10040,10049,10051,10054-10058,10071,10073-10074,10078,10104,10125,10136,10139,10143,10145-10147,10149-10152,10170,10175,10193,10195-10196,10198-10221,10223-10228,10230-10234,10236-10247,10250-10257,10259-10270,10273-10274,10276-10280,10282-10283,10303-10304,10309 + /django/trunk:1-9097,9099-9102,9104-9109,9111,9113-9144,9146-9151,9153-9156,9158-9159,9161-9187,9189-9247,9249-9262,9264-9277,9279-9298,9301-9302,9305-9331,9333-9343,9345,9347,9350-9352,9355-9396,9399-9462,9466-9469,9471-9488,9491-9526,9529,9533-9536,9539-9550,9556-9557,9559-9560,9562-9568,9570-9591,9595-9619,9621-9624,9626-9636,9638-9642,9644-9645,9647-9689,9691-9699,9703-9706,9709-9713,9716-9723,9725-9726,9730-9738,9740-9741,9750-9751,9757-9758,9761-9762,9767-9768,9770-9780,9782-9784,9789-9790,9793-9798,9801-9802,9806-9807,9809-9813,9821-9837,9842-9843,9847-9859,9861,9863-9875,9877-9881,9883-9887,9899-9903,9906-9909,9912,9914,9916-9917,9919-9920,9922-9927,9929,9931-9937,9939,9942-9943,9945-9950,9953-9954,9956-9962,9966-9977,9979-9984,9986-9988,9990,9992,9994,9996-9998,10003,10007,10009,10013,10015,10017,10022,10024,10031,10036-10037,10040,10049,10051,10054-10058,10071,10073-10074,10078,10104,10125,10136,10139,10143,10145-10147,10149-10152,10170,10175,10193,10195-10196,10198-10221,10223-10228,10230-10234,10236-10247,10250-10257,10259-10270,10273-10274,10276-10280,10282-10283,10303-10304,10309,10311 Modified: django/branches/releases/1.0.X/docs/ref/databases.txt =================================================================== --- django/branches/releases/1.0.X/docs/ref/databases.txt 2009-04-01 01:36:44 UTC (rev 10311) +++ django/branches/releases/1.0.X/docs/ref/databases.txt 2009-04-01 02:37:04 UTC (rev 10312) @@ -13,6 +13,33 @@ usage. Of course, it is not intended as a replacement for server-specific documentation or reference manuals. +.. _postgresql-notes: + +PostgreSQL notes +================ + +PostgreSQL 8.2 to 8.2.4 +----------------------- + +The implementation of the population statistics aggregates ``STDDEV_POP`` and +``VAR_POP`` that shipped with PostgreSQL 8.2 to 8.2.4 are `known to be +faulty`_. Users of these releases of PostgreSQL are advised to upgrade to +`Release 8.2.5`_ or later. Django will raise a ``NotImplementedError`` if you +attempt to use the ``StdDev(sample=False)`` or ``Variance(sample=False)`` +aggregate with a database backend that falls within the affected release range. + +.. _known to be faulty: http://archives.postgresql.org/pgsql-bugs/2007-07/msg00046.php +.. _Release 8.2.5: http://developer.postgresql.org/pgdocs/postgres/release-8-2-5.html + +Transaction handling +--------------------- + +:ref:`By default <topics-db-transactions>`, Django starts a transaction when a +database connection is first used and commits the result at the end of the +request/response handling. The PostgreSQL backends normally operate the same +as any other Django backend in this respect. + + .. _mysql-notes: MySQL notes @@ -163,7 +190,7 @@ Connecting to the database -------------------------- -Refer to the :ref:`settings documentation <ref-settings>`. +Refer to the :ref:`settings documentation <ref-settings>`. Connection settings are used in this order: @@ -183,7 +210,7 @@ DATABASE_ENGINE = "mysql" DATABASE_OPTIONS = { 'read_default_file': '/path/to/my.cnf', - } + } # my.cnf [client] @@ -221,9 +248,7 @@ creating your tables:: DATABASE_OPTIONS = { - # ... "init_command": "SET storage_engine=INNODB", - # ... } This sets the default storage engine upon connecting to the database. @@ -262,9 +287,9 @@ .. _sqlite-notes: -SQLite notes -============ - +SQLite notes +============ + SQLite_ provides an excellent development alternative for applications that are predominantly read-only or require a smaller installation footprint. As with all database servers, though, there are some differences that are @@ -285,38 +310,54 @@ .. _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. - -.. _contain a bug: http://www.sqlite.org/cvstrac/tktview?tn=1768 - -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. - -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. +Versions of SQLite 3.3.5 and older contains the following bugs: -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. + * 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``. + * A bug when handling `aggregation`_ together with DateFields and + DecimalFields. + +.. _handling: http://www.sqlite.org/cvstrac/tktview?tn=1768 +.. _aggregation: http://code.djangoproject.com/ticket/10031 + +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). + +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" (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 +package. However the Debian project has subsequently issued updated versions +of the SQLite package that correct these bugs. If you find you are getting +unexpected results under Debian, ensure you have updated your SQLite package +to 3.5.9-5 or later. + +The problem does not appear to exist with other versions of SQLite packaged +with other operating systems. + Version 3.6.2 -------------- @@ -328,6 +369,21 @@ 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 @@ -353,14 +409,14 @@ * CREATE SEQUENCE * CREATE PROCEDURE * CREATE TRIGGER - + To run Django's test suite, the user needs these *additional* privileges: * CREATE USER * DROP USER * CREATE TABLESPACE * DROP TABLESPACE - + Connecting to the database -------------------------- Modified: django/branches/releases/1.0.X/docs/topics/install.txt =================================================================== --- django/branches/releases/1.0.X/docs/topics/install.txt 2009-04-01 01:36:44 UTC (rev 10311) +++ django/branches/releases/1.0.X/docs/topics/install.txt 2009-04-01 02:37:04 UTC (rev 10312) @@ -80,7 +80,7 @@ * 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 @@ .. _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 @@ 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 @@ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. 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 @@ 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 @@ 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 --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "Django updates" group. To post to this group, send email to django-updates@googlegroups.com To unsubscribe from this group, send email to django-updates+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/django-updates?hl=en -~----------~----~----~----~------~----~------~--~---
