diff --git a/docs/release_notes_0.96.txt b/docs/release_notes_0.96.txt index 37f4034aa5..3d83da7554 100644 --- a/docs/release_notes_0.96.txt +++ b/docs/release_notes_0.96.txt @@ -17,6 +17,113 @@ next official release; then you'll be able to upgrade in one step instead of needing to make incremental changes to keep up with the development version of Django. +Backwards-incompatible changes +============================== + +The following changes may require you to update your code when you switch from +0.95 to 0.96: + +`MySQLdb` version requirement +----------------------------- + +Due to a bug in older versions of the `MySQLdb` Python module (which +Django uses to connect to MySQL databases), Django's MySQL backend now +requires version 1.2.1p2 or higher of `MySQLdb`, and will raise +exceptions if you attempt to use an older version. + +If you're currently unable to upgrade your copy of `MySQLdb` to meet +this requirement, a separate, backwards-compatible backend, called +"mysql_old", has been added to Django. To use this backend, change +the ``DATABASE_ENGINE`` setting in your Django settings file from +this:: + + DATABASE_ENGINE = "mysql" + +to this:: + + DATABASE_ENGINE = "mysql_old" + +However, we strongly encourage MySQL users to upgrade to a more recent +version of `MySQLdb` as soon as possible, The "mysql_old" backend is +provided only to ease this transition, and is considered deprecated; +aside from any necessary security fixes, it will not be actively +maintained, and it will be removed in a future release of Django. + +Also, note that some features, like the new ``DATABASE_OPTIONS`` +setting (see the `databases documentation`_ for details), are only +available on the "mysql" backend, and will not be made available for +"mysql_old". + +.. _databases: ../databases/ + +Database constraint names changed +--------------------------------- + +The format of the constraint names Django generates for foreign key +references have changed slightly. These names are generally only used +when it is not possible to put the reference directly on the affected +column, so they is not always visible. + +The effect of this change is that running ``manage.py reset`` and +similar commands against an existing database may generate SQL with +the new form of constraint name, while the database itself contains +constraints named in the old form; this will cause the database server +to raise an error message about modifying non-existent constraints. + +If you need to work around this, there are two methods available: + + 1. Redirect the output of ``manage.py`` to a file, and edit the + generated SQL to use the correct constraint names before + executing it. + + 2. Examine the output of ``manage.py sqlall`` to see the new-style + constraint names, and use that as a guide to rename existing + constraints in your database. + +Names changes in ``manage.py`` +------------------------------ + +A few of the options to ``manage.py`` have changed with the addition of fixture +support: + + * There are new ``dumpdata`` and ``loaddata`` commands which, as + you might expect, will dump and load data to/from the + database. These commands can operate against any of Django's + supported serialization formats. + + * The ``sqlinitialdata`` command has been renamed to ``sqlcustom`` to + emphasize that ``loaddata`` should be used for data (and ``sqlcustom`` for + other custom SQL -- views, stored procedures, etc.). + + * The vestigial ``install`` command has been removed. Use ``syncdb``. + +Backslash escaping changed +-------------------------- + +The Django database API now escapes backslashes given as query parameters. If +you have any database API code that matches backslashes, and it was working before +(despite the lack of escaping), you'll have to change your code to "unescape" the +slashes one level. + +For example, this used to work:: + + # Find text containing a single backslash + MyModel.objects.filter(text__contains='\\\\') + +The above is now incorrect, and should be rewritten as:: + + # Find text containing a single backslash + MyModel.objects.filter(text__contains='\\') + +Removed ENABLE_PSYCO setting +---------------------------- + +The ``ENABLE_PSYCO`` setting no longer exists. If your settings file includes +``ENABLE_PSYCO`` it will have no effect; to use Psyco_, we recommend +writing a middleware class to activate it. + +.. _psyco: http://psyco.sourceforge.net/ + What's new in 0.96? =================== @@ -130,113 +237,6 @@ A small change, but a very nice one: dedicated views for adding and updating users have been added to the admin interface, so you no longer need to worry about working with hashed passwords in the admin. -Backwards-incompatible changes -============================== - -The following changes may require you to update your code when you switch from -0.95 to 0.96: - -`MySQLdb` version requirement ------------------------------ - -Due to a bug in older versions of the `MySQLdb` Python module (which -Django uses to connect to MySQL databases), Django's MySQL backend now -requires version 1.2.1p2 or higher of `MySQLdb`, and will raise -exceptions if you attempt to use an older version. - -If you're currently unable to upgrade your copy of `MySQLdb` to meet -this requirement, a separate, backwards-compatible backend, called -"mysql_old", has been added to Django. To use this backend, change -the ``DATABASE_ENGINE`` setting in your Django settings file from -this:: - - DATABASE_ENGINE = "mysql" - -to this:: - - DATABASE_ENGINE = "mysql_old" - -However, we strongly encourage MySQL users to upgrade to a more recent -version of `MySQLdb` as soon as possible, The "mysql_old" backend is -provided only to ease this transition, and is considered deprecated; -aside from any necessary security fixes, it will not be actively -maintained, and it will be removed in a future release of Django. - -Also, note that some features, like the new ``DATABASE_OPTIONS`` -setting (see the `databases documentation`_ for details), are only -available on the "mysql" backend, and will not be made available for -"mysql_old". - -.. _databases: ../databases/ - -Database constraint names changed ---------------------------------- - -The format of the constraint names Django generates for foreign key -references have changed slightly. These names are generally only used -when it is not possible to put the reference directly on the affected -column, so they is not always visible. - -The effect of this change is that running ``manage.py reset`` and -similar commands against an existing database may generate SQL with -the new form of constraint name, while the database itself contains -constraints named in the old form; this will cause the database server -to raise an error message about modifying non-existent constraints. - -If you need to work around this, there are two methods available: - - 1. Redirect the output of ``manage.py`` to a file, and edit the - generated SQL to use the correct constraint names before - executing it. - - 2. Examine the output of ``manage.py sqlall`` to see the new-style - constraint names, and use that as a guide to rename existing - constraints in your database. - -Names changes in ``manage.py`` ------------------------------- - -A few of the options to ``manage.py`` have changed with the addition of fixture -support: - - * There are new ``dumpdata`` and ``loaddata`` commands which, as - you might expect, will dump and load data to/from the - database. These commands can operate against any of Django's - supported serialization formats. - - * The ``sqlinitialdata`` command has been renamed to ``sqlcustom`` to - emphasize that ``loaddata`` should be used for data (and ``sqlcustom`` for - other custom SQL -- views, stored procedures, etc.). - - * The vestigial ``install`` command has been removed. Use ``syncdb``. - -Backslash escaping changed --------------------------- - -The Django database API now escapes backslashes given as query parameters. If -you have any database API code that matches backslashes, and it was working before -(despite the lack of escaping), you'll have to change your code to "unescape" the -slashes one level. - -For example, this used to work:: - - # Find text containing a single backslash - MyModel.objects.filter(text__contains='\\\\') - -The above is now incorrect, and should be rewritten as:: - - # Find text containing a single backslash - MyModel.objects.filter(text__contains='\\') - -Removed ENABLE_PSYCO setting ----------------------------- - -The ``ENABLE_PSYCO`` setting no longer exists. If your settings file includes -``ENABLE_PSYCO`` it will have no effect; to use Psyco, we recommend -writing a middleware class to activate it. - -.. _psyco: http://psyco.sourceforge.net/ - Thanks ======