mirror of https://github.com/django/django.git
[4.2.x] Fixed #15578 -- Stated the processing order of fixtures in the fixtures docs.
Also, added details about loading multiple fixtures and unified line wrapping
at 79 cols.
Co-Authored-By: Aniketh Babu <anikethbabu@gmail.com>
Co-Authored-by: Mariusz Felisiak <felisiak.mariusz@gmail.com>
Co-Authored-By: Natalia Bidart <124304+nessita@users.noreply.github.com>
Backport of 334dc073b1
from main
This commit is contained in:
parent
0cd8b867a0
commit
43a3646070
|
@ -19,62 +19,104 @@ How to produce a fixture?
|
|||
=========================
|
||||
|
||||
Fixtures can be generated by :djadmin:`manage.py dumpdata <dumpdata>`. It's
|
||||
also possible to generate custom fixtures by directly using
|
||||
:doc:`serialization documentation </topics/serialization>` tools or even by
|
||||
handwriting them.
|
||||
also possible to generate custom fixtures by directly using :doc:`serialization
|
||||
tools </topics/serialization>` or even by handwriting them.
|
||||
|
||||
What to use a fixture for?
|
||||
==========================
|
||||
How to use a fixture?
|
||||
=====================
|
||||
|
||||
Fixtures can be used to pre-populate database with data for
|
||||
:ref:`tests <topics-testing-fixtures>` or to provide some :ref:`initial data
|
||||
<initial-data-via-fixtures>`.
|
||||
:ref:`tests <topics-testing-fixtures>`:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
class MyTestCase(TestCase):
|
||||
fixtures = ["fixture-label"]
|
||||
|
||||
or to provide some :ref:`initial data <initial-data-via-fixtures>` using the
|
||||
:djadmin:`loaddata` command:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
django-admin loaddata <fixture label>
|
||||
|
||||
|
||||
Where Django looks for fixtures?
|
||||
================================
|
||||
|
||||
Django will search in three locations for fixtures:
|
||||
Django will search in these locations for fixtures:
|
||||
|
||||
1. In the ``fixtures`` directory of every installed application
|
||||
2. In any directory named in the :setting:`FIXTURE_DIRS` setting
|
||||
2. In any directory listed in the :setting:`FIXTURE_DIRS` setting
|
||||
3. In the literal path named by the fixture
|
||||
|
||||
Django will load any and all fixtures it finds in these locations that match
|
||||
the provided fixture names.
|
||||
|
||||
If the named fixture has a file extension, only fixtures of that type
|
||||
will be loaded. For example:
|
||||
the provided fixture names. If the named fixture has a file extension, only
|
||||
fixtures of that type will be loaded. For example:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
django-admin loaddata mydata.json
|
||||
|
||||
would only load JSON fixtures called ``mydata``. The fixture extension
|
||||
must correspond to the registered name of a
|
||||
would only load JSON fixtures called ``mydata``. The fixture extension must
|
||||
correspond to the registered name of a
|
||||
:ref:`serializer <serialization-formats>` (e.g., ``json`` or ``xml``).
|
||||
|
||||
If you omit the extensions, Django will search all available fixture types
|
||||
for a matching fixture. For example:
|
||||
If you omit the extensions, Django will search all available fixture types for
|
||||
a matching fixture. For example:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
django-admin loaddata mydata
|
||||
|
||||
would look for any fixture of any fixture type called ``mydata``. If a fixture
|
||||
directory contained ``mydata.json``, that fixture would be loaded
|
||||
as a JSON fixture.
|
||||
directory contained ``mydata.json``, that fixture would be loaded as a JSON
|
||||
fixture.
|
||||
|
||||
The fixtures that are named can include directory components. These
|
||||
directories will be included in the search path. For example:
|
||||
The fixtures that are named can include directory components. These directories
|
||||
will be included in the search path. For example:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
django-admin loaddata foo/bar/mydata.json
|
||||
|
||||
would search ``<app_label>/fixtures/foo/bar/mydata.json`` for each installed
|
||||
application, ``<dirname>/foo/bar/mydata.json`` for each directory in
|
||||
application, ``<dirname>/foo/bar/mydata.json`` for each directory in
|
||||
:setting:`FIXTURE_DIRS`, and the literal path ``foo/bar/mydata.json``.
|
||||
|
||||
Fixtures loading order
|
||||
----------------------
|
||||
|
||||
Multiple fixtures can be specified in the same invocation. For example:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
manage.py loaddata mammals birds insects
|
||||
|
||||
or in a test case class:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
class AnimalTestCase(TestCase):
|
||||
fixtures = ["mammals", "birds", "insects"]
|
||||
|
||||
The order in which fixtures are loaded follows the order in which they are
|
||||
listed, whether it's when using the management command or when listing them in
|
||||
the test case class as shown above.
|
||||
|
||||
In these examples, all the fixtures named ``mammals`` from all applications (in
|
||||
the order in which applications are defined in :setting:`INSTALLED_APPS`) will
|
||||
be loaded first. Subsequently, all the ``birds`` fixtures will be loaded,
|
||||
followed by all the ``insects`` fixtures.
|
||||
|
||||
Be aware that if the database backend supports row-level constraints, these
|
||||
constraints will be checked at the end of the transaction. Any relationships
|
||||
across fixtures may result in a load error if the database configuration does
|
||||
not support deferred constraint checking (refer to the `MySQL`_ docs for an
|
||||
example).
|
||||
|
||||
.. _MySQL: https://dev.mysql.com/doc/refman/en/constraint-foreign-key.html
|
||||
|
||||
How fixtures are saved to the database?
|
||||
=======================================
|
||||
|
||||
|
@ -124,13 +166,7 @@ You could also write a decorator to encapsulate this logic::
|
|||
...
|
||||
|
||||
Just be aware that this logic will disable the signals whenever fixtures are
|
||||
deserialized, not just during ``loaddata``.
|
||||
|
||||
Note that the order in which fixture files are processed is undefined. However,
|
||||
all fixture data is installed as a single transaction, so data in
|
||||
one fixture can reference data in another fixture. If the database backend
|
||||
supports row-level constraints, these constraints will be checked at the
|
||||
end of the transaction.
|
||||
deserialized, not just during :djadmin:`loaddata`.
|
||||
|
||||
Compressed fixtures
|
||||
===================
|
||||
|
@ -146,11 +182,10 @@ would look for any of ``mydata.json``, ``mydata.json.zip``, ``mydata.json.gz``,
|
|||
``mydata.json.bz2``, ``mydata.json.lzma``, or ``mydata.json.xz``. The first
|
||||
file contained within a compressed archive is used.
|
||||
|
||||
Note that if two fixtures with the same name but different
|
||||
fixture type are discovered (for example, if ``mydata.json`` and
|
||||
``mydata.xml.gz`` were found in the same fixture directory), fixture
|
||||
installation will be aborted, and any data installed in the call to
|
||||
``loaddata`` will be removed from the database.
|
||||
Note that if two fixtures with the same name but different fixture type are
|
||||
discovered (for example, if ``mydata.json`` and ``mydata.xml.gz`` were found in
|
||||
the same fixture directory), fixture installation will be aborted, and any data
|
||||
installed in the call to :djadmin:`loaddata` will be removed from the database.
|
||||
|
||||
.. admonition:: MySQL with MyISAM and fixtures
|
||||
|
||||
|
|
Loading…
Reference in New Issue