Opened 8 years ago

Closed 4 years ago

Last modified 4 years ago

#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 Tim Graham, 8 years ago

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 by Tim Graham <timograham@…>, 8 years ago

In 789f9c9b:

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

comment:3 by Tim Graham <timograham@…>, 8 years ago

In 2078b187:

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

Backport of 789f9c9b29dc79c3007b2b31cb75cf8d037f266d from master

comment:4 by michaeloconnor, 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 Tim Graham, 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 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.

comment:6 by Caio Ariede, 4 years ago

Owner: changed from nobody to Caio Ariede
Status: newassigned

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?

comment:7 by Caio Ariede, 4 years ago

Has patch: set
Version: 1.8master

comment:8 by Mariusz Felisiak <felisiak.mariusz@…>, 4 years ago

Resolution: fixed
Status: assignedclosed

In 11e42001:

[2.2.x] Fixed #27164 -- Fixed an example of using routers in multiple databases docs.

Make sure that AuthRouter includes ContentType in the same database.

Backport of 608e06023e6eaf75f744134a0fd203853260e616 from master

comment:9 by Mariusz Felisiak <felisiak.mariusz@…>, 4 years ago

In 5f24b18e:

[3.0.x] Fixed #27164 -- Fixed an example of using routers in multiple databases docs.

Make sure that AuthRouter includes ContentType in the same database.

Backport of 608e06023e6eaf75f744134a0fd203853260e616 from master

comment:10 by Mariusz Felisiak <felisiak.mariusz@…>, 4 years ago

In 608e0602:

Fixed #27164 -- Fixed an example of using routers in multiple databases docs.

Make sure that AuthRouter includes ContentType in the same database.

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