Why save() Doesn't Validate by Default
A common surprise for newcomers is that calling model_instance.save() does not run validation — Django deliberately separates persistence from validation so that internal code, data migrations, and bulk operations aren't slowed down or blocked by validation logic on every write. To validate an instance, you must explicitly call full_clean(), which runs field validators, calls clean_fields(), clean(), and validate_unique(), and raises a ValidationError if anything fails. Django's ModelForm calls full_clean() automatically as part of is_valid(), which is why validation seems automatic when working through forms and the admin but not when saving model instances directly in code.
Cricket analogy: save() skipping validation by default is like a scorer's raw entry system accepting any number typed in without cross-checking it against the ball-by-ball commentary — full_clean() is the separate audit step that actually catches an impossible score.
Validators, clean_fields(), and clean()
Field-level validators are functions or callables passed via the validators= argument (or built-in ones like Django's URLValidator, EmailValidator, MinValueValidator, MaxValueValidator) that run during clean_fields() and raise ValidationError for a specific field if the value fails the check. Overriding clean() on the model itself is the place for validation logic that spans multiple fields, such as checking that a discount_price is less than the regular price, and errors raised there should be attached to specific fields using ValidationError({'discount_price': 'message'}) rather than a bare string when the error clearly belongs to one field.
Cricket analogy: MinValueValidator(0) on a runs_scored field is like a scoring app refusing to accept a negative run total for an innings — a validator catching an impossible value before it's ever saved.
from django.core.exceptions import ValidationError
from django.core.validators import MinValueValidator, MaxValueValidator
class Book(models.Model):
title = models.CharField(max_length=200)
price = models.DecimalField(max_digits=6, decimal_places=2)
discount_price = models.DecimalField(
max_digits=6, decimal_places=2, null=True, blank=True
)
rating = models.IntegerField(
validators=[MinValueValidator(1), MaxValueValidator(5)]
)
def clean(self):
if self.discount_price and self.discount_price >= self.price:
raise ValidationError(
{"discount_price": "Discount price must be less than the regular price."}
)
# Explicit validation before saving directly (outside a ModelForm)
book = Book(title="Django Deep Dive", price=25, discount_price=30, rating=5)
book.full_clean() # raises ValidationError here
book.save()full_clean() runs three phases in order: clean_fields() (per-field validators), clean() (your custom cross-field logic), and validate_unique() (checks unique and unique_together constraints against the database). If clean_fields() raises errors for a field, clean() still runs but should defensively handle missing/invalid data since those fields may not be reliable yet.
bulk_create() and QuerySet.update() bypass both save() and full_clean() entirely — no validators, no clean() logic, and no signals fire. If you rely on model validation or signal-based side effects, bulk operations can silently insert invalid data unless you validate rows manually before calling them.
Uniqueness Validation and the Admin
Uniqueness constraints declared via unique=True or Meta.constraints (UniqueConstraint) are enforced at the database level, but validate_unique() also checks them in Python before a save is attempted, producing a friendly ValidationError instead of letting an IntegrityError bubble up from the database driver. The Django admin site always calls full_clean() on every save through its forms, which is why duplicate entries are caught with a clear message in the admin UI even though the same duplicate insert via a raw save() call outside the admin would instead raise a database-level IntegrityError.
Cricket analogy: validate_unique() catching a duplicate player registration before it hits the database is like a scorer's assistant double-checking the team sheet for a repeated player name before submission, rather than letting the official scoring system reject it later with a cryptic error.
- Model.save() does not call full_clean() automatically; validation must be triggered explicitly.
- full_clean() runs clean_fields(), then clean(), then validate_unique(), and raises ValidationError on failure.
- ModelForm's is_valid() calls full_clean() automatically, which is why form and admin validation feels automatic.
- Field-level validators (validators= or built-ins like MinValueValidator) run during clean_fields() and target one field.
- Override clean() on the model for cross-field validation logic, attaching errors to specific fields where possible.
- bulk_create() and QuerySet.update() bypass save(), full_clean(), and signals entirely.
- Always call full_clean() explicitly before save() when creating or editing model instances outside of a ModelForm.
Practice what you learned
1. Does calling model_instance.save() automatically validate the instance's data?
2. In what order does full_clean() run its validation steps?
3. Why does form validation via ModelForm appear to happen automatically while raw model saves don't validate?
4. Where should you put validation logic that depends on the values of two different fields together?
5. What is a key risk of using bulk_create() to insert model instances?
Was this page helpful?
You May Also Like
Defining Models
How to declare Django models as Python classes that map to database tables, including field types, options, and Meta configuration.
Django ORM QuerySets
How QuerySets let you retrieve, filter, and chain database queries lazily using Python instead of raw SQL.
Model Relationships
How ForeignKey, ManyToManyField, and OneToOneField model real-world relationships between Django models.
Migrations in Django
How Django's migration system tracks model changes over time and applies them safely to the database schema.
Related Reading
Related Study Notes in Web Development
Browse all study notesWebSockets Study Notes
Web Development · 30 topics
Web DevelopmentWebAssembly Study Notes
WebAssembly · 30 topics
Web DevelopmentgRPC Study Notes
Protocol Buffers · 30 topics
Web DevelopmentSpring Boot Study Notes
Java · 30 topics
Web DevelopmentFlask Study Notes
Python · 30 topics
Web DevelopmentNext.js Study Notes
JavaScript · 30 topics