Make TransactionTestCase.multi_db documentation more discoverable.

[Adam Johnson]

I had a pull request that took me two years to resolve (okay, I deferred it quite a lot): ​https://github.com/adamchainz/django-mysql/pull/278 . This was adding pytest-randomly to my project, which randomly sorts the tests and exposes test interdependence. It turned out the failure was due to interdependence between tests that touched a secondary database, with the TestCase classes not resetting the secondary database, because multi_db=True was missing from such TestCases to get the secondary DB wiped between tests.

Part of the trouble debugging this was that multi_db is not easy to find:

• The page on multiple databases doesn't mention or link to testing considerations at all: ​https://docs.djangoproject.com/en/2.0/topics/db/multi-db/
• The 'test database' section of 'writing and running tests' *does* mention and link to 'advanced multi-db testing topics' : ​https://docs.djangoproject.com/en/2.0/topics/testing/overview/#the-test-database -> ​https://docs.djangoproject.com/en/2.0/topics/testing/advanced/#topics-testing-advanced-multidb . However the linked section, "Tests and multiple databases", doesn't mention multi_db - it's only in the "Advanced features of TransactionTestCase" section - and I'd argue it's not an advanced feature but a basic one, even a risk that you'll end up taking 2 years to debug an issue :)
• When multi_db is mentioned, it's only in the context of TransactionTestCase . TestCase isn't mentioned, which yes does inherit from TransactionTestCase, but it also has more behaviour, in the scope of class-level atomic()s that also obey the multi_db flag

I think we should fix the docs for these problems 🎉.

Secondarily, the feature is confusing and I'd flip the default of the flag to True and allow setting it to False as an optimization - but this is a much bigger change.

[Simon Charette]

#28478 is related.

It suggests merging multi_db and allow_database_queries flags into a single databases aliases set that would be unionized to determine which databases needs to be created based on the tests retrieved during discovery.

When a query to an unspecified database would be performed an error similar to the one raised when performing queries in a SimpleTestCase right now would be raised. SimpleTestCase.databases would be an empty set while TestCase.databases = {DEFAULT_DB_ALIAS}. multi_db = True could be alias for databases = {alias for alias in connections} during the deprecation period. We could also support a special databases = '__all__' value to replicate the actual multi_db behavior.

Here's the ​PoC.

[Tim Graham <timograham@…>]

In 2a01162:

Refs #29513 -- Linked the testing docs from the multi-db topic guide.

[Tim Graham <timograham@…>]

In db287e99:

[2.1.x] Refs #29513 -- Linked the testing docs from the multi-db topic guide.

Backport of 2a0116266c4d81bd1cc4e3ea20efe9a7874f481b from master

[Mariusz Felisiak]

We can treat this ticket as fixed, since multi_db will be removed in Django 3.1 (see b61ea56789a5825bd2961a335cb82f65e09f1614).