mirror of https://github.com/django/django.git
112 lines
3.8 KiB
Plaintext
112 lines
3.8 KiB
Plaintext
======================================
|
|
How to provide initial data for models
|
|
======================================
|
|
|
|
It's sometimes useful to prepopulate your database with hard-coded data when
|
|
you're first setting up an app. You can provide initial data with migrations or
|
|
fixtures.
|
|
|
|
Provide initial data with migrations
|
|
====================================
|
|
|
|
To automatically load initial data for an app, create a
|
|
:ref:`data migration <data-migrations>`. Migrations are run when setting up the
|
|
test database, so the data will be available there, subject to :ref:`some
|
|
limitations <test-case-serialized-rollback>`.
|
|
|
|
.. _initial-data-via-fixtures:
|
|
|
|
Provide data with fixtures
|
|
==========================
|
|
|
|
You can also provide data using :ref:`fixtures <fixtures-explanation>`,
|
|
however, this data isn't loaded automatically, except if you use
|
|
:attr:`.TransactionTestCase.fixtures`.
|
|
|
|
A fixture is a collection of data that Django knows how to import into a
|
|
database. The most straightforward way of creating a fixture if you've already
|
|
got some data is to use the :djadmin:`manage.py dumpdata <dumpdata>` command.
|
|
Or, you can write fixtures by hand; fixtures can be written as JSON, XML or YAML
|
|
(with PyYAML_ installed) documents. The :doc:`serialization documentation
|
|
</topics/serialization>` has more details about each of these supported
|
|
:ref:`serialization formats <serialization-formats>`.
|
|
|
|
.. _PyYAML: https://pyyaml.org/
|
|
|
|
As an example, though, here's what a fixture for a ``Person`` model might look
|
|
like in JSON:
|
|
|
|
.. code-block:: js
|
|
|
|
[
|
|
{
|
|
"model": "myapp.person",
|
|
"pk": 1,
|
|
"fields": {
|
|
"first_name": "John",
|
|
"last_name": "Lennon"
|
|
}
|
|
},
|
|
{
|
|
"model": "myapp.person",
|
|
"pk": 2,
|
|
"fields": {
|
|
"first_name": "Paul",
|
|
"last_name": "McCartney"
|
|
}
|
|
}
|
|
]
|
|
|
|
And here's that same fixture as YAML:
|
|
|
|
.. code-block:: yaml
|
|
|
|
- model: myapp.person
|
|
pk: 1
|
|
fields:
|
|
first_name: John
|
|
last_name: Lennon
|
|
- model: myapp.person
|
|
pk: 2
|
|
fields:
|
|
first_name: Paul
|
|
last_name: McCartney
|
|
|
|
You'll store this data in a ``fixtures`` directory inside your app.
|
|
|
|
You can load data by calling :djadmin:`manage.py loaddata <loaddata>`
|
|
``<fixturename>``, where ``<fixturename>`` is the name of the fixture file
|
|
you've created. Each time you run :djadmin:`loaddata`, the data will be read
|
|
from the fixture and reloaded into the database. Note this means that if you
|
|
change one of the rows created by a fixture and then run :djadmin:`loaddata`
|
|
again, you'll wipe out any changes you've made.
|
|
|
|
Tell Django where to look for fixture files
|
|
-------------------------------------------
|
|
|
|
By default, Django looks for fixtures in the ``fixtures`` directory inside each
|
|
app, so the command ``loaddata sample`` will find the file
|
|
``my_app/fixtures/sample.json``. This works with relative paths as well, so
|
|
``loaddata my_app/sample`` will find the file
|
|
``my_app/fixtures/my_app/sample.json``.
|
|
|
|
Django also looks for fixtures in the list of directories provided in the
|
|
:setting:`FIXTURE_DIRS` setting.
|
|
|
|
To completely prevent default search from happening, use an absolute path to
|
|
specify the location of your fixture file, e.g. ``loaddata /path/to/sample``.
|
|
|
|
.. admonition:: Namespace your fixture files
|
|
|
|
Django will use the first fixture file it finds whose name matches, so if
|
|
you have fixture files with the same name in different applications, you
|
|
will be unable to distinguish between them in your ``loaddata`` commands.
|
|
The easiest way to avoid this problem is by *namespacing* your fixture
|
|
files. That is, by putting them inside a directory named for their
|
|
application, as in the relative path example above.
|
|
|
|
.. seealso::
|
|
|
|
Fixtures are also used by the :ref:`testing framework
|
|
<topics-testing-fixtures>` to help set up a consistent test environment.
|