This document explains all the possible metadata options that you can give your model in its internal
If a model exists outside of the standard
models.py(for instance, if the app’s models are in submodules of
myapp.models), the model must define which app it is part of:
app_label = 'myapp'
The name of the database table to use for the model:
db_table = 'music_album'
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
manage.py startapp – to the model’s
class name, with an underscore between them.
For example, if you have an app
bookstore (as created by
manage.py startapp bookstore), a model defined as
class Book will have
a database table named
To override the database table name, use the
db_table parameter in
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.
Use lowercase table names for MySQL
It is strongly advised that you use lowercase table names when you override
the table name via
db_table, particularly if you are using the MySQL
backend. See the MySQL notes for more details.
False, no database table creation or deletion operations will be performed for this model. This is useful if the model represents an existing table or a database view that has been created by some other means. This is the only difference when
managed=False. All other aspects of model handling are exactly the same as normal. This includes
Adding an automatic primary key field to the model if you don’t declare it. To avoid confusion for later code readers, it’s recommended to specify all the columns from the database table you are modeling when using unmanaged models.
If a model with
ManyToManyFieldthat points to another unmanaged model, then the intermediate table for the many-to-many join will also not be created. However, the intermediary table between one managed and one unmanaged model will be created.
If you need to change this default behavior, create the intermediary table as an explicit model (with
managedset as needed) and use the
ManyToManyField.throughattribute to make the relation use your custom model.
For tests involving models with
managed=False, it’s up to you to ensure the correct tables are created as part of the test setup.
If you’re interested in changing the Python-level behavior of a model class, you could use
managed=Falseand create a copy of an existing model. However, there’s a better approach for that situation: Proxy models.
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. For example, if an
Answerrelates to a
Questionobject, and a question has more than one answer, and the order of answers matters, you’d do this:
class Answer(models.Model): question = models.ForeignKey(Question) # ... class Meta: order_with_respect_to = 'question'
order_with_respect_tois set, two additional methods are provided to retrieve and to set the order of the related objects:
RELATEDis the lowercased model name. For example, assuming that a
Questionobject has multiple related
Answerobjects, the list returned contains the primary keys of the related
>>> question = Question.objects.get(id=1) >>> question.get_answer_order() [1, 2, 3]
The order of a
Answerobjects can be set by passing in a list of
>>> question.set_answer_order([3, 1, 2])
The related objects also get two methods,
get_previous_in_order(), which can be used to access those objects in their proper order. Assuming the
Answerobjects are ordered by
>>> answer = Answer.objects.get(id=2) >>> answer.get_next_in_order() <Answer: 3> >>> answer.get_previous_in_order() <Answer: 1>
order_with_respect_to adds an additional field/database column
_order, so be sure to handle that as you would any other
change to your models if you add or change
after your initial
The default ordering for the object, for use when obtaining lists of objects:
ordering = ['-order_date']
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.
For example, to order by a
pub_datefield ascending, use this:
ordering = ['pub_date']
To order by
pub_datedescending, use this:
ordering = ['-pub_date']
To order by
pub_datedescending, then by
authorascending, use this:
ordering = ['-pub_date', 'author']The Django admin honors all elements in the list/tuple; before 1.4, only the first one was respected.
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
adminset. This example specifies an extra permission,
permissions = (("can_deliver_pizzas", "Can deliver pizzas"),)
This is a list or tuple of 2-tuples in the format
Sets of field names that, taken together, must be unique:
unique_together = (("driver", "restaurant"),)
This is a tuple of tuples 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
UNIQUEstatements are included in the
For convenience, unique_together can be a single tuple when dealing with a single set of fields:
unique_together = ("driver", "restaurant")
ManyToManyFieldcannot be included in unique_together. (It’s not clear what that would even mean!) If you need to validate uniqueness related to a
ManyToManyField, try using a signal or an explicit
Sets of field names that, taken together, are indexed:
index_together = [ ["pub_date", "deadline"], ]
This list of fields will be indexed together (i.e. the appropriate
CREATE INDEXstatement will be issued.)
A human-readable name for the object, singular:
verbose_name = "pizza"
If this isn’t given, Django will use a munged version of the class name: