Django Race Conditions: Unique constraints
A fun challenge of any application is handling the race conditions. I’m talking about concurrent requests attempting to take the same action at the same time. This can be a particularly difficult thing to implement, as we can see in Haki Benita’s fantastic resource, “How to Get or Create in PostgreSQL”. It’s a lengthy discussion on how to do something “simple”, but it’s anything but that.
This post and a few others (links to be provided in the future) will show what Django provides and how it can be extended to handle race conditions given your own constraints.
Please note, this is written using PostgreSQL for the database. If you’re using another database, you’ll need to check what the equivalent is or if there is support.
The core problem
At its core the problem we’re trying to solve is avoiding errors when the same or similar requests are made at the same time. For example, PyPI is a central repository for Python packages. If two people try to publish a package with the name “django-coolness” at the same time, what happens?
The other version of this would be that there are two users editing the same object in the Django admin. When they both press save, what should happen? Admittedly, this is partly a business logic question. It could be fine to overwrite a blog post entirely.
However, if you’re dealing with orders and one user is marking it as paid and the other as cancelled, that end user could be perplexed. Especially if changing the state on a request triggers background tasks.
The basics
There are some common features of Django that you should familiarize yourself with if you’re dealing with race conditions. However, they will not be used in this post.
The Django docs cover these well enough that I am not going into detail on them.
Enforcing a unique constraint
The first race condition I’d like to discuss is enforcing a unique constraint. At its surface, this feels like it should be as easy as defining a UniqueConstraint in your model and calling it a day.
And while that will enforce data integrity in your table, it doesn’t mean the user experience of your app will be adequate. Let’s look at this model, for example:
class Organization(models.Model):
name = models.CharField(max_length=200)
slug = models.SlugField(unique=True)
class Project(models.Model):
organization = models.ForeignKey(
Organization, related_name="projects", on_delete=models.CASCADE
)
name = models.CharField(max_length=200)
slug = models.SlugField()
class Meta:
constraints = [
models.UniqueConstraint(
fields=["organization", "slug"],
name="unique_project_slug_per_org",
),
]
We’re going to see how the Project.organization foreign key causes some problems later. For now, though, let’s focus on Organization. Django automatically provides support for evaluating unique constraints (when they are fields on the form).
Meaning the following form will automatically check that the new organization being created doesn’t reuse an existing slug:
class OrganizationForm(forms.ModelForm):
class Meta:
model = Organization
fields = ["name", "slug"]
That’s great! When users try to create duplicate data, they’ll get an invalid form error in the view. At least for requests that happen one after another. We’ll see later that two requests at the same time can both pass this check.
Let’s look at the Project case now. It has two problems. The first is that a duplicate slug causes a 500 even when the requests are minutes apart. The second is the race condition, where two requests submitted at the same time both pass validation. Here is a typical view and form implementation:
class ProjectForm(forms.ModelForm):
class Meta:
model = Project
fields = ["name", "slug"]
def __init__(self, *args, organization, **kwargs):
super().__init__(*args, **kwargs)
self.instance.organization = organization
def create_project(request, org_slug):
org = get_object_or_404(Organization, slug=org_slug)
form = ProjectForm(request.POST or None, organization=org)
if request.method == "POST" and form.is_valid():
form.save()
return redirect("project-list")
return render(request, "project_create_form.html",
{
"form": form,
"organization": org,
},
)
Because ProjectForm.Meta.fields does not include organization, that unique constraint is not evaluated as a part of form.is_valid(). It will be evaluated at the database, though, and unfortunately raise an IntegrityError which will cause the application to return a 500 response to your user.
We should be able to check that constraint in the form during the form.is_valid() check so that the user doesn’t break the entire application.
Check UniqueConstraint during the form validation
For cases where the UniqueConstraint has fields not included in the ModelForm.Meta.fields collection, we need Django to evaluate our extra constraint. This can be done by overriding ModelForm.validate_constraints:
class ProjectForm(forms.ModelForm):
# ...
def validate_constraints(self):
# The organization comes from the URL rather than a form field, and
# Django skips constraints on fields that aren't on the form. Without
# this, a duplicate slug would raise an IntegrityError on save.
exclude = self._get_validation_exclusions() - {"organization"}
try:
self.instance.validate_constraints(exclude=exclude)
except ValidationError as e:
self._update_errors(e)
Since our UniqueConstraint is on organization, but organization is not in ProjectForm.Meta.fields, we need to remove organization as a reason to exclude which constraints to evaluate.
Confusing? Yeah, probably.
Put another way, exclude = self._get_validation_exclusions() - {"organization"} means we want to validate the constraints that use the organization field.
Now we’ll get a form validation error if we try to create a project with a slug that’s already been used rather than a 500 error.
If we wanted to make that message a bit nicer (and I suspect you do), use the violation_error_message argument.
class Project(models.Model):
# ...
class Meta:
constraints = [
models.UniqueConstraint(
fields=["organization", "slug"],
name="unique_project_slug_per_org",
violation_error_code="project_slug_taken",
violation_error_message=(
"A project with this slug already exists in this organization."
),
),
]
Handling race conditions of concurrent requests in the database
While the above implementation of ProjectForm validates the constraint as a part of form.is_valid(), there’s still a chance that another request also passed that and will try to create the row at the same time. In other words, there’s a race condition.
One option is to let the database handle this. Which means when form.save() (or the underlying model_instance.save()) is called and the row is inserted, there’s a chance that we’ll get an IntegrityError.
We want to catch that exception so that the user doesn’t get a 500 error page. Which means we need to wrap our save flow in a try/except.
# Look up the constraint based on its name.
SLUG_CONSTRAINT = next(
c for c in Project._meta.constraints if c.name == "unique_project_slug_per_org"
)
def violates_constraint(error, name):
"""Return whether an IntegrityError came from the named constraint."""
return error.__cause__.diag.constraint_name == name
def create_project(request, org_slug):
org = get_object_or_404(Organization, slug=org_slug)
form = ProjectForm(request.POST or None, organization=org)
if request.method == "POST" and form.is_valid():
try:
# The savepoint lets the request keep using the database after
# the failed insert.
with transaction.atomic():
form.save()
except IntegrityError as e:
if violates_constraint(e, SLUG_CONSTRAINT.name):
form.add_error(
None,
ValidationError(
SLUG_CONSTRAINT.get_violation_error_message(),
code=SLUG_CONSTRAINT.violation_error_code,
),
)
# Drop down to the render flow with the now invalid form
else:
raise
else:
# The save worked properly
return redirect("project-list")
return render(request, "project_create_form.html",
{
"form": form,
"organization": org,
},
)
With this, we will handle concurrent requests that would conflict with one another without causing one request to get a 500 error response.
The same applies to OrganizationForm. Its slug check runs before the insert, so it needs the same IntegrityError handling.
BUT! This is particularly ugly to me. I really don’t like that we have two different places to add form validation errors. This is especially visible in a CBV approach. Look at how ProjectCreateConcurrentView.form_valid can still result in form_invalid() being called. That’s unusual and annoying to remember.
class ConcurrentProjectForm(ProjectForm):
def save(self, commit=True):
try:
with transaction.atomic():
return super().save(commit=commit)
except IntegrityError as e:
if violates_constraint(e, SLUG_CONSTRAINT.name):
self.add_error(
None,
ValidationError(
SLUG_CONSTRAINT.get_violation_error_message(),
code=SLUG_CONSTRAINT.violation_error_code,
),
)
raise
class ProjectCreateConcurrentView(OrganizationProjectMixin, CreateView):
form_class = ConcurrentProjectForm
def form_valid(self, form):
try:
return super().form_valid(form)
except IntegrityError:
if not form.has_error(
NON_FIELD_ERRORS, code=SLUG_CONSTRAINT.violation_error_code
):
raise
return self.form_invalid(form)
Raising exceptions for invalid forms
An option to clean the above is to adopt DRF’s serializer’s concept of raising an exception for invalid data. Clearly, there are multiple places where a form may be determined to be invalid. It’s not just in form.is_valid(). So perhaps we should be using exceptions; it may be the better API for what we’re trying to represent.
# Look up the constraint from the models
SLUG_CONSTRAINT = next(
c for c in Project._meta.constraints if c.name == "unique_project_slug_per_org"
)
class FormIsInvalid(Exception):
"""New exception representing that the form is invalid."""
def __init__(self, form):
super().__init__(form.errors.as_text())
self.form = form
def violates_constraint(error, name):
"""Return whether an IntegrityError came from the named constraint."""
return error.__cause__.diag.constraint_name == name
class RaisingProjectForm(ProjectForm):
def is_valid(self):
"""Raise an exception if the form isn't valid, otherwise return True."""
if not super().is_valid():
raise FormIsInvalid(self)
return True
def save(self, commit=True):
self.is_valid()
try:
# The savepoint lets the request keep using the database after
# the failed insert.
with transaction.atomic():
return super().save(commit=commit)
except IntegrityError as e:
# Any other IntegrityError is a real failure.
if not violates_constraint(e, SLUG_CONSTRAINT.name):
raise
self.add_error(
None,
ValidationError(
SLUG_CONSTRAINT.get_violation_error_message(),
code=SLUG_CONSTRAINT.violation_error_code,
),
)
raise FormIsInvalid(self)
The most significant change in the above is overriding is_valid to raise a custom exception and then raising that exception from the save() method where our unique constraint is violated.
This style of form means our view gets significantly simpler:
def project_create_raising(request, org_slug):
organization = get_object_or_404(Organization, slug=org_slug)
form = RaisingProjectForm(request.POST or None, organization=organization)
if request.method == "POST":
try:
form.is_valid() # Redundant since save() will call is_valid()
project = form.save()
messages.success(request, f"Created project {project.name}.")
# Return to the same page so another project can be added.
return redirect(request.path)
except FormIsInvalid:
pass
return render(
request,
"myapp/project_form.html",
{"form": form, "organization": organization},
)
Admittedly, this isn’t super Django-ey. I’m conditioned to look for if form.is_valid() to find the error and success flow. It’d take me a bit to get used to looking for except FormIsInvalid instead. Plus, RaisingProjectForm will only work in views written for it. Django’s CBVs won’t work with it out of the box and would take a little tweaking.
I think many developers want to build their applications for scale (or maybe they just want to handle someone double-clicking the save button), and having a clean, readable way to implement that is a helpful thing. If you’re finding yourself in a scenario where you reasonably expect to hit concurrent request race conditions, consider switching to exception-driven form validation.
Writing unit tests for race conditions
There is a tricky scenario we need to test for in our application, and that is when there’s a duplicate row when save() commits.
Later when we get to race conditions with database locks, we’ll match what Django does with threads, but this is a bit simpler. In fact, a clanker came up with a clever solution, though it’s not far off from what Django does for a race condition with file-based caching. A solution is to dynamically create a new form class that would create the duplicate row after is_valid() is called. This is entirely contained in the racing function below.
from myapp.models import Project
def racing(form_class):
"""
Return a form class that inserts a duplicate project after is_valid
"""
class RacingForm(form_class):
raced = False
def is_valid(self):
valid = super().is_valid()
# Only insert the competing row once
if valid and not self.raced:
self.raced = True
Project.objects.create(
organization=self.instance.organization,
name="Competitor",
slug=self.cleaned_data["slug"],
)
return valid
return RacingForm
Then in the actual test, we either need to generate a new view using this form or monkeypatch the returned form in.
First the new view using the form:
from django.db import IntegrityError
from django.test import RequestFactory, TestCase
from myapp.approaches.unique_constraint.validate_only import ProjectCreateView, ProjectForm
from myapp.models import Organization
from myapp.tests.helpers import racing
class ProjectSlugTests(TestCase):
@classmethod
def setUpTestData(cls):
cls.acme = Organization.objects.create(name="Acme", slug="acme")
def test_create_race(self):
"""
A race condition on save with ProjectForm will result in an IntegrityError.
"""
view = ProjectCreateView.as_view(form_class=racing(ProjectForm))
request = RequestFactory().post("/", {"name": "Anvil", "slug": "anvil"})
with self.assertRaises(IntegrityError):
view(request, org_slug="acme")
Then the monkeypatch of our form in the test:
from unittest import mock
from django.test import TestCase
from django.urls import reverse
from myapp.approaches.unique_constraint import raise_form_invalid
from myapp.approaches.unique_constraint.raise_form_invalid import RaisingProjectForm
from myapp.models import Organization
from myapp.tests.helpers import PROJECT_SLUG_TAKEN, racing
class RaisingProjectSlugFunctionViewTests(TestCase):
@classmethod
def setUpTestData(cls):
cls.acme = Organization.objects.create(name="Acme", slug="acme")
cls.url = reverse("project-create-raising-fbv", kwargs={"org_slug": "acme"})
def test_create_race(self):
"""
A race condition on save with RaisingProjectForm will show a
form error.
"""
with mock.patch.object(
raise_form_invalid, "RaisingProjectForm", racing(RaisingProjectForm)
):
response = self.client.post(self.url, {"name": "Anvil", "slug": "anvil"})
self.assertFormError(response.context["form"], None, PROJECT_SLUG_TAKEN)
self.assertEqual(
list(self.acme.projects.filter(slug="anvil").values_list("name", flat=True)),
["Competitor"],
)
I really like the racing() helper in this case. It only works with Project, but that could be refactored out with some copy logic to make it reusable. Or just define it as racing_project and be done with it.
Regardless of how we test the race condition, it’s valuable to confirm that the test actually does what we want it to. This typically means commenting out functionality in our application code and confirming our test fails. For example, commenting out the except IntegrityError branch of RaisingProjectForm.save() and confirming that RaisingProjectSlugFunctionViewTests.test_create_race no longer passes. In fact, it should raise an IntegrityError. Once we’ve confirmed that our test pattern is solid, it’s much safer to copy/paste across the project.
Where to next?
The next post in this little series will be showing how to enforce business constraints via locking. If you can’t wait to read more, consider reading another excellent article from Haki Benita, “Handling Concurrency Without Locks: How to not let concurrency cripple your system”.
Additionally, if you’d like a better API than calling the private _get_validation_exclusions() method in your ModelForm to opt in to enforcing constraints, give an upvote to the feature request for it. This isn’t the first time it’s come up, but it has lacked support to see it pushed through.
If this type of improvement is in your interest, there’s a similar one you may also want to show your support for: “Raise a subclass of IntegrityError for duplicate key errors”
Written by Tim Schilling
Django 6.x Steering Council member, maintainer of django-debug-toolbar and django-simple-history, and a professional software engineer since 2009. These days, I mentor developers one-on-one.