Django Models


Each model is a Python class that subclasses django.db.models.Model.

Each attribute of the model represents a database field.

The MTV (or MVC) Development Pattern

  • Model: Refers to the data access layer. This is handled by Django's database layer.
  • View: Refers to the part of he system that selects what to display and how to display it. This is handled by views and templates.
  • Controller: Refers to the port of the system that decides which view to use, depending on user input, accessing the model as needed. This is handled by the framework itself by following your URLconf and calling the appropriate Python function for the given URL.

Django has been referred to as an MTV framework. In the MTV development pattern,

  • M stands for Model, the data access layer. This layer contains anything and everything about the data: how to access it, how to validate it, which behaviors it has, and the relationships between the data.
    • T stands for Template, the presentation layer. This layer contains presentation-related decisions: how something should be displayed on a Web page or other type of document.
    • V stands for View, the business logic layer. This layer contains the logic that access the model and defers to the appropriate template(s).

Configuring the Database

Database configuration is in

Defining Models in Python

A Django model is a description of the data in your database, represented as Python code.


  • An author has a first name, a last name and an email address.
  • A publisher has a name, a street address, a city, a state/province, a country, and a Web site.
  • A book has a title and a publication date. It also has one or more authors (a many-to-many relationship with authors) and a single publisher (a one-to-many relationship — aka foreign key — to publishers).
from django.db import models
class Publisher(models.Model):
    name = models.CharField(max_length=30)
    address = models.CharField(max_length=50, null=True) #    If True, Django will store empty values as NULL in the database. Default is False.
    city = models.CharField(max_length=60)
    state_province = models.CharField(max_length=30)
    country = models.CharField(max_length=50)
    website = models.URLField()
class Author(models.Model):
    first_name = models.CharField(max_length=30)
    last_name = models.CharField(max_length=40)
    email = models.EmailField()
class Book(models.Model):
    title = models.CharField(max_length=100)
    authors = models.ManyToManyField(Author)
    publisher = models.ForeignKey(Publisher)
    publication_date = models.DateField()
  • We haven’t explicitly defined a primary key in any of these models. Unless you instruct it otherwise, Django automatically gives every model an auto-incrementing integer primary key field called id. Each Django model is required to have a single-column primary key.

Installing the Model

  • First, we have to activate these models in our Django project. This is done by adding the books app to the list of installed apps in the settings file. Add the following lines:
    # 'django.contrib.auth',
    # 'django.contrib.contenttypes',
    # 'django.contrib.sessions',
    # 'django.contrib.sites',

Then you have to run python syncdb to create the new tables. model specific commands

  • python validate: To validate the models
  • python sqlall books To generate the CREATE TABLE statements. The sqlall command doesn’t actually create the tables. It just prints output to the screen so you can see what SQL Django would execute if you asked it.
  • python syncdb: To commit the SQL to the database.


Django offers ways to define the three most common types of database relationships: many-to-one, many-to-many and one-to-one.

Many-to-one relationships

Example: A Manufacturer makes multiple cars but each Car only has one Manufacturer.

class Manufacturer(models.Model):
    # ...
class Car(models.Model):
    manufacturer = models.ForeignKey(Manufacturer)
    # ...

Many-to-many relationships

Example: A Topping can be on multiple pizzas and each Pizza has multiple toppings.

class Topping(models.Model):
    # ...
class Pizza(models.Model):
    # ...
    toppings = models.ManyToManyField(Topping)

It doesn't matter which model gets the ManyToManyField, but you only need it in one of the models — not in both.

One-to-one relationships

Example: if you were building a database of "places", you would build pretty standard stuff such as address, phone number, etc. in the database. Then, if you wanted to build a database of restaurants on top of the places, instead of repeating yourself and replicating those fields in the Restaurant model, you could make Restaurant have a OneToOneField to Place.

class Place(models.Model):
    name = models.CharField(max_length=50)
    address = models.CharField(max_length=80)
class Restaurant(models.Model):
    place = models.OneToOneField(Place, primary_key=True)
    serves_hot_dogs = models.BooleanField()
    serves_pizza = models.BooleanField()

Django API model commands

>>> from books.models import Publisher
>>> p1 = Publisher(name='Apress', address='2855 Telegraph Avenue',
...     city='Berkeley', state_province='CA', country='U.S.A.',
...     website='')
#Save the object into the database. You have to call save() explicitly.
>>> p2 = Publisher(name="O'Reilly", address='10 Fawcett St.',
...     city='Cambridge', state_province='MA', country='U.S.A.',
...     website='')
>>> publisher_list = Publisher.objects.all()
>>> publisher_list
[<Publisher: Publisher object>, <Publisher: Publisher object>]
# New objects get an id by default
# Access database columns via Python attributes.
>>> p2.address
# Change values by changing the attributes, then calling save().
>>> = ''

