Django REST Framework_001: Using a Custom User Model

In Django projects, working with users is a fundamental part of many applications. By default, Django provides the auth.User model, which includes basic user fields like username, email, password, etc. While sufficient for many scenarios, this default model may not always fit your application’s needs. To address this, Django allows you to define your own custom user model.

In this lesson, we will:

1. Learn how to define a custom user model.
2. Understand what the AUTH_USER_MODEL setting does and why it’s essential.
3. Discuss common issues when AUTH_USER_MODEL is not properly configured and how to resolve them.

Why Use a Custom User Model?

Sometimes, the default auth.User model may not meet the requirements of your application. For example, you might want to:

• Add fields like phone_number, profile_picture, or date_of_birth.
• Remove unnecessary fields that your application does not use.
• Extend the default user authentication functionality.

Using a custom user model allows for these customizations while maintaining compatibility with Django’s built-in authentication system.

Steps to Create and Use a Custom User Model

Step 1: Create a New Django Project

Run the following commands to set up a Django project and app:

django-admin startproject custom_user_project
cd custom_user_project
django-admin startapp api

This creates the project custom_user_project and the app api.

Step 2: Define the Custom User Model

In the api app, define a custom user model in models.py. To create a custom user model, Django provides the AbstractUser class, which already includes the basic fields and methods of a user.

Here is an example:

from django.contrib.auth.models import AbstractUser
from django.db import models

class User(AbstractUser):
    # Add custom fields if needed
    phone_number = models.CharField(max_length=15, blank=True, null=True)

    def __str__(self):
        return self.username

This class:

• Inherits from AbstractUser, which includes fields like username, email, password, etc.
• Adds an optional phone_number field for additional functionality.

You can now use this User model as the user model for your project.

Step 3: Set AUTH_USER_MODEL

In the settings.py file, add the following:

AUTH_USER_MODEL = "api.User"

The AUTH_USER_MODEL setting tells Django to use your custom user model (api.User) instead of the default auth.User model.

Is AUTH_USER_MODEL a Predefined Keyword in Django? Yes, AUTH_USER_MODEL is a predefined setting in Django. By default, it is set to 'auth.User', which refers to Django’s built-in user model. When you create a custom user model, this setting must explicitly point to your model in the format '<app_name>.<model_name>'.

 Why Do We Need AUTH_USER_MODEL?

If you don’t set AUTH_USER_MODEL and try to use a custom user model, Django will still reference the default auth.User. This creates conflicts, especially when you have relationships like groups or permissions in your custom user model.

For example, without AUTH_USER_MODEL, you may encounter the following error:

django.core.management.base.SystemCheckError: SystemCheckError: System check identified some issues:

ERRORS:
api.User.groups: (fields.E304) Reverse accessor 'Group.user_set' for 'api.User.groups' clashes with reverse accessor for 'auth.User.groups'.
        HINT: Add or change a related_name argument to the definition for 'api.User.groups' or 'auth.User.groups'.

This happens because Django tries to create reverse relationships for both auth.User and your custom user model. By setting AUTH_USER_MODEL, you prevent Django from referencing auth.User, resolving such conflicts.

Step 4: Apply Migrations

After defining your custom user model and setting AUTH_USER_MODEL, apply the migrations:

python manage.py makemigrations
python manage.py migrate

Django will now create the database schema for your custom user model.

Common Issues and Fixes

Problem: SystemCheckError (Reverse Accessor Clash)

As mentioned earlier, this error occurs when Django tries to reference both the default auth.User and your custom user model. The conflict arises because both models attempt to define reverse relationships with groups and permissions.

Solution

The solution is to set AUTH_USER_MODEL to your custom user model in settings.py:

AUTH_USER_MODEL = "api.User"

 

This ensures that Django uses your custom user model exclusively.