id	summary	reporter	owner	description	type	status	component	version	severity	resolution	keywords	cc	stage	has_patch	needs_docs	needs_tests	needs_better_patch	easy	ui_ux
27164	Database routers examples could be more realistic	michaeloconnor	Caio Ariede	"I am running (1, 8, 7, 'final', 0); this ticket pertains specifically to https://docs.djangoproject.com/en/1.8/topics/db/multi-db/ and to the code snippets in it.

First, in the discussion of Database Routers and in the code for the router AuthRouter(), the declaration of the method controlling migrations is  allow_migrate(db, app_label, model_name=None, *hints), which is stated to be new in 1.8, the 1.7 version having been deprecated. However, in reality in (1, 8, 7, 'final', 0) only the 1.7 version of this method works.

Secondly, the AuthRouter() code is designed to only permit apps with app_label =='auth' to be migrated to the database of the same name--- all other apps spill over, via the PrimaryReplicaRouter(), to one of the other databases and are migrated there. However, at the bottom of the page it clearly states that ""auth models — User, Group and Permission — are linked together and linked to ContentType, so they must be stored in the same database as ContentType"". Thus, unless django_content_type is somehow  naturally given an app_label of 'auth', it would appear that this is a contradiction.

The third matter is the 'default': {} recommendation. With several tries I only get an error message to the effect that {} can't be empty.

In all it appears that the given code was never tested.

I can recommend a simple example, for which the painful ""Example purposes only!"" disclaimer should be unnecessary. I am now happy with one database being 'default':{...}, with the name of the database being also 'default'. For that one I provide no router at all. For two others I use an AuthRouter()-type that rigidly connects each of two apps of my own to a corresponding database of the two. And so only the two routers for the two databases are in the settings.py router chain.

With that, I have thrown away the migrations folders and checked to be sure that the makemigrations-migrate sequence does the correct migrations. It does--- the auth models and django_site, django_session, django_migrations and django_content_type all end up in the 'default' database; my models end up in the others.

Finally, ""admin depends on auth, so their models must be in the same database as auth"" should be corrected (e.g. ""its models"")."	Cleanup/optimization	closed	Documentation	dev	Normal	fixed	multiple databases docs		Accepted	1	0	0	0	0	0