====== 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. ````, ``