Opened 15 months ago

Last modified 15 months ago

#27164 new Cleanup/optimization

Database routers examples could be more realistic

Reported by: michaeloconnor Owned by: nobody
Component: Documentation Version: 1.8
Severity: Normal Keywords: multiple databases docs
Cc: Triage Stage: Accepted
Has patch: no 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 (5)

comment:1 Changed 15 months ago by Tim Graham

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.

  1. What's the error and what are the steps to reproduce?
  2. This might be valid. If you tested and confirmed it, feel free to submit a correction.
  3. Did you setup appropriate DATABASE_ROUTERS as 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?
  4. We could certainly consider revising that example.

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.

comment:2 Changed 15 months ago by Tim Graham <timograham@…>

In 789f9c9b:

Refs #27164 -- Fixed typo in docs/topics/db/multi-db.txt

comment:3 Changed 15 months ago by Tim Graham <timograham@…>

In 2078b187:

[1.10.x] Refs #27164 -- Fixed typo in docs/topics/db/multi-db.txt

Backport of 789f9c9b29dc79c3007b2b31cb75cf8d037f266d from master

comment:4 Changed 15 months ago by michaeloconnor

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 Changed 15 months ago by Tim Graham

Component: Database layer (models, ORM)Documentation
Easy pickings: unset
Summary: Multiple problems with multiple database docs for 1.8 and possibly other versionsDatabase routers examples could be more realistic
Triage Stage: UnreviewedAccepted
Type: BugCleanup/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.

Note: See TracTickets for help on using tickets.
Back to Top