Backwards-incompatible changes

As Django is still in pre-release mode, we haven't yet committed to maintaining backwards compatibility in any APIs. Although we're keeping such changes to a minimum, Django developers should be acutely aware of these changes.

Of course, once we reach our first official release, we'll be strongly committed to backward compatibility.

This page lists all backwards-incompatible changes to Django so far.

Moved mod_python handler

As of [169], using django.core.handler as a mod_python handler is deprecated. Use django.core.handlers.modpython instead. We will be removing django.core.handler for Django's first release.

Changed ordering syntax

As of [292], syntax used for order_by (in the database API) and ordering (in models) has changed.

Example of old ordering syntax: order_by=[('foo', 'ASC'), ('bar', 'DESC')]

Example of new ordering syntax: order_by=['foo', '-bar']

The old syntax is deprecated, and we'll stop supporting it for Django's first release.

Refactored meta.py

As of [378], django/core/meta.py has been converted to a package, django/core/meta/. If you're using a version of Django from before [378], make sure to delete django/core/meta.pyc and django/core/meta.pyo, if they exist. The existence of those files doesn't pose any known problems, but it's best to clean things up.

Changed edit_inline and edit_inline_type behavior

As of [440], using edit_inline_type in your models is deprecated, in favor of a less-redundant approach that uses edit_inline itself.

Example of old syntax: edit_inline=True, edit_inline_type=meta.TABULAR

Example of new syntax: edit_inline=meta.TABULAR

We'll stop supporting the old syntax for Django's first release.

Changed admin log to store primary keys as TEXT fields, not INTEGER fields

As of [469], the object_id field in django.models.auth.LogEntry is a TextField instead of an IntegerField. We made this change to accomodate non-integer primary keys.

If you're using a Django database installation from before [469] and you want to use non-integer primary keys on an object you edit in the admin site, you'll need to do an ALTER TABLE in your database.

In PostgreSQL:

BEGIN;
ALTER TABLE auth_admin_log RENAME object_id TO object_id_old;
ALTER TABLE auth_admin_log ADD COLUMN object_id TEXT;
UPDATE auth_admin_log SET object_id = object_id_old;
ALTER TABLE auth_admin_log DROP COLUMN object_id_old;
COMMIT;

In MySQL:

ALTER TABLE auth_admin_log MODIFY object_id TEXT;

Added support for anonymous sessions

As of [518], Django has support for anonymous sessions. If you're using a Django database installation from before [518] and you want to use the Django admin, anonymous sessions or auth-based sessions, you'll need to make a few updates to your database and settings files.

Change your settings files

Add "django.middleware.sessions.SessionMiddleware" to the MIDDLEWARE_CLASSES tuple in your admin settings file. Make sure it appears before "django.middleware.admin.AdminUserRequired". (The middleware classes are applied in order, and the admin middleware requires that the session middleware come first.)

If you want session support any other (i.e., non-admin) Django installation, change the MIDDLEWARE_CLASSES setting accordingly. The order (i.e., whether it comes before or after the other installed middleware classes) doesn't matter.

Create the core_sessions database table

In PostgreSQL, use this:

CREATE TABLE core_sessions (
    session_key varchar(40) NOT NULL PRIMARY KEY,
    session_data text NOT NULL,
    expire_date timestamp with time zone NOT NULL
);
INSERT INTO content_types (name, package, python_module_name) VALUES ('session', 'core', 'sessions');

In MySQL and SQLite, use this:

CREATE TABLE core_sessions (
    session_key varchar(40) NOT NULL PRIMARY KEY,
    session_data text NOT NULL,
    expire_date datetime NOT NULL
);
INSERT INTO content_types (name, package, python_module_name) VALUES ('session', 'core', 'sessions');

Remove old, unneeded things

Execute this SQL in your database:

DROP TABLE auth_sessions;
DELETE FROM content_types WHERE package = 'auth' AND python_module_name = 'sessions';

Edit your settings file(s) to remove AUTH_SESSION_COOKIE and REGISTRATION_COOKIE_DOMAIN, if they exist.

Changed model syntax

As of [549], Django's model syntax has changed. If you're using models that use old (pre-[549]) syntax, you'll need to convert them according to the instructions on ModelSyntaxChangeInstructions.

Moved template loader module

As of [867], django.core.template_loader is deprecated. Use django.core.template.loader instead.

Refactored the admin app not to require its own settings file

As of an upcoming changeset, the admin will have been refactored, to make things simpler and tighter -- both conceptually and in code layout.

What changed

• The admin no longer requires its own settings file. The "main" site and admin site can run on the same Django installation.
• All the admin code moved to django/contrib/admin.
• The admin requires "django.contrib.admin" in INSTALLED_APPS, and it requires the app_directories ​template loader.
• The admin database table isn't installed unless you explicitly have the admin installed (django-admin.py install admin).
• Renamed the admin log database table to give it a "django" prefix.

How to update your code

If you're using a Django installation from before this changeset, do the following to restore your admin site:

• Execute this SQL command: ALTER TABLE auth_admin_log RENAME TO django_admin_log;
• Edit your Django settings file (probably called settings/main.py) to make the following changes:
  • Add "django.contrib.admin" to INSTALLED_APPS. Order doesn't matter; it can be the first, last, whatever.
  • Remove "django.middleware.admin.AdminUserRequired" from MIDDLEWARE_CLASSES, if it's in there.
  • Add "django.middleware.sessions.SessionMiddleware" to MIDDLEWARE_CLASSES, if it's not already in there.
  • If you've created any custom admin templates, add the appropriate line from the admin TEMPLATE_DIRS setting to your "main" TEMPLATE_DIRS.
  • If you've created any custom admin templates, note that the template inheritance structure has changed. All admin templates are now within an admin subdirectory of the template directory. The following admin templates are directly affected by this change:
    • 400 --> admin/404
    • 500 --> admin/500
    • base --> admin/base
    • base_site --> admin/base_site
    • admin_object_history --> admin/object_history
    • delete_confirmation_generic --> admin/delete_confirmation
    • index --> admin/index
    • login --> admin/login
    • template_validator --> admin/template_validator
  • Add "django.core.template.loaders.app_directories.load_template_source" to TEMPLATE_LOADERS, after "django.core.template.loaders.filesystem.load_template_source". If you don't have the TEMPLATE_LOADERS setting, set it to this:

    TEMPLATE_LOADERS = (
        'django.core.template.loaders.filesystem.load_template_source',
        'django.core.template.loaders.app_directories.load_template_source',
    )
    

• Remove your admin settings file (probably called settings/admin.py) and admin URLconf (probably called settings/urls/admin.py).
• Delete django/templatetags/*.pyc and django/templatetags/*.pyo, just to be safe.
• Edit your main URLconf (probably called settings/urls/main.py) and add this line:

(r'^admin/', include('django.contrib.admin.urls.admin')),

Change that "admin" to whatever URL you were using for the admin site.

The following steps are optional but will tighten your code up. All assume your project is called myproject.

• Move myproject/settings/urls/main.py to myproject/urls.py.
• Delete myproject/settings/urls/admin.py (unless you had custom things in it, of course).
• Move myproject/settings/main.py to myproject/settings.py.
• Edit myproject/settings.py to change ROOT_URLCONF}} from {{{"myproject.settings.urls.main" to "myproject.urls".