===============

Model reference

===============

A model is the single, definitive source of data 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 ``django.db.models.Model``.

    * Each attribute of the model represents a database field.

    * Model metadata (non-field information) goes in an inner class named

      ``Meta``.

    * Metadata used for Django's admin site goes into an inner class named

      ``Admin``.

    * With all of this, Django gives you an automatically-generated

      database-access API, which is explained in the `Database API reference`_.

A companion to this document is the `official repository of model examples`_.

(In the Django source distribution, these examples are in the

``tests/modeltests`` directory.)

.. _Database API reference: http://www.djangoproject.com/documentation/db_api/

.. _official repository of model examples: http://www.djangoproject.com/documentation/models/

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(maxlength=30)

        last_name = models.CharField(maxlength=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::

    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 _`Table names` below.

    * An ``id`` field is added automatically, but this behavior can be

      overriden. See `Automatic primary key fields`_ below.

    * 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 `settings file`_.

.. _settings file: http://www.djangoproject.com/documentation/settings/

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.

Example::

    class Musician(models.Model):

        first_name = models.CharField(maxlength=50)

        last_name = models.CharField(maxlength=50)

        instrument = models.CharField(maxlength=100)

    class Album(models.Model):

        artist = models.ForeignKey(Musician)

        name = models.CharField(maxlength=100)

        release_date = models.DateField()

        num_stars = models.IntegerField()

Field name restrictions

-----------------------

Django places only two restrictions on model field names:

    1. A field name cannot be a Python reserved word, because that would result

       in a Python syntax error. For example::

           class Example(models.Model):

               pass = models.IntegerField() # 'pass' is a reserved word!

    2. A field name cannot contain more than one underscore in a row, due to

       the way Django's query lookup syntax works. For example::

           class Example(models.Model):

               foo__bar = models.IntegerField() # 'foo__bar' has two underscores!

These limitations can be worked around, though, because your field name doesn't

necessarily have to match your database column name. See `db_column`_ below.

SQL reserved words, such as ``join``, ``where`` or ``select``, *are* allowed as

model field names, because Django escapes all database table names and column

names in every underlying SQL query. It uses the quoting syntax of your

particular database engine.

Field types

-----------

Each field in your model should be an instance of the appropriate ``Field``

class. Django uses the field class types to determine a few things:

    * The database column type (e.g. ``INTEGER``, ``VARCHAR``).

    * The widget to use in Django's admin interface, if you care to use it

      (e.g. ``<input type="text">``, ``<select>``).

    * The minimal validation requirements, used in Django's admin and in

      manipulators.

Here are all available field types:

``AutoField``

~~~~~~~~~~~~~

An ``IntegerField`` that automatically increments according to available IDs.

You usually won't need to use this directly; a primary key field will

automatically be added to your model if you don't specify otherwise. See

`Automatic primary key fields`_.

``BooleanField``

~~~~~~~~~~~~~~~~

A true/false field.

The admin represents this as a checkbox.

``CharField``

~~~~~~~~~~~~~

A string field, for small- to large-sized strings.

For large amounts of text, use ``TextField``.

The admin represents this as an ``<input type="text">`` (a single-line input).

``CharField`` has an extra required argument, ``maxlength``, the maximum length

(in characters) of the field. The maxlength is enforced at the database level

and in Django's validation.

``CommaSeparatedIntegerField``

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

A field of integers separated by commas. As in ``CharField``, the ``maxlength``

argument is required.

``DateField``

~~~~~~~~~~~~~

A date field. Has a few extra optional arguments:

    ======================  ===================================================

    Argument                Description

    ======================  ===================================================

    ``auto_now``            Automatically set the field to now every time the

                            object is saved. Useful for "last-modified"

                            timestamps. Note that the current date is *always*

                            used; it's not just a default value that you can

                            override.

    ``auto_now_add``        Automatically set the field to now when the object

                            is first created. Useful for creation of

                            timestamps. Note that the current date is *always*

                            used; it's not just a default value that you can

                            override.

    ======================  ===================================================

The admin represents this as an ``<input type="text">`` with a JavaScript

calendar and a shortcut for "Today."

``DateTimeField``

~~~~~~~~~~~~~~~~~

A date and time field. Takes the same extra options as ``DateField``.

The admin represents this as two ``<input type="text">`` fields, with

JavaScript shortcuts.

``EmailField``

~~~~~~~~~~~~~~

A ``CharField`` that checks that the value is a valid e-mail address.

This doesn't accept ``maxlength``; its ``maxlength`` is automatically set to

75.

``FileField``

~~~~~~~~~~~~~

A file-upload field.

Has an extra required argument, ``upload_to``, a local filesystem path to

which files should be upload. This path may contain `strftime formatting`_,

which will be replaced by the date/time of the file upload (so that

uploaded files don't fill up the given directory).

The admin represents this as an ``<input type="file">`` (a file-upload widget).

Using a ``FileField`` or an ``ImageField`` (see below) in a model takes a few

steps:

    1. In your settings file, you'll need to define ``MEDIA_ROOT`` as the

       full path to a directory where you'd like Django to store uploaded

       files. (For performance, these files are not stored in the database.)

       Define ``MEDIA_URL`` as the base public URL of that directory. Make

       sure that this directory is writable by the Web server's user

       account.

    2. Add the ``FileField`` or ``ImageField`` to your model, making sure

       to define the ``upload_to`` option to tell Django to which

       subdirectory of ``MEDIA_ROOT`` it should upload files.

    3. All that will be stored in your database is a path to the file

       (relative to ``MEDIA_ROOT``). You'll most likely want to use the

       convenience ``get_<fieldname>_url`` function provided by Django. For

       example, if your ``ImageField`` is called ``mug_shot``, you can get

       the absolute URL to your image in a template with ``{{

       object.get_mug_shot_url }}``.

For example, say your ``MEDIA_ROOT`` is set to ``'/home/media'``, and

``upload_to`` is set to ``'photos/%Y/%m/%d'``. The ``'%Y/%m/%d'`` part of

``upload_to`` is strftime formatting; ``'%Y'`` is the four-digit year,

``'%m'`` is the two-digit month and ``'%d'`` is the two-digit day. If you

upload a file on Jan. 15, 2007, it will be saved in the directory

``/home/media/photos/2007/01/15``.

Note that whenever you deal with uploaded files, you should pay close attention

to where you're uploading them and what type of files they are, to avoid

security holes. *Validate all uploaded files* so that you're sure the files are

what you think they are. For example, if you blindly let somebody upload files,

without validation, to a directory that's within your Web server's document

root, then somebody could upload a CGI or PHP script and execute that script by

visiting its URL on your site. Don't allow that.

.. _`strftime formatting`: http://docs.python.org/lib/module-time.html#l2h-1941

``FilePathField``

~~~~~~~~~~~~~~~~~

A field whose choices are limited to the filenames in a certain directory

on the filesystem. Has three special arguments, of which the first is

required:

    ======================  ===================================================

    Argument                Description

    ======================  ===================================================

    ``path``                Required. The absolute filesystem path to a

                            directory from which this ``FilePathField`` should

                            get its choices. Example: ``"/home/images"``.

    ``match``               Optional. A regular expression, as a string, that

                            ``FilePathField`` will use to filter filenames.

                            Note that the regex will be applied to the

                            base filename, not the full path. Example:

                            ``"foo.*\.txt^"``, which will match a file called

                            ``foo23.txt`` but not ``bar.txt`` or ``foo23.gif``.

    ``recursive``           Optional. Either ``True`` or ``False``. Default is

                            ``False``. Specifies whether all subdirectories of

                            ``path`` should be included.

    ======================  ===================================================

Of course, these arguments can be used together.

The one potential gotcha is that ``match`` applies to the base filename,

not the full path. So, this example::

    FilePathField(path="/home/images", match="foo.*", recursive=True)

...will match ``/home/images/foo.gif`` but not ``/home/images/foo/bar.gif``

because the ``match`` applies to the base filename (``foo.gif`` and

``bar.gif``).

``FloatField``

~~~~~~~~~~~~~~

A floating-point number. Has two **required** arguments:

    ======================  ===================================================

    Argument                Description

    ======================  ===================================================

    ``max_digits``          The maximum number of digits allowed in the number.

    ``decimal_places``      The number of decimal places to store with the

                            number.

    ======================  ===================================================

For example, to store numbers up to 999 with a resolution of 2 decimal places,

you'd use::

    models.FloatField(..., max_digits=5, decimal_places=2)

And to store numbers up to approximately one billion with a resolution of 10

decimal places::

    models.FloatField(..., max_digits=19, decimal_places=10)

The admin represents this as an ``<input type="text">`` (a single-line input).

``ImageField``

~~~~~~~~~~~~~~

Like ``FileField``, but validates that the uploaded object is a valid

image. Has two extra optional arguments, ``height_field`` and

``width_field``, which, if set, will be auto-populated with the height and

width of the image each time a model instance is saved.

Requires the `Python Imaging Library`_.

.. _Python Imaging Library: http://www.pythonware.com/products/pil/

``IntegerField``

~~~~~~~~~~~~~~~~

An integer.

The admin represents this as an ``<input type="text">`` (a single-line input).

``IPAddressField``

~~~~~~~~~~~~~~~~~~

An IP address, in string format (i.e. "24.124.1.30").

The admin represents this as an ``<input type="text">`` (a single-line input).

``NullBooleanField``

~~~~~~~~~~~~~~~~~~~~

Like a ``BooleanField``, but allows ``NULL`` as one of the options.  Use this

instead of a ``BooleanField`` with ``null=True``.

The admin represents this as a ``<select>`` box with "Unknown", "Yes" and "No" choices.

``PhoneNumberField``

~~~~~~~~~~~~~~~~~~~~

A ``CharField`` that checks that the value is a valid U.S.A.-style phone

number (in the format ``XXX-XXX-XXXX``).

``PositiveIntegerField``

~~~~~~~~~~~~~~~~~~~~~~~~

Like an ``IntegerField``, but must be positive.

``PositiveSmallIntegerField``

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Like a ``PositiveIntegerField``, but only allows values under a certain

(database-dependent) point.

``SlugField``

~~~~~~~~~~~~~

"Slug" is a newspaper term. 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 ``maxlength``. If ``maxlength`` is

not specified, Django will use a default length of 50.

Implies ``db_index=True``.

Accepts an extra option, ``prepopulate_from``, which is a list of fields

from which to auto-populate the slug, via JavaScript, in the object's admin

form::

    models.SlugField(prepopulate_from=("pre_name", "name"))

``prepopulate_from`` doesn't accept DateTimeFields.

The admin represents ``SlugField`` as an ``<input type="text">`` (a

single-line input).

``SmallIntegerField``

~~~~~~~~~~~~~~~~~~~~~

Like an ``IntegerField``, but only allows values under a certain

(database-dependent) point.

``TextField``

~~~~~~~~~~~~~

A large text field.

The admin represents this as a ``<textarea>`` (a multi-line input).

``TimeField``

~~~~~~~~~~~~~

A time. Accepts the same auto-population options as ``DateField`` and

``DateTimeField``.

The admin represents this as an ``<input type="text">`` with some

JavaScript shortcuts.

``URLField``

~~~~~~~~~~~~

A field for a URL. If the ``verify_exists`` option is ``True`` (default),

the URL given will be checked for existence (i.e., the URL actually loads

and doesn't give a 404 response).

The admin represents this as an ``<input type="text">`` (a single-line input).

``USStateField``

~~~~~~~~~~~~~~~~

A two-letter U.S. state abbreviation.

The admin represents this as an ``<input type="text">`` (a single-line input).

``XMLField``

~~~~~~~~~~~~

A ``TextField`` that checks that the value is valid XML that matches a

given schema. Takes one required argument, ``schema_path``, which is the

filesystem path to a RelaxNG_ schema against which to validate the field.

.. _RelaxNG: http://www.relaxng.org/

Field options

-------------

The following arguments are available to all field types. All are optional.

``null``

~~~~~~~~

If ``True``, Django will store empty values as ``NULL`` in the database.

Default is ``False``.

Note that empty string values will always get stored as empty strings, not

as ``NULL`` -- so use ``null=True`` for non-string fields such as integers,

booleans and dates.

Avoid using ``null`` on string-based fields such as ``CharField`` and

``TextField`` unless you have an excellent reason. If a string-based field

has ``null=True``, that means it has two possible values for "no data":

``NULL``, and the empty string. In most cases, it's redundant to have two

possible values for "no data;" Django convention is to use the empty

string, not ``NULL``.

``blank``

~~~~~~~~~

If ``True``, the field is allowed to be blank.

Note that this is different than ``null``. ``null`` is purely

database-related, whereas ``blank`` is validation-related. If a field has

``blank=True``, validation on Django's admin site will allow entry of an

empty value. If a field has ``blank=False``, the field will be required.

``choices``

~~~~~~~~~~~

An iterable (e.g., a list or tuple) of 2-tuples to use as choices for this

field.

If this is given, Django's admin will use a select box instead of the

standard text field and will limit choices to the choices given.

A choices list looks like this::

    YEAR_IN_SCHOOL_CHOICES = (

        ('FR', 'Freshman'),

        ('SO', 'Sophomore'),

        ('JR', 'Junior'),

        ('SR', 'Senior'),

        ('GR', 'Graduate'),

    )

The first element in each tuple is the actual value to be stored. The

second element is the human-readable name for the option.

The choices list can be defined either as part of your model class::

    class Foo(models.Model):

        GENDER_CHOICES = (

            ('M', 'Male'),

            ('F', 'Female'),

        )

        gender = models.CharField(maxlength=1, choices=GENDER_CHOICES)

or outside your model class altogether::

    GENDER_CHOICES = (

        ('M', 'Male'),

        ('F', 'Female'),

    )

    class Foo(models.Model):

        gender = models.CharField(maxlength=1, choices=GENDER_CHOICES)

For each model field that has ``choices`` set, Django will add a method to

retrieve the human-readable name for the field's current value. See

`get_FOO_display`_ in the database API documentation.

.. _get_FOO_display: ../db_api/#get-foo-display

Finally, note that choices can be any iterable object -- not necessarily a

list or tuple. This lets you construct choices dynamically. But if you find

yourself hacking ``choices`` to be dynamic, you're probably better off using

a proper database table with a ``ForeignKey``. ``choices`` is meant for static

data that doesn't change much, if ever.

``core``

~~~~~~~~

For objects that are edited inline to a related object.

In the Django admin, if all "core" fields in an inline-edited object are

cleared, the object will be deleted.

It is an error to have an inline-editable relation without at least one

``core=True`` field.

Please note that each field marked "core" is treated as a required field by the

Django admin site. Essentially, this means you should put ``core=True`` on all

required fields in your related object that is being edited inline.

``db_column``

~~~~~~~~~~~~~