From 6b41f07720be7c817a8023905a1f55d72f534327 Mon Sep 17 00:00:00 2001 From: Adam Johnson Date: Tue, 3 Mar 2020 17:51:39 +0000 Subject: [3.0.x] Clarified SeparateDatabaseAndState docs and added example of changing ManyToManyField. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Mariusz Felisiak Co-Authored-By: Carlton Gibson Co-Authored-By: René Fleschenberg Backport of a9ee6872bd9e1bacc2da827dbd5b9093f724e4a5 from master --- docs/ref/migration-operations.txt | 20 ++++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/migration-operations.txt b/docs/ref/migration-operations.txt index 7cc9bd550a..27ffc43c52 100644 --- a/docs/ref/migration-operations.txt +++ b/docs/ref/migration-operations.txt @@ -423,12 +423,24 @@ if ``atomic=True`` is passed to the ``RunPython`` operation. .. class:: SeparateDatabaseAndState(database_operations=None, state_operations=None) -A highly specialized operation that let you mix and match the database +A highly specialized operation that lets you mix and match the database (schema-changing) and state (autodetector-powering) aspects of operations. -It accepts two lists of operations, and when asked to apply state will use the -state list, and when asked to apply changes to the database will use the database -list. Do not use this operation unless you're very sure you know what you're doing. +It accepts two lists of operations. When asked to apply state, it will use the +``state_operations`` list (this is a generalized version of :class:`RunSQL`'s +``state_operations`` argument). When asked to apply changes to the database, it +will use the ``database_operations`` list. + +If the actual state of the database and Django's view of the state get out of +sync, this can break the migration framework, even leading to data loss. It's +worth exercising caution and checking your database and state operations +carefully. You can use :djadmin:`sqlmigrate` and :djadmin:`dbshell` to check +your database operations. You can use :djadmin:`makemigrations`, especially +with :option:`--dry-run`, to check your state +operations. + +For an example using ``SeparateDatabaseAndState``, see +:ref:`changing-a-manytomanyfield-to-use-a-through-model`. .. _writing-your-own-migration-operation: -- cgit v1.3