Debian Codegraph @

docs/topics/db/fixtures.txt

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