mirror of
https://github.com/django/django.git
synced 2024-12-25 02:26:12 +00:00
681 lines
29 KiB
Plaintext
681 lines
29 KiB
Plaintext
==========
|
|
Migrations
|
|
==========
|
|
|
|
.. module:: django.db.migrations
|
|
:synopsis: Schema migration support for Django models
|
|
|
|
.. versionadded:: 1.7
|
|
|
|
Migrations are Django's way of propagating changes you make to your models
|
|
(adding a field, deleting a model, etc.) into your database schema. They're
|
|
designed to be mostly automatic, but you'll need to know when to make
|
|
migrations, when to run them, and the common problems you might run into.
|
|
|
|
A Brief History
|
|
---------------
|
|
|
|
Prior to version 1.7, Django only supported adding new models to the
|
|
database; it was not possible to alter or remove existing models via the
|
|
``syncdb`` command (the predecessor to :djadmin:`migrate`).
|
|
|
|
Third-party tools, most notably `South <http://south.aeracode.org>`_,
|
|
provided support for these additional types of change, but it was considered
|
|
important enough that support was brought into core Django.
|
|
|
|
The Commands
|
|
------------
|
|
|
|
There are several commands which you will use to interact with migrations
|
|
and Django's handling of database schema:
|
|
|
|
* :djadmin:`migrate`, which is responsible for applying migrations, as well as
|
|
unapplying and listing their status.
|
|
|
|
* :djadmin:`makemigrations`, which is responsible for creating new migrations
|
|
based on the changes you have made to your models.
|
|
|
|
* :djadmin:`sqlmigrate`, which displays the SQL statements for a migration.
|
|
|
|
It's worth noting that migrations are created and run on a per-app basis.
|
|
In particular, it's possible to have apps that *do not use migrations* (these
|
|
are referred to as "unmigrated" apps) - these apps will instead mimic the
|
|
legacy behavior of just adding new models.
|
|
|
|
You should think of migrations as a version control system for your database
|
|
schema. ``makemigrations`` is responsible for packaging up your model changes
|
|
into individual migration files - analogous to commits - and ``migrate`` is
|
|
responsible for applying those to your database.
|
|
|
|
The migration files for each app live in a "migrations" directory inside
|
|
of that app, and are designed to be committed to, and distributed as part
|
|
of, its codebase. You should be making them once on your development machine
|
|
and then running the same migrations on your colleagues' machines, your
|
|
staging machines, and eventually your production machines.
|
|
|
|
.. note::
|
|
It is possible to override the name of the package which contains the
|
|
migrations on a per-app basis by modifying the :setting:`MIGRATION_MODULES`
|
|
setting.
|
|
|
|
Migrations will run the same way on the same dataset and produce consistent
|
|
results, meaning that what you see in development and staging is, under the
|
|
same circumstances, exactly what will happen in production.
|
|
|
|
Django will make migrations for any change to your models or fields - even
|
|
options that don't affect the database - as the only way it can reconstruct
|
|
a field correctly is to have all the changes in the history, and you might
|
|
need those options in some data migrations later on (for example, if you've
|
|
set custom validators).
|
|
|
|
Backend Support
|
|
---------------
|
|
|
|
Migrations are supported on all backends that Django ships with, as well
|
|
as any third-party backends if they have programmed in support for schema
|
|
alteration (done via the :doc:`SchemaEditor </ref/schema-editor>` class).
|
|
|
|
However, some databases are more capable than others when it comes to
|
|
schema migrations; some of the caveats are covered below.
|
|
|
|
PostgreSQL
|
|
~~~~~~~~~~
|
|
|
|
PostgreSQL is the most capable of all the databases here in terms of schema
|
|
support; the only caveat is that adding columns with default values will
|
|
cause a full rewrite of the table, for a time proportional to its size.
|
|
|
|
For this reason, it's recommended you always create new columns with
|
|
``null=True``, as this way they will be added immediately.
|
|
|
|
MySQL
|
|
~~~~~
|
|
|
|
MySQL lacks support for transactions around schema alteration operations,
|
|
meaning that if a migration fails to apply you will have to manually unpick
|
|
the changes in order to try again (it's impossible to roll back to an
|
|
earlier point).
|
|
|
|
In addition, MySQL will fully rewrite tables for almost every schema operation
|
|
and generally takes a time proportional to the number of rows in the table to
|
|
add or remove columns. On slower hardware this can be worse than a minute per
|
|
million rows - adding a few columns to a table with just a few million rows
|
|
could lock your site up for over ten minutes.
|
|
|
|
Finally, MySQL has reasonably small limits on name lengths for columns, tables
|
|
and indexes, as well as a limit on the combined size of all columns an index
|
|
covers. This means that indexes that are possible on other backends will
|
|
fail to be created under MySQL.
|
|
|
|
SQLite
|
|
~~~~~~
|
|
|
|
SQLite has very little built-in schema alteration support, and so Django
|
|
attempts to emulate it by:
|
|
|
|
* Creating a new table with the new schema
|
|
* Copying the data across
|
|
* Dropping the old table
|
|
* Renaming the new table to match the original name
|
|
|
|
This process generally works well, but it can be slow and occasionally
|
|
buggy. It is not recommended that you run and migrate SQLite in a
|
|
production environment unless you are very aware of the risks and
|
|
its limitations; the support Django ships with is designed to allow
|
|
developers to use SQLite on their local machines to develop less complex
|
|
Django projects without the need for a full database.
|
|
|
|
Workflow
|
|
--------
|
|
|
|
Working with migrations is simple. Make changes to your models - say, add
|
|
a field and remove a model - and then run :djadmin:`makemigrations`::
|
|
|
|
$ python manage.py makemigrations
|
|
Migrations for 'books':
|
|
0003_auto.py:
|
|
- Alter field author on book
|
|
|
|
Your models will be scanned and compared to the versions currently
|
|
contained in your migration files, and then a new set of migrations
|
|
will be written out. Make sure to read the output to see what
|
|
``makemigrations`` thinks you have changed - it's not perfect, and for
|
|
complex changes it might not be detecting what you expect.
|
|
|
|
Once you have your new migration files, you should apply them to your
|
|
database to make sure they work as expected::
|
|
|
|
$ python manage.py migrate
|
|
Operations to perform:
|
|
Synchronize unmigrated apps: sessions, admin, messages, auth, staticfiles, contenttypes
|
|
Apply all migrations: books
|
|
Synchronizing apps without migrations:
|
|
Creating tables...
|
|
Installing custom SQL...
|
|
Installing indexes...
|
|
Installed 0 object(s) from 0 fixture(s)
|
|
Running migrations:
|
|
Applying books.0003_auto... OK
|
|
|
|
The command runs in two stages; first, it synchronizes unmigrated apps
|
|
(performing the same functionality that ``syncdb`` used to provide), and
|
|
then it runs any migrations that have not yet been applied.
|
|
|
|
Once the migration is applied, commit the migration and the models change
|
|
to your version control system as a single commit - that way, when other
|
|
developers (or your production servers) check out the code, they'll
|
|
get both the changes to your models and the accompanying migration at the
|
|
same time.
|
|
|
|
Version control
|
|
~~~~~~~~~~~~~~~
|
|
|
|
Because migrations are stored in version control, you'll occasionally
|
|
come across situations where you and another developer have both committed
|
|
a migration to the same app at the same time, resulting in two migrations
|
|
with the same number.
|
|
|
|
Don't worry - the numbers are just there for developers' reference, Django
|
|
just cares that each migration has a different name. Migrations specify which
|
|
other migrations they depend on - including earlier migrations in the same
|
|
app - in the file, so it's possible to detect when there's two new migrations
|
|
for the same app that aren't ordered.
|
|
|
|
When this happens, Django will prompt you and give you some options. If it
|
|
thinks it's safe enough, it will offer to automatically linearize the two
|
|
migrations for you. If not, you'll have to go in and modify the migrations
|
|
yourself - don't worry, this isn't difficult, and is explained more in
|
|
:ref:`migration-files` below.
|
|
|
|
Dependencies
|
|
------------
|
|
|
|
While migrations are per-app, the tables and relationships implied by
|
|
your models are too complex to be created for just one app at a time. When
|
|
you make a migration that requires something else to run - for example,
|
|
you add a ``ForeignKey`` in your ``books`` app to your ``authors`` app - the
|
|
resulting migration will contain a dependency on a migration in ``authors``.
|
|
|
|
This means that when you run the migrations, the ``authors`` migration runs
|
|
first and creates the table the ``ForeignKey`` references, and then the migration
|
|
that makes the ``ForeignKey`` column runs afterwards and creates the constraint.
|
|
If this didn't happen, the migration would try to create the ``ForeignKey``
|
|
column without the table it's referencing existing and your database would
|
|
throw an error.
|
|
|
|
This dependency behavior affects most migration operations where you
|
|
restrict to a single app. Restricting to a single app (either in
|
|
``makemigrations`` or ``migrate``) is a best-efforts promise, and not
|
|
a guarantee; any other apps that need to be used to get dependencies correct
|
|
will be.
|
|
|
|
.. _unmigrated-dependencies:
|
|
|
|
Be aware, however, that unmigrated apps cannot depend on migrated apps, by the
|
|
very nature of not having migrations. This means that it is not generally
|
|
possible to have an unmigrated app have a ForeignKey or ManyToManyField to
|
|
a migrated app; some cases may work, but it will eventually fail.
|
|
|
|
This is particularly apparent if you use swappable models (e.g.
|
|
``AUTH_USER_MODEL``), as every app that uses swappable models will need
|
|
to have migrations if you're unlucky. As time goes on, more and more
|
|
third-party apps will get migrations, but in the meantime you can either
|
|
give them migrations yourself (using :setting:`MIGRATION_MODULES` to
|
|
store those modules outside of the app's own module if you wish), or
|
|
keep the app with your user model unmigrated.
|
|
|
|
.. _migration-files:
|
|
|
|
Migration files
|
|
---------------
|
|
|
|
Migrations are stored as an on-disk format, referred to here as
|
|
"migration files". These files are actually just normal Python files with
|
|
an agreed-upon object layout, written in a declarative style.
|
|
|
|
A basic migration file looks like this::
|
|
|
|
from django.db import migrations, models
|
|
|
|
class Migration(migrations.Migration):
|
|
|
|
dependencies = [("migrations", "0001_initial")]
|
|
|
|
operations = [
|
|
migrations.DeleteModel("Tribble"),
|
|
migrations.AddField("Author", "rating", models.IntegerField(default=0)),
|
|
]
|
|
|
|
What Django looks for when it loads a migration file (as a Python module) is
|
|
a subclass of ``django.db.migrations.Migration`` called ``Migration``. It then
|
|
inspects this object for four attributes, only two of which are used
|
|
most of the time:
|
|
|
|
* ``dependencies``, a list of migrations this one depends on.
|
|
* ``operations``, a list of ``Operation`` classes that define what this
|
|
migration does.
|
|
|
|
The operations are the key; they are a set of declarative instructions which
|
|
tell Django what schema changes need to be made. Django scans them and
|
|
builds an in-memory representation of all of the schema changes to all apps,
|
|
and uses this to generate the SQL which makes the schema changes.
|
|
|
|
That in-memory structure is also used to work out what the differences are
|
|
between your models and the current state of your migrations; Django runs
|
|
through all the changes, in order, on an in-memory set of models to come
|
|
up with the state of your models last time you ran ``makemigrations``. It
|
|
then uses these models to compare against the ones in your ``models.py`` files
|
|
to work out what you have changed.
|
|
|
|
You should rarely, if ever, need to edit migration files by hand, but
|
|
it's entirely possible to write them manually if you need to. Some of the
|
|
more complex operations are not autodetectable and are only available via
|
|
a hand-written migration, so don't be scared about editing them if you have to.
|
|
|
|
Custom fields
|
|
~~~~~~~~~~~~~
|
|
|
|
You can't modify the number of positional arguments in an already migrated
|
|
custom field without raising a ``TypeError``. The old migration will call the
|
|
modified ``__init__`` method with the old signature. So if you need a new
|
|
argument, please create a keyword argument and add something like
|
|
``assert kwargs.get('argument_name') is not None`` in the constructor.
|
|
|
|
Adding migrations to apps
|
|
-------------------------
|
|
|
|
Adding migrations to new apps is straightforward - they come preconfigured to
|
|
accept migrations, and so just run :djadmin:`makemigrations` once you've made
|
|
some changes.
|
|
|
|
If your app already has models and database tables, and doesn't have migrations
|
|
yet (for example, you created it against a previous Django version), you'll
|
|
need to convert it to use migrations; this is a simple process::
|
|
|
|
$ python manage.py makemigrations your_app_label
|
|
|
|
This will make a new initial migration for your app. Now, when you run
|
|
:djadmin:`migrate`, Django will detect that you have an initial migration
|
|
*and* that the tables it wants to create already exist, and will mark the
|
|
migration as already applied.
|
|
|
|
Note that this only works given two things:
|
|
|
|
* You have not changed your models since you made their tables. For migrations
|
|
to work, you must make the initial migration *first* and then make changes,
|
|
as Django compares changes against migration files, not the database.
|
|
|
|
* You have not manually edited your database - Django won't be able to detect
|
|
that your database doesn't match your models, you'll just get errors when
|
|
migrations try to modify those tables.
|
|
|
|
.. versionadded:: 1.8
|
|
|
|
If you want to give the migration(s) a meaningful name instead of a generated one,
|
|
you can use the :djadminopt:`--name` option::
|
|
|
|
$ python manage.py makemigrations --name changed_my_model your_app_label
|
|
|
|
.. _historical-models:
|
|
|
|
Historical models
|
|
-----------------
|
|
|
|
When you run migrations, Django is working from historical versions of
|
|
your models stored in the migration files. If you write Python code
|
|
using the :class:`~django.db.migrations.operations.RunPython` operation, or if
|
|
you have ``allow_migrate`` methods on your database routers, you will be
|
|
exposed to these versions of your models.
|
|
|
|
Because it's impossible to serialize arbitrary Python code, these historical
|
|
models will not have any custom methods or managers that you have defined.
|
|
They will, however, have the same fields, relationships and ``Meta`` options
|
|
(also versioned, so they may be different from your current ones).
|
|
|
|
.. warning::
|
|
|
|
This means that you will NOT have custom ``save()`` methods called on objects
|
|
when you access them in migrations, and you will NOT have any custom
|
|
constructors or instance methods. Plan appropriately!
|
|
|
|
References to functions in field options such as ``upload_to`` and
|
|
``limit_choices_to`` are serialized in migrations, so the functions will need
|
|
to be kept around for as long as there is a migration referencing them. Any
|
|
:doc:`custom model fields </howto/custom-model-fields>` will also need to be
|
|
kept, since these are imported directly by migrations.
|
|
|
|
In addition, the base classes of the model are just stored as pointers,
|
|
so you must always keep base classes around for as long as there is a migration
|
|
that contains a reference to them. On the plus side, methods and managers
|
|
from these base classes inherit normally, so if you absolutely need access
|
|
to these you can opt to move them into a superclass.
|
|
|
|
.. _data-migrations:
|
|
|
|
Data Migrations
|
|
---------------
|
|
|
|
As well as changing the database schema, you can also use migrations to change
|
|
the data in the database itself, in conjunction with the schema if you want.
|
|
|
|
Migrations that alter data are usually called "data migrations"; they're best
|
|
written as separate migrations, sitting alongside your schema migrations.
|
|
|
|
Django can't automatically generate data migrations for you, as it does with
|
|
schema migrations, but it's not very hard to write them. Migration files in
|
|
Django are made up of :doc:`Operations </ref/migration-operations>`, and
|
|
the main operation you use for data migrations is
|
|
:class:`~django.db.migrations.operations.RunPython`.
|
|
|
|
To start, make an empty migration file you can work from (Django will put
|
|
the file in the right place, suggest a name, and add dependencies for you)::
|
|
|
|
python manage.py makemigrations --empty yourappname
|
|
|
|
Then, open up the file; it should look something like this::
|
|
|
|
# -*- coding: utf-8 -*-
|
|
from django.db import models, migrations
|
|
|
|
class Migration(migrations.Migration):
|
|
|
|
dependencies = [
|
|
('yourappname', '0001_initial'),
|
|
]
|
|
|
|
operations = [
|
|
]
|
|
|
|
Now, all you need to do is create a new function and have
|
|
:class:`~django.db.migrations.operations.RunPython` use it.
|
|
:class:`~django.db.migrations.operations.RunPython` expects a callable as its argument
|
|
which takes two arguments - the first is an :doc:`app registry
|
|
</ref/applications/>` that has the historical versions of all your models
|
|
loaded into it to match where in your history the migration sits, and the
|
|
second is a :doc:`SchemaEditor </ref/schema-editor>`, which you can use to
|
|
manually effect database schema changes (but beware, doing this can confuse
|
|
the migration autodetector!)
|
|
|
|
Let's write a simple migration that populates our new ``name`` field with the
|
|
combined values of ``first_name`` and ``last_name`` (we've come to our senses
|
|
and realized that not everyone has first and last names). All we
|
|
need to do is use the historical model and iterate over the rows::
|
|
|
|
# -*- coding: utf-8 -*-
|
|
from django.db import models, migrations
|
|
|
|
def combine_names(apps, schema_editor):
|
|
# We can't import the Person model directly as it may be a newer
|
|
# version than this migration expects. We use the historical version.
|
|
Person = apps.get_model("yourappname", "Person")
|
|
for person in Person.objects.all():
|
|
person.name = "%s %s" % (person.first_name, person.last_name)
|
|
person.save()
|
|
|
|
class Migration(migrations.Migration):
|
|
|
|
dependencies = [
|
|
('yourappname', '0001_initial'),
|
|
]
|
|
|
|
operations = [
|
|
migrations.RunPython(combine_names),
|
|
]
|
|
|
|
Once that's done, we can just run ``python manage.py migrate`` as normal and
|
|
the data migration will run in place alongside other migrations.
|
|
|
|
You can pass a second callable to
|
|
:class:`~django.db.migrations.operations.RunPython` to run whatever logic you
|
|
want executed when migrating backwards. If this callable is omitted, migrating
|
|
backwards will raise an exception.
|
|
|
|
If you're interested in the more advanced migration operations, or want
|
|
to be able to write your own, see the :doc:`migration operations reference
|
|
</ref/migration-operations>`.
|
|
|
|
.. _migration-squashing:
|
|
|
|
Squashing migrations
|
|
--------------------
|
|
|
|
You are encouraged to make migrations freely and not worry about how many you
|
|
have; the migration code is optimized to deal with hundreds at a time without
|
|
much slowdown. However, eventually you will want to move back from having
|
|
several hundred migrations to just a few, and that's where squashing comes in.
|
|
|
|
Squashing is the act of reducing an existing set of many migrations down to
|
|
one (or sometimes a few) migrations which still represent the same changes.
|
|
|
|
Django does this by taking all of your existing migrations, extracting their
|
|
``Operation``\s and putting them all in sequence, and then running an optimizer
|
|
over them to try and reduce the length of the list - for example, it knows
|
|
that :class:`~django.db.migrations.operations.CreateModel` and
|
|
:class:`~django.db.migrations.operations.DeleteModel` cancel each other out,
|
|
and it knows that :class:`~django.db.migrations.operations.AddField` can be
|
|
rolled into :class:`~django.db.migrations.operations.CreateModel`.
|
|
|
|
Once the operation sequence has been reduced as much as possible - the amount
|
|
possible depends on how closely intertwined your models are and if you have
|
|
any :class:`~django.db.migrations.operations.RunSQL`
|
|
or :class:`~django.db.migrations.operations.RunPython` operations (which can't
|
|
be optimized through) - Django will then write it back out into a new set of
|
|
initial migration files.
|
|
|
|
These files are marked to say they replace the previously-squashed migrations,
|
|
so they can coexist with the old migration files, and Django will intelligently
|
|
switch between them depending where you are in the history. If you're still
|
|
part-way through the set of migrations that you squashed, it will keep using
|
|
them until it hits the end and then switch to the squashed history, while new
|
|
installs will just use the new squashed migration and skip all the old ones.
|
|
|
|
This enables you to squash and not mess up systems currently in production
|
|
that aren't fully up-to-date yet. The recommended process is to squash, keeping
|
|
the old files, commit and release, wait until all systems are upgraded with
|
|
the new release (or if you're a third-party project, just ensure your users
|
|
upgrade releases in order without skipping any), and then remove the old files,
|
|
commit and do a second release.
|
|
|
|
The command that backs all this is :djadmin:`squashmigrations` - just pass
|
|
it the app label and migration name you want to squash up to, and it'll get to
|
|
work::
|
|
|
|
$ ./manage.py squashmigrations myapp 0004
|
|
Will squash the following migrations:
|
|
- 0001_initial
|
|
- 0002_some_change
|
|
- 0003_another_change
|
|
- 0004_undo_something
|
|
Do you wish to proceed? [yN] y
|
|
Optimizing...
|
|
Optimized from 12 operations to 7 operations.
|
|
Created new squashed migration /home/andrew/Programs/DjangoTest/test/migrations/0001_squashed_0004_undo_somthing.py
|
|
You should commit this migration but leave the old ones in place;
|
|
the new migration will be used for new installs. Once you are sure
|
|
all instances of the codebase have applied the migrations you squashed,
|
|
you can delete them.
|
|
|
|
Note that model interdependencies in Django can get very complex, and squashing
|
|
may result in migrations that do not run; either mis-optimized (in which case
|
|
you can try again with ``--no-optimize``, though you should also report an issue),
|
|
or with a ``CircularDependencyError``, in which case you can manually resolve it.
|
|
|
|
To manually resolve a ``CircularDependencyError``, break out one of
|
|
the ForeignKeys in the circular dependency loop into a separate
|
|
migration, and move the dependency on the other app with it. If you're unsure,
|
|
see how makemigrations deals with the problem when asked to create brand
|
|
new migrations from your models. In a future release of Django, squashmigrations
|
|
will be updated to attempt to resolve these errors itself.
|
|
|
|
Once you've squashed your migration, you should then commit it alongside the
|
|
migrations it replaces and distribute this change to all running instances
|
|
of your application, making sure that they run ``migrate`` to store the change
|
|
in their database.
|
|
|
|
After this has been done, you must then transition the squashed migration to
|
|
a normal initial migration, by:
|
|
|
|
- Deleting all the migration files it replaces
|
|
- Removing the ``replaces`` argument in the ``Migration`` class of the
|
|
squashed migration (this is how Django tells that it is a squashed migration)
|
|
|
|
.. note::
|
|
Once you've squashed a migration, you should not then re-squash that squashed
|
|
migration until you have fully transitioned it to a normal migration.
|
|
|
|
|
|
.. _migration-serializing:
|
|
|
|
Serializing values
|
|
------------------
|
|
|
|
Migrations are just Python files containing the old definitions of your models
|
|
- thus, to write them, Django must take the current state of your models and
|
|
serialize them out into a file.
|
|
|
|
While Django can serialize most things, there are some things that we just
|
|
can't serialize out into a valid Python representation - there's no Python
|
|
standard for how a value can be turned back into code (``repr()`` only works
|
|
for basic values, and doesn't specify import paths).
|
|
|
|
Django can serialize the following:
|
|
|
|
- ``int``, ``long``, ``float``, ``bool``, ``str``, ``unicode``, ``bytes``, ``None``
|
|
- ``list``, ``set``, ``tuple``, ``dict``
|
|
- ``datetime.date``, ``datetime.time``, and ``datetime.datetime`` instances
|
|
(include those that are timezone-aware)
|
|
- ``decimal.Decimal`` instances
|
|
- Any Django field
|
|
- Any function or method reference (e.g. ``datetime.datetime.today``) (must be in module's top-level scope)
|
|
- Any class reference (must be in module's top-level scope)
|
|
- Anything with a custom ``deconstruct()`` method (:ref:`see below <custom-deconstruct-method>`)
|
|
|
|
.. versionchanged:: 1.7.1
|
|
|
|
Support for serializing timezone-aware datetimes was added.
|
|
|
|
Django can serialize the following on Python 3 only:
|
|
|
|
- Unbound methods used from within the class body (see below)
|
|
|
|
Django cannot serialize:
|
|
|
|
- Nested classes
|
|
- Arbitrary class instances (e.g. ``MyClass(4.3, 5.7)``)
|
|
- Lambdas
|
|
|
|
Due to the fact ``__qualname__`` was only introduced in Python 3, Django can only
|
|
serialize the following pattern (an unbound method used within the class body)
|
|
on Python 3, and will fail to serialize a reference to it on Python 2::
|
|
|
|
class MyModel(models.Model):
|
|
|
|
def upload_to(self):
|
|
return "something dynamic"
|
|
|
|
my_file = models.FileField(upload_to=upload_to)
|
|
|
|
If you are using Python 2, we recommend you move your methods for upload_to
|
|
and similar arguments that accept callables (e.g. ``default``) to live in
|
|
the main module body, rather than the class body.
|
|
|
|
.. _custom-deconstruct-method:
|
|
|
|
Adding a deconstruct() method
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
You can let Django serialize your own custom class instances by giving the class
|
|
a ``deconstruct()`` method. It takes no arguments, and should return a tuple
|
|
of three things ``(path, args, kwargs)``:
|
|
|
|
* ``path`` should be the Python path to the class, with the class name included
|
|
as the last part (for example, ``myapp.custom_things.MyClass``). If your
|
|
class is not available at the top level of a module it is not serializable.
|
|
|
|
* ``args`` should be a list of positional arguments to pass to your class'
|
|
``__init__`` method. Everything in this list should itself be serializable.
|
|
|
|
* ``kwargs`` should be a dict of keyword arguments to pass to your class'
|
|
``__init__`` method. Every value should itself be serializable.
|
|
|
|
.. note::
|
|
This return value is different from the ``deconstruct()`` method
|
|
:ref:`for custom fields <custom-field-deconstruct-method>` which returns a
|
|
tuple of four items.
|
|
|
|
Django will write out the value as an instantiation of your class with the
|
|
given arguments, similar to the way it writes out references to Django fields.
|
|
|
|
To prevent a new migration from being created each time
|
|
:djadmin:`makemigrations` is run, you should also add a ``__eq__()`` method to
|
|
the decorated class. This function will be called by Django's migration
|
|
framework to detect changes between states.
|
|
|
|
As long as all of the arguments to your class' constructor are themselves
|
|
serializable, you can use the ``@deconstructible`` class decorator from
|
|
``django.utils.deconstruct`` to add the ``deconstruct()`` method::
|
|
|
|
from django.utils.deconstruct import deconstructible
|
|
|
|
@deconstructible
|
|
class MyCustomClass(object):
|
|
|
|
def __init__(self, foo=1):
|
|
self.foo = foo
|
|
...
|
|
|
|
def __eq__(self, other):
|
|
return self.foo == other.foo
|
|
|
|
|
|
The decorator adds logic to capture and preserve the arguments on their
|
|
way into your constructor, and then returns those arguments exactly when
|
|
deconstruct() is called.
|
|
|
|
.. _upgrading-from-south:
|
|
|
|
Upgrading from South
|
|
--------------------
|
|
|
|
If you already have pre-existing migrations created with
|
|
`South <http://south.aeracode.org>`_, then the upgrade process to use
|
|
``django.db.migrations`` is quite simple:
|
|
|
|
* Ensure all installs are fully up-to-date with their migrations.
|
|
* Remove ``'south'`` from :setting:`INSTALLED_APPS`.
|
|
* Delete all your (numbered) migration files, but not the directory or
|
|
``__init__.py`` - make sure you remove the ``.pyc`` files too.
|
|
* Run ``python manage.py makemigrations``. Django should see the empty
|
|
migration directories and make new initial migrations in the new format.
|
|
* Run ``python manage.py migrate``. Django will see that the tables for the
|
|
initial migrations already exist and mark them as applied without running
|
|
them.
|
|
|
|
That's it! The only complication is if you have a circular dependency loop
|
|
of foreign keys; in this case, ``makemigrations`` might make more than one
|
|
initial migration, and you'll need to mark them all as applied using::
|
|
|
|
python manage.py migrate --fake yourappnamehere
|
|
|
|
Libraries/Third-party Apps
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
If you are a library or app maintainer, and wish to support both South migrations
|
|
(for Django 1.6 and below) and Django migrations (for 1.7 and above) you should
|
|
keep two parallel migration sets in your app, one in each format.
|
|
|
|
To aid in this, South 1.0 will automatically look for South-format migrations
|
|
in a ``south_migrations`` directory first, before looking in ``migrations``,
|
|
meaning that users' projects will transparently use the correct set as long
|
|
as you put your South migrations in the ``south_migrations`` directory and
|
|
your Django migrations in the ``migrations`` directory.
|
|
|
|
More information is available in the
|
|
`South 1.0 release notes <http://south.readthedocs.org/en/latest/releasenotes/1.0.html#library-migration-path>`_.
|
|
|
|
.. seealso::
|
|
|
|
:doc:`The Migrations Operations Reference </ref/migration-operations>`
|
|
Covers the schema operations API, special operations, and writing your
|
|
own operations.
|