Django/django
11
0
Fork 0
Code Pull Requests Projects Releases Activity

[1.10.x] Fixed #24370 -- Recommended starting with a custom user model.

Browse Source 
Backport of d02a03d574b6623ce0d648dd676ae278d46375fb from master
This commit is contained in:
Krzysztof Gogolewski 2016-11-06 13:49:35 +01:00 committed by Tim Graham
parent a079d5ceed
commit 9f89ca41db
1 changed files with 42 additions and 29 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

63
docs/topics/auth/customizing.txt
View File

@ -385,40 +385,53 @@ This dotted pair describes the name of the Django app (which must be in your
:setting:`INSTALLED_APPS`), and the name of the Django model that you wish to :setting:`INSTALLED_APPS`), and the name of the Django model that you wish to
use as your User model. use as your User model.
.. warning:: Using a custom user model when starting a project
-------------------------------------------------
Changing :setting:`AUTH_USER_MODEL` has a big effect on your database If you're starting a new project, it's highly recommended to set up a custom
structure. It changes the tables that are available, and it will affect the user model, even if the default :class:`~django.contrib.auth.models.User` model
construction of foreign keys and many-to-many relationships. If you intend is sufficient for you. This model behaves identically to the default user
to set :setting:`AUTH_USER_MODEL`, you should set it before creating model, but you'll be able to customize it in the future if the need arises::
from django.conf.auth.models import AbstractUser
class User(AbstractUser):
pass
Don't forget to point :setting:`AUTH_USER_MODEL` to it. Do this before creating
any migrations or running ``manage.py migrate`` for the first time. any migrations or running ``manage.py migrate`` for the first time.
Changing this setting after you have tables created is not supported Changing to a custom user model mid-project
by :djadmin:`makemigrations` and will result in you having to manually -------------------------------------------
fix your schema, port your data from the old user table, and possibly
manually reapply some migrations.
.. warning:: Changing :setting:`AUTH_USER_MODEL` after you've created database tables is
significantly more difficult since it affects foreign keys and many-to-many
relationships, for example.
This change can't be done automatically and requires manually fixing your
schema, moving your data from the old user table, and possibly manually
reapplying some migrations. See :ticket:`25313` for an outline of the steps.
Due to limitations of Django's dynamic dependency feature for swappable Due to limitations of Django's dynamic dependency feature for swappable
models, you must ensure that the model referenced by :setting:`AUTH_USER_MODEL` models, the model referenced by :setting:`AUTH_USER_MODEL` must be created in
is created in the first migration of its app (usually called ``0001_initial``); the first migration of its app (usually called ``0001_initial``); otherwise,
otherwise, you will have dependency issues. you'll have dependency issues.
In addition, you may run into a CircularDependencyError when running your In addition, you may run into a ``CircularDependencyError`` when running your
migrations as Django won't be able to automatically break the dependency migrations as Django won't be able to automatically break the dependency loop
loop due to the dynamic dependency. If you see this error, you should due to the dynamic dependency. If you see this error, you should break the loop
break the loop by moving the models depended on by your User model by moving the models depended on by your user model into a second migration.
into a second migration (you can try making two normal models that (You can try making two normal models that have a ``ForeignKey`` to each other
have a ForeignKey to each other and seeing how ``makemigrations`` resolves that and seeing how ``makemigrations`` resolves that circular dependency if you want
circular dependency if you want to see how it's usually done) to see how it's usually done.)
.. admonition:: Reusable apps and ``AUTH_USER_MODEL`` Reusable apps and ``AUTH_USER_MODEL``
-------------------------------------
Reusable apps shouldn't implement a custom user model. A project may use Reusable apps shouldn't implement a custom user model. A project may use many
many apps, and two reusable apps that implemented a custom user model apps, and two reusable apps that implemented a custom user model couldn't be
couldn't be used together. If you need to store per user information in your used together. If you need to store per user information in your app, use
app, use a :class:`~django.db.models.ForeignKey` or a :class:`~django.db.models.ForeignKey` or
:class:`~django.db.models.OneToOneField` to ``settings.AUTH_USER_MODEL`` :class:`~django.db.models.OneToOneField` to ``settings.AUTH_USER_MODEL``
as described below. as described below.