Arthur de Jong

Open Source / Free Software developer

summaryrefslogtreecommitdiffstats
path: root/docs/ref/models/options.txt
blob: 65fa8acfea24099c695727410bb592f99f6238ad (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
======================
Model ``Meta`` options
======================

This document explains all the possible :ref:`metadata options
<meta-options>` that you can give your model in its internal
``class Meta``.

Available ``Meta`` options
==========================

.. currentmodule:: django.db.models

``abstract``
------------

.. attribute:: Options.abstract

    If ``abstract = True``, this model will be an
    :ref:`abstract base class <abstract-base-classes>`.

``app_label``
-------------

.. attribute:: Options.app_label

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

        app_label = 'myapp'

    .. versionadded:: 1.9

    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.

``db_table``
------------

.. attribute:: Options.db_table

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

        db_table = 'music_album'

.. _table-names:

Table names
~~~~~~~~~~~

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 :djadmin:`manage.py startapp <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 ``bookstore_book``.

To override the database table name, use the ``db_table`` parameter in
``class Meta``.

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.

.. admonition:: 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 :ref:`MySQL notes <mysql-notes>` for more details.

.. admonition:: Table name quoting for Oracle

   In order to meet the 30-char limitation Oracle has on table names,
   and match the usual conventions for Oracle databases, Django may shorten
   table names and turn them all-uppercase. To prevent such transformations,
   use a quoted name as the value for ``db_table``::

       db_table = '"name_left_in_lowercase"'

   Such quoted names can also be used with Django's other supported database
   backends; except for Oracle, however, the quotes have no effect. See the
   :ref:`Oracle notes <oracle-notes>` for more details.

``db_tablespace``
-----------------

.. attribute:: Options.db_tablespace

    The name of the :doc:`database tablespace </topics/db/tablespaces>` to use
    for this model. The default is the project's :setting:`DEFAULT_TABLESPACE`
    setting, if set. If the backend doesn't support tablespaces, this option is
    ignored.

``default_related_name``
------------------------

.. attribute:: Options.default_related_name

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

    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
    :ref:`related names for abstract models <abstract-related-name>`.

``get_latest_by``
-----------------

.. attribute:: Options.get_latest_by

    The name of an orderable field in the model, typically a :class:`DateField`,
    :class:`DateTimeField`, or :class:`IntegerField`. This specifies the default
    field to use in your model :class:`Manager`’s
    :meth:`~django.db.models.query.QuerySet.latest` and
    :meth:`~django.db.models.query.QuerySet.earliest` methods.

    Example::

        get_latest_by = "order_date"

    See the :meth:`~django.db.models.query.QuerySet.latest` docs for more.

``managed``
-----------

.. attribute:: Options.managed

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

    If ``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

    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
       :class:`~django.db.models.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 :attr:`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: :ref:`proxy-models`.

``order_with_respect_to``
-------------------------

.. attribute:: Options.order_with_respect_to

    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>

.. admonition:: ``order_with_respect_to`` implicitly sets the ``ordering`` option

    Internally, ``order_with_respect_to`` adds an additional field/database
    column named ``_order`` and sets the model's :attr:`~Options.ordering`
    option to this field. Consequently, ``order_with_respect_to`` and
    ``ordering`` cannot be used together, and the ordering added by
    ``order_with_respect_to`` will apply whenever you obtain a list of objects
    of this model.

.. admonition:: Changing ``order_with_respect_to``

    Because ``order_with_respect_to`` adds a new database column, be sure to
    make and apply the appropriate migrations if you add or change
    ``order_with_respect_to`` after your initial :djadmin:`migrate`.

``ordering``
------------

.. attribute:: Options.ordering

    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_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']

.. warning::

    Ordering is not a free operation. Each field you add to the ordering
    incurs a cost to your database. Each foreign key you add will
    implicitly include all of its default orderings as well.

``permissions``
---------------

.. attribute:: Options.permissions

    Extra permissions to enter into the permissions table when creating this object.
    Add, delete and change 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)``.

``default_permissions``
------------------------------

.. attribute:: Options.default_permissions

    Defaults to ``('add', 'change', 'delete')``. 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 :djadmin:`migrate` in order to prevent any omitted
    permissions from being created.

``proxy``
---------

.. attribute:: Options.proxy

    If ``proxy = True``, a model which subclasses another model will be treated as
    a :ref:`proxy model <proxy-models>`.

``required_db_features``
------------------------

.. attribute:: Options.required_db_features

    .. versionadded:: 1.9

    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.

``required_db_vendor``
----------------------

.. attribute:: Options.required_db_vendor

    .. versionadded:: 1.9

    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.

``select_on_save``
------------------

.. attribute:: Options.select_on_save

    Determines if Django will use the pre-1.6
    :meth:`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 :meth:`django.db.models.Model.save()` for more about the old and
    new saving algorithm.

``unique_together``
-------------------

.. attribute:: Options.unique_together

    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 ``UNIQUE`` statements are included in the ``CREATE TABLE``
    statement).

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

        unique_together = ("driver", "restaurant")

    A :class:`~django.db.models.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
    :class:`~django.db.models.ManyToManyField`, try using a signal or
    an explicit :attr:`through <ManyToManyField.through>` model.

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

``index_together``
------------------

.. attribute:: Options.index_together

    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"]

``verbose_name``
----------------

.. attribute:: Options.verbose_name

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

``verbose_name_plural``
-----------------------

.. attribute:: Options.verbose_name_plural

    The plural name for the object::

        verbose_name_plural = "stories"

    If this isn't given, Django will use :attr:`~Options.verbose_name` + ``"s"``.

Read-only ``Meta`` attributes
=============================

``label``
---------

.. attribute:: Options.label

    .. versionadded:: 1.9

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

``label_lower``
---------------

.. attribute:: Options.label_lower

    .. versionadded:: 1.9

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