diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/releases/1.7.txt | 12 | ||||
| -rw-r--r-- | docs/topics/db/multi-db.txt | 10 | ||||
| -rw-r--r-- | docs/topics/migrations.txt | 23 |
3 files changed, 43 insertions, 2 deletions
diff --git a/docs/releases/1.7.txt b/docs/releases/1.7.txt index df2b10d18c..a617c90b34 100644 --- a/docs/releases/1.7.txt +++ b/docs/releases/1.7.txt @@ -110,6 +110,18 @@ Backwards incompatible changes in 1.7 deprecation timeline for a given feature, its removal may appear as a backwards incompatible change. +allow_syncdb/allow_migrate +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +While Django will still look at ``allow_syncdb`` methods even though they +should be renamed to ``allow_migrate``, there is a subtle difference in which +models get passed to these methods. + +For apps with migrations, ``allow_migrate`` will now get passed +:ref:`historical models <historical-models>`, which are special versioned models +without custom attributes, methods or managers. Make sure your ``allow_migrate`` +methods are only referring to fields or other items in ``model._meta``. + Miscellaneous ~~~~~~~~~~~~~ diff --git a/docs/topics/db/multi-db.txt b/docs/topics/db/multi-db.txt index 6c74fb944d..6e19844b5c 100644 --- a/docs/topics/db/multi-db.txt +++ b/docs/topics/db/multi-db.txt @@ -163,8 +163,14 @@ A database Router is a class that provides up to four methods: the router has no opinion. This method can be used to determine the availability of a model on a given database. - Note that if this returns ``True`` for an app with migrations but - ``False`` for an app those migrations depend on, Django will error. + Note that migrations will just silently not perform any operations + on a model for which this returns ``False``. This may result in broken + ForeignKeys, extra tables or missing tables if you change it once you + have applied some migrations. + + The value passed for ``model`` may be a + :ref:`historical model <historical-models>`, and thus not have any + custom attributes, methods or managers. You should only rely on ``_meta``. A router doesn't have to provide *all* these methods -- it may omit one or more of them. If one of the methods is omitted, Django will skip diff --git a/docs/topics/migrations.txt b/docs/topics/migrations.txt index f80cbf81fd..5f7def7107 100644 --- a/docs/topics/migrations.txt +++ b/docs/topics/migrations.txt @@ -272,3 +272,26 @@ Note that this only works given two things: * 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 and modify those tables. + + +.. 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 ``django.db.migrations.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). + +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. |