mirror of
https://github.com/django/django.git
synced 2025-09-17 22:49:35 +00:00
f81e6e3a53
Lines in the docs files were manually adjusted to conform to the 79 columns limit per line (plus newline), improving readability and consistency across the content.
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 hardcoded 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.
|