Clarified SeparateDatabaseAndState docs and added example of changing ManyToManyField.

[adamchainz]

The SeparateDatabaseAndState documentation has always been too short and non-visual for how often one ends up using it (at least, I do). This adds an example and rewords it to point to RunSQL.state_operations and be less patronizing about avoiding it.

[adamchainz]

The example is drawn from a draft blog post I have - it's maybe not the best since it uses an empty database_operations, but it's the best use case I have off the top of my head.

[felixxm]

@adamchainz Thanks 👍 I would move an example to the howto/writing-migrations.txt (with a specific use case) and ref it in docs/ref/migration-operations.txt. I used migrations.SeparateDatabaseAndState few times and IMO moving from a custom to an auto-generated intermediate table for ManyToManyField is a better example because it uses both database_operations and state_operations, e.g. (sorry for a typos and not representative names)

        migrations.SeparateDatabaseAndState(
            database_operations=[
                # Rename a custom intermediate table to an auto-generated name.
                migrations.RunSQL(
                    '''
                        ALTER TABLE x RENAME TO y
                    ''',
                    '''
                        ALTER TABLE y RENAME TO x
                    ''',
                ),
            ],
            state_operations=[
                migrations.AlterUniqueTogether(
                    name='customintermediatemodel',
                    unique_together=set(),
                ),
                migrations.RemoveField(
                    model_name='customintermediatemodel',
                    name='foreign_key_1',
                ),
                migrations.RemoveField(
                    model_name='customintermediatemodel',
                    name='foreign_key_2',
                ),
                migrations.AlterField(
                    model_name='model1',
                    name='model_2_objs',
                    field=models.ManyToManyField(to='my_app.Model2'),
                ),
                migrations.DeleteModel(
                    name='CustomIntermediateModel',
                ),
            ],

What do you think?

[adamchainz]

Updated. I went the other way and used a migration to add the through model. Project: https://github.com/adamchainz/django-document-separate-database-and-state

[felixxm]

@adamchainz Thanks 👍 I pushed minor edits and added AuthorBook._meta.db_table tip.

[adamchainz]

Thanks, I pushed a version of the advice on _meta.db_table into the text above, so it's alongside the advice where to get the new table name. I then expanded the comment in the migration to include where the old table name came from.

[carltongibson]

Super stuff. Thanks @adamchainz (and others).

[adamchainz]

Cheers all for review, I added you all as coauthors :)

[felixxm]

Merged in a9ee687.