The Django’s built-in authentication system is great. For the most part we can use it out-of-the-box, saving a lot of development and testing effort. It fits most of the use cases and is very safe. But sometimes we need to do some fine adjustment so to fit our Web application.
Commonly we want to store a few more data related to our User. If your Web application have an social appeal, you might want to store a short bio, the location of the user, and other things like that.
In this tutorial I will present the strategies you can use to simply extend the default Django User Model, so you don’t need to implement everything from scratch.
Ways to Extend the Existing User Model
Generally speaking, there are four different ways to extend the existing User model. Read below why and when to use them.
Option 1: Using a Proxy Model
What is a Proxy Model?
It is a model inheritance without creating a new table in the database. It is used to
change the behaviour of an existing model (e.g. default ordering, add new methods, etc.) without affecting the existing
database schema.
When should I use a Proxy Model?
You should use a Proxy Model to extend the existing User model when you don’t need to store extra information in the
database, but simply add extra methods or change the model’s query Manager.
That’s what I need! Take me to the instructions.
Option 2: Using One-To-One Link With a User Model (Profile)
What is a One-To-One Link?
It is a regular Django model that’s gonna have it’s own database table and will hold a One-To-One relationship with the
existing User Model through a OneToOneField
.
When should I use a One-To-One Link?
You should use a One-To-One Link when you need to store extra information about the existing User Model that’s not
related to the authentication process. We usually call it a User Profile.
That’s what I need! Take me to the instructions.
Option 3: Creating a Custom User Model Extending AbstractBaseUser
What is a Custom User Model Extending AbstractBaseUser?
It is an entirely new User model that inherit from AbstractBaseUser
. It requires a special care and to update some
references through the settings.py
. Ideally it should be done in the begining of the project, since it will
dramatically impact the database schema. Extra care while implementing it.
When should I use a Custom User Model Extending AbstractBaseUser?
You should use a Custom User Model when your application have specific requirements in relation to the authentication
process. For example, in some cases it makes more sense to use an email address as your identification token instead of
a username.
That’s what I need! Take me to the instructions.
Option 4: Creating a Custom User Model Extending AbstractUser
What is a Custom User Model Extending AbstractUser?
It is a new User model that inherit from AbstractUser
. It requires a special care and to update some
references through the settings.py
. Ideally it should be done in the begining of the project, since it will
dramatically impact the database schema. Extra care while implementing it.
When should I use a Custom User Model Extending AbstractUser?
You should use it when you are perfectly happy with how Django handles the authentication process and you wouldn’t
change anything on it. Yet, you want to add some extra information directly in the User model, without having to create
an extra class (like in the Option 2).
That’s what I need! Take me to the instructions.
Extending User Model Using a Proxy Model
This is the less intrusive way to extend the existing User model. You won’t have any drawbacks with that strategy. But it is very limited in many ways.
Here is how you do it:
In the example above we have defined a Proxy Model named Person
. We tell Django this is a Proxy Model by
adding the following property inside the Meta class: proxy = True
.
In this case I’ve redefined the default ordering, assigned a custom Manager
to the model, and also defined a new
method do_something
.
It is worth noting that User.objects.all()
and Person.objects.all()
will query the same database table. The only
difference is in the behavior we define for the Proxy Model.
If that’s all you need, go for it. Keep it simple.
Extending User Model Using a One-To-One Link
There is a good chance that this is what you want. Personally that is the method I use for the most part. We will be creating a new Django Model to store the extra information that relates to the User Model.
Bear in mind that using this strategy results in additional queries or joins to retrieve the related data. Basically all the time you access an related data, Django will fire an additional query. But this can be avoided for the most cases. I will get back to that later on.
I usually name the Django Model as Profile
:
Now this is where the magic happens: we will now define signals so our Profile
model will be automatically
created/updated when we create/update User instances.
Basically we are hooking the create_user_profile
and save_user_profile
methods to the User model, whenever a
save event occurs. This kind of signal is called post_save
.
Great stuff. Now, tell me how can I use it.
Piece of cake. Check this example in a Django Template:
How about inside a view method?
Generally speaking, you will never have to call the Profile’s save method. Everything is done through the User model.
What if I’m using Django Forms?
Did you know that you can process more than one form at once? Check out this snippet:
forms.py
views.py
profile.html
And the extra database queries you were talking about?
Oh, right. I’ve addressed this issue in another post named “Optimize Database Queries”. You can read it clicking here.
But, long story short: Django relationships are lazy. Meaning Django will only query the database if you access one of
the related properties. Sometimes it causes some undesired effects, like firing hundreds or thousands of queries.
This problem can be mitigated using the select_related
method.
Knowing beforehand you will need to access a related data, you can prefetch it in a single database query:
Extending User Model Using a Custom Model Extending AbstractBaseUser
The hairy one. Well, honestly I try to avoid it at all costs. But sometimes you can’t run from it. And it is perfectly fine. There is hardly such a thing as best or worst solution. For the most part there is a more or less appropriate solution. If this is the most appropriate solution for you case, go ahead.
I had to do it once. Honestly I don’t know if this is the cleaner way to do it, but, here goes nothing:
I needed to use email address as auth token and in the scenario the username
was completly useless for me. Also there
was no need for the is_staff
flag, as I wasn’t using the Django Admin.
Here is how I defined my own user model:
I wanted to keep it as close as possible to the existing User model. Since we are inheriting from the
AbstractBaseUser
we have to follow some rules:
- USERNAME_FIELD: A string describing the name of the field on the User model that is used as the unique
identifier. The field must be unique (i.e., have
unique=True
set in its definition); - REQUIRED_FIELDS: A list of the field names that will be prompted for when creating a user via the
createsuperuser
management command; - is_active: A boolean attribute that indicates whether the user is considered “active”;
- get_full_name(): A longer formal identifier for the user. A common interpretation would be the full name of the user, but it can be any string that identifies the user.
- get_short_name(): A short, informal identifier for the user. A common interpretation would be the first name of the user.
Okay, let’s move forward. I had also to define my own UserManager
. That’s because the existing manager define the
create_user
and create_superuser
methods.
So, here is what my UserManager
looks like:
Basically I’ve done a clean up of the existing UserManager
, removing the username
and the is_staff
property.
Now the final move. We have to update our settings.py. More specifically the AUTH_USER_MODEL
property.
This way we are telling Django to use our custom model instead the default one. In the example above, I’ve created the
custom model inside an app named core
.
How should I reference this model?
Well, there are two ways. Consider a model named Course
:
This is perfectly okay. But if you are creating a reusable app, that you want to make available for the public, it is strongly advised that you use the following strategy:
Extending User Model Using a Custom Model Extending AbstractUser
This is pretty straighforward since the class django.contrib.auth.models.AbstractUser
provides the full
implementation of the default User as an abstract model.
Then we have to update our settings.py defining the AUTH_USER_MODEL
property.
In a similar way as the previous method, this should be done ideally in the begining of a project and with an extra
care. It will change the whole database schema. Also, prefer to create foreign keys to the User model importing
the settings from django.conf import settings
and referring to the settings.AUTH_USER_MODEL
instead of referring
directly to the custom User model.
Conclusions
Alright! We’ve gone through four different ways to extend the existing User Model. I tried to give you as much details as possible. As I said before, there is no best solution. It will really depend on what you need to achieve. Keep it simple and choose wisely.
- Proxy Model: You are happy with everything Django User provide and don’t need to store extra information.
- User Profile: You are happy with the way Django handles the auth and need to add some non-auth related attributes to the User.
- Custom User Model from AbstractBaseUser: The way Django handles auth doesn’t fit your project.
- Custom User Model from AbstractUser: The way Django handles auth is a perfect fit for your project but still you want to add extra attributes without having to create a separate Model.
Do NOT hesitate to ask me questions or tell what you think about this post!
You can also join my mailing list. I send exclusive tips directly to your email every week! :-)