======
Models
======
.. module:: django.db.models
A model is the single, definitive source of information about your data. It
contains the essential fields and behaviors of the data you're storing.
Generally, each model maps to a single database table.
The basics:
* Each model is a Python class that subclasses
:class:`django.db.models.Model`.
* Each attribute of the model represents a database field.
* With all of this, Django gives you an automatically-generated
database-access API; see :doc:`/topics/db/queries`.
Quick example
=============
This example model defines a ``Person``, which has a ``first_name`` and
``last_name``::
from django.db import models
class Person(models.Model):
first_name = models.CharField(max_length=30)
last_name = models.CharField(max_length=30)
``first_name`` and ``last_name`` are fields_ of the model. Each field is
specified as a class attribute, and each attribute maps to a database column.
The above ``Person`` model would create a database table like this:
.. code-block:: sql
CREATE TABLE myapp_person (
"id" serial NOT NULL PRIMARY KEY,
"first_name" varchar(30) NOT NULL,
"last_name" varchar(30) NOT NULL
);
Some technical notes:
* The name of the table, ``myapp_person``, is automatically derived from
some model metadata but can be overridden. See :ref:`table-names` for more
details.
* An ``id`` field is added automatically, but this behavior can be
overridden. See :ref:`automatic-primary-key-fields`.
* The ``CREATE TABLE`` SQL in this example is formatted using PostgreSQL
syntax, but it's worth noting Django uses SQL tailored to the database
backend specified in your :doc:`settings file `.
Using models
============
Once you have defined your models, you need to tell Django you're going to *use*
those models. Do this by editing your settings file and changing the
:setting:`INSTALLED_APPS` setting to add the name of the module that contains
your ``models.py``.
For example, if the models for your application live in the module
``myapp.models`` (the package structure that is created for an
application by the :djadmin:`manage.py startapp ` script),
:setting:`INSTALLED_APPS` should read, in part::
INSTALLED_APPS = [
#...
'myapp',
#...
]
When you add new apps to :setting:`INSTALLED_APPS`, be sure to run
:djadmin:`manage.py migrate `, optionally making migrations
for them first with :djadmin:`manage.py makemigrations `.
Fields
======
The most important part of a model -- and the only required part of a model --
is the list of database fields it defines. Fields are specified by class
attributes. Be careful not to choose field names that conflict with the
:doc:`models API ` like ``clean``, ``save``, or
``delete``.
Example::
from django.db import models
class Musician(models.Model):
first_name = models.CharField(max_length=50)
last_name = models.CharField(max_length=50)
instrument = models.CharField(max_length=100)
class Album(models.Model):
artist = models.ForeignKey(Musician, on_delete=models.CASCADE)
name = models.CharField(max_length=100)
release_date = models.DateField()
num_stars = models.IntegerField()
Field types
-----------
Each field in your model should be an instance of the appropriate
:class:`~django.db.models.Field` class. Django uses the field class types to
determine a few things:
* The column type, which tells the database what kind of data to store (e.g.
``INTEGER``, ``VARCHAR``, ``TEXT``).
* The default HTML :doc:`widget ` to use when rendering a form
field (e.g. ````, ``