[1.8.x] Added a "Writing migrations" how-to.

Backport of 570912a97d from master
This commit is contained in:
Tim Graham 2015-02-03 13:09:54 -05:00
parent b35c226154
commit ff39de1e1e
4 changed files with 78 additions and 64 deletions

View File

@ -26,6 +26,7 @@ you quickly accomplish common tasks.
static-files/index
static-files/deployment
windows
writing-migrations
.. seealso::

View File

@ -0,0 +1,69 @@
===========================
Writing database migrations
===========================
This document explains how to structure and write database migrations for
different scenarios you might encounter. For introductory material on
migrations, see :doc:`the topic guide </topics/migrations>`.
.. _data-migrations-and-multiple-databases:
Data migrations and multiple databases
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When using multiple databases, you may need to figure out whether or not to
run a migration against a particular database. For example, you may want to
**only** run a migration on a particular database.
In order to do that you can check the database connection's alias inside a
``RunPython`` operation by looking at the ``schema_editor.connection.alias``
attribute::
from django.db import migrations
def forwards(apps, schema_editor):
if not schema_editor.connection.alias == 'default':
return
# Your migration code goes here
class Migration(migrations.Migration):
dependencies = [
# Dependencies to other migrations
]
operations = [
migrations.RunPython(forwards),
]
.. versionadded:: 1.8
You can also provide hints that will be passed to the :meth:`allow_migrate()`
method of database routers as ``**hints``:
.. snippet::
:filename: myapp/dbrouters.py
class MyRouter(object):
def allow_migrate(self, db, model, **hints):
if 'target_db' in hints:
return db == hints['target_db']
return True
Then, to leverage this in your migrations, do the following::
from django.db import migrations
def forwards(apps, schema_editor):
# Your migration code goes here
class Migration(migrations.Migration):
dependencies = [
# Dependencies to other migrations
]
operations = [
migrations.RunPython(forwards, hints={'target_db': 'default'}),
]

View File

@ -76,7 +76,8 @@ manipulating the data of your Web application. Learn more about it below:
* **Migrations:**
:doc:`Introduction to Migrations<topics/migrations>` |
:doc:`Operations reference <ref/migration-operations>` |
:doc:`SchemaEditor <ref/schema-editor>`
:doc:`SchemaEditor <ref/schema-editor>` |
:doc:`Writing migrations <howto/writing-migrations>`
* **Advanced:**
:doc:`Managers <topics/db/managers>` |

View File

@ -515,74 +515,13 @@ You can pass a second callable to
want executed when migrating backwards. If this callable is omitted, migrating
backwards will raise an exception.
.. _data-migrations-and-multiple-databases:
Data migrations and multiple databases
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When using multiple databases, you may need to figure out whether or not to
run a migration against a particular database. For example, you may want to
**only** run a migration on a particular database.
In order to do that you can check the database connection's alias inside a
``RunPython`` operation by looking at the ``schema_editor.connection.alias``
attribute::
from django.db import migrations
def forwards(apps, schema_editor):
if not schema_editor.connection.alias == 'default':
return
# Your migration code goes here
class Migration(migrations.Migration):
dependencies = [
# Dependencies to other migrations
]
operations = [
migrations.RunPython(forwards),
]
.. versionadded:: 1.8
You can also provide hints that will be passed to the :meth:`allow_migrate()`
method of database routers as ``**hints``:
.. snippet::
:filename: myapp/dbrouters.py
class MyRouter(object):
def allow_migrate(self, db, model, **hints):
if 'target_db' in hints:
return db == hints['target_db']
return True
Then, to leverage this in your migrations, do the following::
from django.db import migrations
def forwards(apps, schema_editor):
# Your migration code goes here
class Migration(migrations.Migration):
dependencies = [
# Dependencies to other migrations
]
operations = [
migrations.RunPython(forwards, hints={'target_db': 'default'}),
]
More advanced migrations
~~~~~~~~~~~~~~~~~~~~~~~~
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>`.
</ref/migration-operations>` and the "how-to" on :doc:`writing migrations
</howto/writing-migrations>`.
.. _migration-squashing:
@ -849,3 +788,7 @@ More information is available in the
:doc:`The Migrations Operations Reference </ref/migration-operations>`
Covers the schema operations API, special operations, and writing your
own operations.
:doc:`The Writing Migrations "how-to" </howto/writing-migrations>`
Explains how to structure and write database migrations for different
scenarios you might encounter.