Model Methods

Define custom methods on a model to add custom "row-level" functionality to your objects.


str() is a Python "magic method" that defines what should be returned if you call str() on the object. Django uses str(obj) in a number of places, most notably as the value displayed to render an object in the Django admin site and as the value inserted into a template when it displays an object.


The unicode() method is called whenever you call unicode() on an object. Since Django's database backends will return Unicode strings in your model's attributes, you would normally want to write a unicode() method for your model. It is recommended to define only unicode() and let Django take care of the conversion to string objects when required.


You can override this method if you want something to happen whenever you save an object.
Django Documentation about save


Issues a SQL DELETE for the object. This only deletes the object in the database
Django Documentation about delete

Model field reference

Field types

Django Field Types
Each field in your model should be an instance of the appropriate Field class.


A string field, for small- to large-sized strings. For large amounts of text, use TextField.

CharField has one extra required argument:

The maximum length (in characters) of the field. The max_length is enforced at the database level and in Django's validation.


An integer.


A large text field.


A date, represented in Python by a instance.

Has a few extra, optional arguments:

Automatically set the field to now every time the object is saved. Useful for "last-modified" timestamps.

Automatically set the field to now when the object is first created. Useful for creation of timestamps.


A slug is a short label for something, containing only letters, numbers, underscores or hyphens. They're generally used in URLs.

Like a CharField, you can specify max_length. If max_length is not specified, Django will use a default length of 50.


A many-to-one relationship. Requires a positional argument: the class to which the model is related.

To create a recursive relationship — an object that has a many-to-one relationship with itself — use models.ForeignKey('self')

Field options

Each field takes a certain set of field-specific arguments


The maximum length of a field.


If True, this field must be unique throughout the table.

Accessing Related objects

Example 1: The “other side” of a ForeignKey relation

class Reporter(models.Model):
class Article(models.Model):
    reporter = models.ForeignKey(Reporter)

In the above example, the methods below will be available on the manager reporter.article_set


Example 2:Both sides of a ManyToManyField relation:

class Topping(models.Model):
class Pizza(models.Model):
    toppings = models.ManyToManyField(Topping)

In the above example, the methods below will be available both on topping.pizza_set and on pizza.toppings.

QuerySet.add(obj1[, obj2, …])


QuerySet.remove(obj1[, obj2, …])


Model Meta options

Because you often need to provide extra meta-information about a model, Django lets you add an inner class, named Meta, which can specify a large number of common options.

Model metadata is "anything that's not a field".

A complete list of all possible Meta options can be found in the model option reference.


If True, this model will be an abstract base class.


If a model exists outside of the standard (for instance, if the app’s models are in submodules of myapp.models), the model must define which app it is part of.


The name of the database table to use for the model.

Table names

To save you time, Django automatically derives the name of the database table from the name of your model class and the app that contains it. A model's database table name is constructed by joining the model's "app label" — the name you used in startapp — to the model's class name, with an underscore between them.

For example, if you have an app bookstore (as created by startapp bookstore), a model defined as class Book will have a database table named bookstore_book.

To override the database table name, use the db_table parameter in class Meta.

If your database table name is an SQL reserved word, or contains characters that aren't allowed in Python variable names — notably, the hyphen — that's OK. Django quotes column and table names behind the scenes.


The name of the database tablespace to use for the model. If the backend doesn't support tablespaces, this option is ignored.


The name of a DateField or DateTimeField in the model. This specifies the default field to use in your model Manager's latest method.


Defaults to True, meaning Django will create the appropriate database tables in syncdb and remove them as part of a reset management command. That is, Django manages the database tables' lifecycles.


Marks this object as "orderable" with respect to the given field. This is almost always used with related objects to allow them to be ordered with respect to a parent object.


The default ordering for the object, for use when obtaining lists of objects.

This is a tuple or list of strings. Each string is a field name with an optional "-" prefix, which indicates descending order. Fields without a leading "-" will be ordered ascending. Use the string "?" to order randomly.


Extra permissions to enter into the permissions table when creating this object. Add, delete and change permissions are automatically created for each object that has admin set. This example specifies an extra permission, can_deliver_pizzas:


If set to True, a model which subclasses another model will be treated as a proxy model.


Sets of field names that, taken together, must be unique.
This is a list of lists of fields that must be unique when considered together. It's used in the Django admin and is enforced at the database level (i.e., the appropriate UNIQUE statements are included in the CREATE TABLE statement).


A human-readable name for the object, singular.

If this isn't given, Django will use a munged version of the class name: CamelCase becomes camel case.


The plural name for the object.

If this isn't given, Django will use verbose_name + "s".

Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-Share Alike 2.5 License.