CharField is a Django model field for short character data such as a musician’s first and last name. On a model, it does two jobs: it defines the database column’s stored type and provides the attribute used to read that value from queried objects. Unlike ordinary Python strings, whose length can be arbitrary, a CharField requires an explicit maximum length for the database column. section 4.2
Listing 4.2 Musician ORM Model class
# RiffMates/bands/models.py
from django.db import models
class Musician(models.Model):
first_name = models.CharField(max_length=50)
last_name = models.CharField(max_length=50)
birth = models.DateField()
A Musician model uses CharField for both names. Each declaration becomes a character-data column and an attribute such as first_name or last_name. section 4.2
Set max_length to a reasonable upper bound for the data rather than assuming names fit a narrow, familiar pattern. Names vary across cultures, and a limit that looks generous until it meets “Christopher” can still trim real data. CharField is the usual choice for bounded values like names; text fields without that limit exist, but their storage can be less efficient. section 4.2
Define names on a model
Use CharField declarations in models.py: from django.db import models class Musician(models.Model): first_name = models.CharField(max_length=50) last_name = models.CharField(max_length=50) birth = models.DateField() Here, the two name values are character fields, while birth uses a field that maps to a Python date object. After defining the model, migrations create the corresponding table. section 4.2 section 4.4
When creating model objects, supply CharField values as Python strings with keyword arguments. The generic .create() method inserts those values into the database and returns the corresponding model object. Required fields must be provided; a missing required value is reported when Django runs the underlying database statement, not by the Python compiler. section 4.4
Create a musician
A query creates a row using the CharField attribute names: steve = Musician.objects.create( first_name="Steve", last_name="Vai", birth=date(1960, 6, 6), ) The first_name and last_name arguments become stored character values. Querying later returns a Musician object whose attributes provide access to those values. A custom __str__() method can include last_name to make shell output easier to inspect while debugging. section 4.4
CharField is part of a family of text-oriented model fields. EmailField, URLField, and SlugField inherit from it and add validation suited to email addresses, URLs, and slug identifiers. Their default maximum lengths are 254, 200, and 50 respectively, and validation is usually performed at the model level unless the database supplies a specialized storage type. section 4.8.2
Choose TextField when the value is open-ended rather than bounded. Database implementations may store CharField and TextField identically or separately, but Django’s default interfaces distinguish them: CharField appears as a single-line entry widget, while TextField appears as a multiline widget. That presentation can be changed when needed. section 4.8.2
Common CharField decisions:
- Use it for bounded character values such as first and last names; provide max_length. section 4.2
- Use EmailField, URLField, or SlugField when their added validation matches the value being stored. section 4.8.2
- Use TextField for open-ended content, especially when a multiline form control fits the input. section 4.8.2
