======================================

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.

Providing initial data with migrations

======================================

If you want 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:

Providing data with fixtures

============================

You can also provide data using fixtures, 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.

Where Django finds fixture files

--------------------------------

By default, Django looks in the ``fixtures`` directory inside each app for

fixtures. You can set the :setting:`FIXTURE_DIRS` setting to a list of

additional directories where Django should look.

When running :djadmin:`manage.py loaddata <loaddata>`, you can also

specify a path to a fixture file, which overrides searching the usual

directories.

.. seealso::

    Fixtures are also used by the :ref:`testing framework

    <topics-testing-fixtures>` to help set up a consistent test environment.