| 1 |
.. _fixtures-explanation: |
| 2 |
|
| 3 |
======== |
| 4 |
Fixtures |
| 5 |
======== |
| 6 |
|
| 7 |
A *fixture* is a collection of files that contain the serialized contents of |
| 8 |
the database. Each fixture has a unique name, and the files that comprise the |
| 9 |
fixture can be distributed over multiple directories, in multiple applications. |
| 10 |
|
| 11 |
.. seealso:: |
| 12 |
|
| 13 |
* :doc:`/howto/initial-data` |
| 14 |
|
| 15 |
How to produce a fixture |
| 16 |
======================== |
| 17 |
|
| 18 |
Fixtures can be generated by :djadmin:`manage.py dumpdata <dumpdata>`. It's |
| 19 |
also possible to generate custom fixtures by directly using :doc:`serialization |
| 20 |
tools </topics/serialization>` or even by handwriting them. |
| 21 |
|
| 22 |
How to use a fixture |
| 23 |
==================== |
| 24 |
|
| 25 |
Fixtures can be used to pre-populate the database with data for |
| 26 |
:ref:`tests <topics-testing-fixtures>`: |
| 27 |
|
| 28 |
.. code-block:: python |
| 29 |
|
| 30 |
class MyTestCase(TestCase): |
| 31 |
fixtures = ["fixture-label"] |
| 32 |
|
| 33 |
or to provide some :ref:`initial data <initial-data-via-fixtures>` using the |
| 34 |
:djadmin:`loaddata` command: |
| 35 |
|
| 36 |
.. code-block:: shell |
| 37 |
|
| 38 |
django-admin loaddata <fixture label> |
| 39 |
|
| 40 |
How fixtures are discovered |
| 41 |
=========================== |
| 42 |
|
| 43 |
Django will search in these locations for fixtures: |
| 44 |
|
| 45 |
1. In the ``fixtures`` directory of every installed application |
| 46 |
2. In any directory listed in the :setting:`FIXTURE_DIRS` setting |
| 47 |
3. In the literal path named by the fixture |
| 48 |
|
| 49 |
Django will load any and all fixtures it finds in these locations that match |
| 50 |
the provided fixture names. If the named fixture has a file extension, only |
| 51 |
fixtures of that type will be loaded. For example: |
| 52 |
|
| 53 |
.. code-block:: shell |
| 54 |
|
| 55 |
django-admin loaddata mydata.json |
| 56 |
|
| 57 |
would only load JSON fixtures called ``mydata``. The fixture extension must |
| 58 |
correspond to the registered name of a |
| 59 |
:ref:`serializer <serialization-formats>` (e.g., ``json`` or ``xml``). |
| 60 |
|
| 61 |
If you omit the extensions, Django will search all available fixture types for |
| 62 |
a matching fixture. For example: |
| 63 |
|
| 64 |
.. code-block:: shell |
| 65 |
|
| 66 |
django-admin loaddata mydata |
| 67 |
|
| 68 |
would look for any fixture of any fixture type called ``mydata``. If a fixture |
| 69 |
directory contained ``mydata.json``, that fixture would be loaded as a JSON |
| 70 |
fixture. |
| 71 |
|
| 72 |
The fixtures that are named can include directory components. These directories |
| 73 |
will be included in the search path. For example: |
| 74 |
|
| 75 |
.. code-block:: shell |
| 76 |
|
| 77 |
django-admin loaddata foo/bar/mydata.json |
| 78 |
|
| 79 |
would search ``<app_label>/fixtures/foo/bar/mydata.json`` for each installed |
| 80 |
application, ``<dirname>/foo/bar/mydata.json`` for each directory in |
| 81 |
:setting:`FIXTURE_DIRS`, and the literal path ``foo/bar/mydata.json``. |
| 82 |
|
| 83 |
Fixtures loading order |
| 84 |
---------------------- |
| 85 |
|
| 86 |
Multiple fixtures can be specified in the same invocation. For example: |
| 87 |
|
| 88 |
.. code-block:: shell |
| 89 |
|
| 90 |
django-admin loaddata mammals birds insects |
| 91 |
|
| 92 |
or in a test case class: |
| 93 |
|
| 94 |
.. code-block:: python |
| 95 |
|
| 96 |
class AnimalTestCase(TestCase): |
| 97 |
fixtures = ["mammals", "birds", "insects"] |
| 98 |
|
| 99 |
The order in which fixtures are loaded follows the order in which they are |
| 100 |
listed, whether it's when using the management command or when listing them in |
| 101 |
the test case class as shown above. |
| 102 |
|
| 103 |
In these examples, all the fixtures named ``mammals`` from all applications (in |
| 104 |
the order in which applications are defined in :setting:`INSTALLED_APPS`) will |
| 105 |
be loaded first. Subsequently, all the ``birds`` fixtures will be loaded, |
| 106 |
followed by all the ``insects`` fixtures. |
| 107 |
|
| 108 |
Be aware that if the database backend supports row-level constraints, these |
| 109 |
constraints will be checked at the end of the transaction. Any relationships |
| 110 |
across fixtures may result in a load error if the database configuration does |
| 111 |
not support deferred constraint checking (refer to the `MySQL`_ docs for an |
| 112 |
example). |
| 113 |
|
| 114 |
.. _MySQL: https://dev.mysql.com/doc/refman/en/constraint-foreign-key.html |
| 115 |
|
| 116 |
How fixtures are saved to the database |
| 117 |
====================================== |
| 118 |
|
| 119 |
When fixture files are processed, the data is saved to the database as is. |
| 120 |
Model defined :meth:`~django.db.models.Model.save` methods are not called, and |
| 121 |
any :data:`~django.db.models.signals.pre_save` or |
| 122 |
:data:`~django.db.models.signals.post_save` signals will be called with |
| 123 |
``raw=True`` since the instance only contains attributes that are local to the |
| 124 |
model. You may, for example, want to disable handlers that access |
| 125 |
related fields that aren't present during fixture loading and would otherwise |
| 126 |
raise an exception:: |
| 127 |
|
| 128 |
from django.db.models.signals import post_save |
| 129 |
from .models import MyModel |
| 130 |
|
| 131 |
|
| 132 |
def my_handler(**kwargs): |
| 133 |
# disable the handler during fixture loading |
| 134 |
if kwargs["raw"]: |
| 135 |
return |
| 136 |
... |
| 137 |
|
| 138 |
|
| 139 |
post_save.connect(my_handler, sender=MyModel) |
| 140 |
|
| 141 |
You could also write a decorator to encapsulate this logic:: |
| 142 |
|
| 143 |
from functools import wraps |
| 144 |
|
| 145 |
|
| 146 |
def disable_for_loaddata(signal_handler): |
| 147 |
""" |
| 148 |
Decorator that turns off signal handlers when loading fixture data. |
| 149 |
""" |
| 150 |
|
| 151 |
@wraps(signal_handler) |
| 152 |
def wrapper(*args, **kwargs): |
| 153 |
if kwargs["raw"]: |
| 154 |
return |
| 155 |
signal_handler(*args, **kwargs) |
| 156 |
|
| 157 |
return wrapper |
| 158 |
|
| 159 |
|
| 160 |
@disable_for_loaddata |
| 161 |
def my_handler(**kwargs): ... |
| 162 |
|
| 163 |
Just be aware that this logic will disable the signals whenever fixtures are |
| 164 |
deserialized, not just during :djadmin:`loaddata`. |
| 165 |
|
| 166 |
Compressed fixtures |
| 167 |
=================== |
| 168 |
|
| 169 |
Fixtures may be compressed in ``zip``, ``gz``, ``bz2``, ``lzma``, or ``xz`` |
| 170 |
format. For example: |
| 171 |
|
| 172 |
.. code-block:: shell |
| 173 |
|
| 174 |
django-admin loaddata mydata.json |
| 175 |
|
| 176 |
would look for any of ``mydata.json``, ``mydata.json.zip``, ``mydata.json.gz``, |
| 177 |
``mydata.json.bz2``, ``mydata.json.lzma``, or ``mydata.json.xz``. The first |
| 178 |
file contained within a compressed archive is used. |
| 179 |
|
| 180 |
Note that if two fixtures with the same name but different fixture type are |
| 181 |
discovered (for example, if ``mydata.json`` and ``mydata.xml.gz`` were found in |
| 182 |
the same fixture directory), fixture installation will be aborted, and any data |
| 183 |
installed in the call to :djadmin:`loaddata` will be removed from the database. |
| 184 |
|
| 185 |
.. admonition:: MySQL with MyISAM and fixtures |
| 186 |
|
| 187 |
The MyISAM storage engine of MySQL doesn't support transactions or |
| 188 |
constraints, so if you use MyISAM, you won't get validation of fixture |
| 189 |
data, or a rollback if multiple transaction files are found. |
| 190 |
|
| 191 |
Database-specific fixtures |
| 192 |
========================== |
| 193 |
|
| 194 |
If you're in a multi-database setup, you might have fixture data that |
| 195 |
you want to load onto one database, but not onto another. In this |
| 196 |
situation, you can add a database identifier into the names of your fixtures. |
| 197 |
|
| 198 |
For example, if your :setting:`DATABASES` setting has a ``users`` database |
| 199 |
defined, name the fixture ``mydata.users.json`` or |
| 200 |
``mydata.users.json.gz`` and the fixture will only be loaded when you |
| 201 |
specify you want to load data into the ``users`` database. |