Model Meta optionsLink to this heading#

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

If a model is defined outside of an application in INSTALLED_APPS, it must declare which app it belongs to:

app_label = 'myapp'

If you want to represent a model with the format app_label.object_name or app_label.model_name you can use model._meta.label or model._meta.label_lower respectively.

The attribute name of the manager, for example, 'objects', to use for the model’s _base_manager.

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

db_table = 'music_album'

The name of the database tablespace to use for this model. The default is the project’s DEFAULT_TABLESPACE setting, if set. If the backend doesn’t support tablespaces, this option is ignored.

The name of the manager to use for the model’s _default_manager.

The name that will be used by default for the relation from a related object back to this one. The default is <model_name>_set.

This option also sets related_query_name.

As the reverse name for a field should be unique, be careful if you intend to subclass your model. To work around name collisions, part of the name should contain '%(app_label)s' and '%(model_name)s', which are replaced respectively by the name of the application the model is in, and the name of the model, both lowercased. See the paragraph on related names for abstract models.

The name of a field or a list of field names in the model, typically DateField, DateTimeField, or IntegerField. This specifies the default field(s) to use in your model Manager’s latest() and earliest() methods.

Example:

# Latest by ascending order_date.
get_latest_by = "order_date"

# Latest by priority descending, order_date ascending.
get_latest_by = ['-priority', 'order_date']

See the latest() docs for more.

Defaults to True, meaning Django will create the appropriate database tables in migrate or as part of migrations and remove them as part of a flush management command. That is, Django manages the database tables” lifecycles.

If False, no database table creation, modification, 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

1. 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.

2. If a model with managed=False contains a ManyToManyField that 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 managed set as needed) and use the ManyToManyField.through attribute 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=False and create a copy of an existing model. However, there’s a better approach for that situation: Proxy models.

Makes this object orderable with respect to the given field, usually a ForeignKey. This can be used to make related objects orderable with respect to a parent object. For example, if an Answer relates to a Question object, and a question has more than one answer, and the order of answers matters, you’d do this:

from django.db import models

class Question(models.Model):
    text = models.TextField()
    # ...

class Answer(models.Model):
    question = models.ForeignKey(Question, on_delete=models.CASCADE)
    # ...

    class Meta:
        order_with_respect_to = 'question'

When order_with_respect_to is set, two additional methods are provided to retrieve and to set the order of the related objects: get_RELATED_order() and set_RELATED_order(), where RELATED is the lowercased model name. For example, assuming that a Question object has multiple related Answer objects, the list returned contains the primary keys of the related Answer objects:

>>> question = Question.objects.get(id=1)
>>> question.get_answer_order()
[1, 2, 3]

The order of a Question object’s related Answer objects can be set by passing in a list of Answer primary keys:

>>> question.set_answer_order([3, 1, 2])

The related objects also get two methods, get_next_in_order() and get_previous_in_order(), which can be used to access those objects in their proper order. Assuming the Answer objects are ordered by id:

>>> answer = Answer.objects.get(id=2)
>>> answer.get_next_in_order()
<Answer: 3>
>>> answer.get_previous_in_order()
<Answer: 1>

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

ordering = ['-order_date']

This is a tuple or list of strings and/or query expressions. 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_date field ascending, use this:

ordering = ['pub_date']

To order by pub_date descending, use this:

ordering = ['-pub_date']

To order by pub_date descending, then by author ascending, use this:

ordering = ['-pub_date', 'author']

You can also use query expressions. To order by author ascending and make null values sort last, use this:

from django.db.models import F

ordering = [F('author').asc(nulls_last=True)]

Default ordering also affects aggregation queries but this won’t be the case starting in Django 3.1.

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

permissions = [('can_deliver_pizzas', 'Can deliver pizzas')]

This is a list or tuple of 2-tuples in the format (permission_code, human_readable_permission_name).

Defaults to ('add', 'change', 'delete', 'view'). You may customize this list, for example, by setting this to an empty list if your app doesn’t require any of the default permissions. It must be specified on the model before the model is created by migrate in order to prevent any omitted permissions from being created.

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

List of database features that the current connection should have so that the model is considered during the migration phase. For example, if you set this list to ['gis_enabled'], the model will only be synchronized on GIS-enabled databases. It’s also useful to skip some models when testing with several database backends. Avoid relations between models that may or may not be created as the ORM doesn’t handle this.

Name of a supported database vendor that this model is specific to. Current built-in vendor names are: sqlite, postgresql, mysql, oracle. If this attribute is not empty and the current connection vendor doesn’t match it, the model will not be synchronized.

Determines if Django will use the pre-1.6 django.db.models.Model.save() algorithm. The old algorithm uses SELECT to determine if there is an existing row to be updated. The new algorithm tries an UPDATE directly. In some rare cases the UPDATE of an existing row isn’t visible to Django. An example is the PostgreSQL ON UPDATE trigger which returns NULL. In such cases the new algorithm will end up doing an INSERT even when a row exists in the database.

Usually there is no need to set this attribute. The default is False.

See django.db.models.Model.save() for more about the old and new saving algorithm.

A list of indexes that you want to define on the model:

from django.db import models

class Customer(models.Model):
    first_name = models.CharField(max_length=100)
    last_name = models.CharField(max_length=100)

    class Meta:
        indexes = [
            models.Index(fields=['last_name', 'first_name']),
            models.Index(fields=['first_name'], name='first_name_idx'),
        ]

Sets of field names that, taken together, must be unique:

unique_together = [['driver', 'restaurant']]

This is a list of lists 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).

For convenience, unique_together can be a single list when dealing with a single set of fields:

unique_together = ['driver', 'restaurant']

A ManyToManyField cannot 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 through model.

The ValidationError raised during model validation when the constraint is violated has the unique_together error code.

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 INDEX statement will be issued.)

For convenience, index_together can be a single list when dealing with a single set of fields:

index_together = ["pub_date", "deadline"]

A list of constraints that you want to define on the model:

from django.db import models

class Customer(models.Model):
    age = models.IntegerField()

    class Meta:
        constraints = [
            models.CheckConstraint(check=models.Q(age__gte=18), name='age_gte_18'),
        ]

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: CamelCase becomes camel case.

The plural name for the object:

verbose_name_plural = "stories"

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

Representation of the object, returns app_label.object_name, e.g. 'polls.Question'.

Representation of the model, returns app_label.model_name, e.g. 'polls.question'.