#27164 closed Cleanup/optimization (fixed)
Database routers examples could be more realistic
| Reported by: | michaeloconnor | Owned by: | Caio Ariede |
|---|---|---|---|
| Component: | Documentation | Version: | dev |
| Severity: | Normal | Keywords: | multiple databases docs |
| Cc: | Triage Stage: | Accepted | |
| Has patch: | yes | Needs documentation: | no |
| Needs tests: | no | Patch needs improvement: | no |
| Easy pickings: | no | UI/UX: | no |
Description
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").
Change History (10)
comment:1 by , 8 years ago
comment:4 by , 8 years ago
Let's see you start on the rather evident--- no code examples needed here--- contradiction between the fact that the AuthRouter() assigns all auth models and only auth models to one database and the statement at the bottom 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." This ticket is in part about documentation, writing--- not only about whether the given code example works or not.
That seeming conflict is in 1.7 through to dev. Yes or no. Is this not a glaring and absurd conflict (and a pain-inducing one at that for those who are new to multiple databases)? Wouldn't the django_content_type model end up in the second database, whereas the docs 1.7-dev all say it must be stored in the same database as auth?
Since 1.9 discontinued support for FastCGI some hosting companies offering shared-hosting (e.g., A2 Hosting, a "Django-friendly" company) are stalled out at Django 1.8.7 for now. I think that you can revise the 1.8 docs.
comment:5 by , 8 years ago
| Component: | Database layer (models, ORM) → Documentation |
|---|---|
| Easy pickings: | unset |
| Summary: | Multiple problems with multiple database docs for 1.8 and possibly other versions → Database routers examples could be more realistic |
| Triage Stage: | Unreviewed → Accepted |
| Type: | Bug → Cleanup/optimization |
I haven't made much use of multi-db support but at this point in my understanding, only point 2 seems valid, so I'll accept the ticket for that issue. If you can provide more details (steps to reproduce) about points 1 and 3, then please open separate tickets. Thanks.
comment:6 by , 5 years ago
| Owner: | changed from to |
|---|---|
| Status: | new → assigned |
I can see that the AuthRouter would not work in the provided example, given that a query for Permission that has a relationship with ContentType would not work.
It is not clear to me how to make that example work, given that, moving ContentType to auth_db would create other restrictions for models using ContentType.
Should we just replace this example with something else? Am I missing something?
Hi, we usually don't update old versions of the documentation except for critical issues so as not to introduce untranslated text in the translated versions of the docs. There have been some updates and corrections in newer versions so if you could please check if these issues are relevant in newer versions of the docs, that would be helpful.
DATABASE_ROUTERSas described, "You must setup DATABASE_ROUTERS for all of your apps’ models, including those in any contrib and third-party apps you are using, so that no queries are routed to the default database in order to do this." How do you reproduce the issue?You've raised several issues which probably are best addressed in different patches. For future reference, it's better to open separate tickets rather than combining several different issues.