What Are the Key Steps for Migration From Django Version 1.6 To 1.9?
Upgrading a web application’s framework is often a pivotal moment in its lifecycle, offering opportunities for improved performance, enhanced features, and better security. For developers working with Django, one of the most significant leaps was the transition from version 1.6 to 1.9. This migration not only introduced a host of new capabilities but also required careful planning to navigate changes in the framework’s architecture and best practices.
The journey from Django 1.6 to 1.9 represents more than just a version bump—it reflects the evolution of Django’s core philosophy and tooling. As the framework matured, so did its approach to database migrations, template handling, and middleware configuration, among other areas. Understanding these shifts is crucial for developers aiming to maintain stability while leveraging the advancements that Django 1.9 brings to the table.
In this article, we will explore the essential considerations and strategies for a smooth migration from Django 1.6 to 1.9. Whether you’re maintaining legacy projects or preparing for future development, gaining a clear overview of what this upgrade entails will help you make informed decisions and set the stage for success.
Changes in Middleware and Settings
One of the key changes when migrating from Django 1.6 to 1.9 involves the middleware architecture. Django 1.7 introduced a new-style middleware system that was fully adopted by Django 1.9, replacing the old-style middleware used in 1.6. This change affects how middleware classes are defined and registered in your project.
In Django 1.6, middleware classes were listed in the `MIDDLEWARE_CLASSES` setting, and each middleware needed to implement specific methods like `process_request`, `process_response`, and others. From Django 1.10 onward (but relevant to 1.9 since the new middleware was introduced earlier), middleware is defined in the `MIDDLEWARE` setting, and middleware classes follow a simpler interface based on a callable that takes `get_response` as an argument.
When upgrading, you should:
- Replace `MIDDLEWARE_CLASSES` with `MIDDLEWARE` in your settings.
- Update any custom middleware to conform to the new middleware API.
- Remove deprecated middleware classes or replace them with their supported equivalents.
Additionally, certain settings have been renamed or deprecated between these versions. For example, the `TEMPLATE_*` settings introduced in Django 1.8 replace the old `TEMPLATE_DIRS`, `TEMPLATE_CONTEXT_PROCESSORS`, and related settings from Django 1.6.
Key settings changes include:
| Old Setting (Django 1.6) | New Setting (Django 1.9) | Notes |
|---|---|---|
| MIDDLEWARE_CLASSES | MIDDLEWARE | Switch to new-style middleware API |
| TEMPLATE_DIRS, TEMPLATE_CONTEXT_PROCESSORS, etc. | TEMPLATES (a list of dictionaries) | Use the new TEMPLATES setting introduced in Django 1.8 for templates configuration |
| SESSION_COOKIE_NAME | SESSION_COOKIE_NAME | No change, but review session-related settings for deprecations |
Migrating templates requires converting the old settings into the new `TEMPLATES` configuration. This involves specifying the backend engine (typically `’django.template.backends.django.DjangoTemplates’`), directories, app directories, and context processors in a single structured setting.
Database Migrations and App Loading
Django 1.7 introduced the built-in migrations framework, replacing South, which was the de facto migrations tool in Django 1.6. By the time of Django 1.9, this migrations framework is fully integrated and expected to be used exclusively.
If your project still uses South, the migration process will involve:
- Removing South from your dependencies and codebase.
- Creating initial migrations for all apps using `python manage.py makemigrations`.
- Applying migrations using `python manage.py migrate`.
- Carefully handling database schema changes to avoid data loss.
The app loading mechanism also changed starting with Django 1.7, moving to an AppConfig-based registry. This means:
- Each app should have an `apps.py` file defining an `AppConfig` subclass.
- `INSTALLED_APPS` should list the app labels or full app config paths.
- Signals and app initialization code should be moved to AppConfig’s `ready()` method to ensure proper loading order.
Failure to adapt to the new app loading system can result in issues like models not being registered or signals not firing.
Template System Updates
The template system underwent significant restructuring between Django 1.6 and 1.9. The most notable change is the of the new `TEMPLATES` setting, which consolidates template backend configuration into a single setting.
Key points to consider:
- The new `TEMPLATES` setting is a list of template engine configurations. Each configuration is a dictionary specifying backend, directories, options, and context processors.
- This design supports multiple template backends in a project, such as Django templates and Jinja2.
- The `django.template.context_processors` module replaces the old `TEMPLATE_CONTEXT_PROCESSORS` tuple and is specified inside the `OPTIONS` dictionary under `context_processors`.
- Template loaders are also specified within the `OPTIONS` dictionary, replacing the old `TEMPLATE_LOADERS`.
A typical `TEMPLATES` setting example for Django 1.9:
“`python
TEMPLATES = [
{
‘BACKEND’: ‘django.template.backends.django.DjangoTemplates’,
‘DIRS’: [os.path.join(BASE_DIR, ‘templates’)],
‘APP_DIRS’: True,
‘OPTIONS’: {
‘context_processors’: [
‘django.template.context_processors.debug’,
‘django.template.context_processors.request’,
‘django.contrib.auth.context_processors.auth’,
‘django.contrib.messages.context_processors.messages’,
],
‘loaders’: [ … ], Optional explicit loaders
},
},
]
“`
When migrating, convert your old template settings accordingly, making sure to remove deprecated settings and confirm that your templates continue to render as expected.
Handling Deprecations and Removed Features
Django 1.9 deprecates or removes several features present in 1.6. It is critical to audit your codebase for usage of these and refactor where necessary.
Some commonly impacted areas include:
- The removal of `django.db.models.permalink` decorator. Use `reverse()` inside views instead.
- Changes to URL dispatcher syntax: the `patterns()` function is no longer necessary and is removed. Use plain lists of `url()` or `path()` objects.
- The `django.utils.importlib` module has been removed; use Python’s built-in `importlib`.
- The `url()` function in `django.conf.urls` now requires regular expressions without the use of
Key Changes in Django’s Migration System Between Versions 1.6 and 1.9
Django 1.7 introduced a fundamental shift in how database schema migrations are handled, replacing the external South migration tool with a built-in migrations framework. This migration system was further enhanced and stabilized by Django 1.9. Understanding these changes is critical to a smooth upgrade process.
- Native Migration Framework: Django 1.7+ includes a native migration system that tracks changes to models and generates migration files automatically.
- Migration Files Location: Migration files reside in the
migrationsdirectory inside each app, replacing South’smigrationsfolder structure. - Migration Commands: The management commands
makemigrationsandmigratereplace South’sschemamigrationandmigrate. - State vs. Database Schema: Django’s migration system maintains a model state representation separately from the database schema to better handle complex migrations.
- Dependency Management: Migration dependencies allow for more granular control over the order of migration application, including cross-app dependencies.
| Aspect | Django 1.6 (South) | Django 1.9 (Built-in Migrations) |
|---|---|---|
| Migration Management | South external tool | Native Django migrations framework |
| Migration Files | migrations directory created by South |
migrations directory auto-generated by Django |
| Commands | schemamigration, migrate |
makemigrations, migrate |
| Migration Dependencies | Limited, app-specific | Explicit, cross-app dependencies supported |
| Database State Tracking | South tracked applied migrations in south_migrationhistory |
Django tracks applied migrations in django_migrations table |
Steps to Convert South Migrations to Django’s Built-in Migration System
To upgrade your project from Django 1.6 (with South) to Django 1.9, you must carefully migrate existing schema migration history to Django’s new system to avoid data loss or migration conflicts.
- Remove South Dependencies:
Uninstall South and remove anysouthreferences inINSTALLED_APPSand project code. - Freeze Current Database State:
Ensure the current database schema matches the last applied South migration. Apply any outstanding South migrations before proceeding. - Create Initial Django Migrations:
Runpython manage.py makemigrations --empty yourappnameto create an initial empty migration for each app. - Fake Initial Migrations:
Apply the initial migrations with the--fakeflag to mark them as applied without modifying the database:
python manage.py migrate --fake - Generate Subsequent Migrations Normally:
Make further model changes and generate migrations usingmakemigrationsas usual.
It is essential to verify that the django_migrations table is populated correctly and that the migration history reflects the current database schema state.
Common Issues and Solutions During Migration Upgrade
Migrating from Django 1.6 to 1.9 can encounter several challenges. Understanding common pitfalls helps anticipate and resolve problems efficiently.
- Conflicting Migration Histories:
If both South and Django migrations coexist, conflicts arise. Remove South completely and fake initial migrations to sync histories. - Model Meta Changes:
Some Meta options changed behavior between versions (e.g.,unique_together,index_together). Review and adjust model Meta classes accordingly. - Custom Field Migration Support:
South-specific custom fields may require rewriting migration logic to be compatible with Django’s migration framework. - Third-party App Compatibility:
Ensure that all third-party apps are compatible with Django 1.9 migrations or have updated migration files. - Migration Dependencies and Order:
Misconfigured dependencies can cause migration failures. Explicitly define dependencies if necessary to maintain order across apps.
Adjustments to Settings and Codebase for Django 1.9 Compatibility
Beyond migrations, upgrading Django versions requires attention to settings and application code to align with new framework expectations and deprecations.