Debian Codegraph @

docs/howto/initial-data.txt

raw
1 ======================================
2 How to provide initial data for models
3 ======================================
4
5 It's sometimes useful to prepopulate your database with hard-coded data when
6 you're first setting up an app. You can provide initial data with migrations or
7 fixtures.
8
9 Provide initial data with migrations
10 ====================================
11
12 To automatically load initial data for an app, create a
13 :ref:`data migration <data-migrations>`. Migrations are run when setting up the
14 test database, so the data will be available there, subject to :ref:`some
15 limitations <test-case-serialized-rollback>`.
16
17 .. _initial-data-via-fixtures:
18
19 Provide data with fixtures
20 ==========================
21
22 You can also provide data using :ref:`fixtures <fixtures-explanation>`,
23 however, this data isn't loaded automatically, except if you use
24 :attr:`.TransactionTestCase.fixtures`.
25
26 A fixture is a collection of data that Django knows how to import into a
27 database. The most straightforward way of creating a fixture if you've already
28 got some data is to use the :djadmin:`manage.py dumpdata <dumpdata>` command.
29 Or, you can write fixtures by hand; fixtures can be written as JSON, XML or YAML
30 (with PyYAML_ installed) documents. The :doc:`serialization documentation
31 </topics/serialization>` has more details about each of these supported
32 :ref:`serialization formats <serialization-formats>`.
33
34 .. _PyYAML: https://pyyaml.org/
35
36 As an example, though, here's what a fixture for a ``Person`` model might look
37 like in JSON:
38
39 .. code-block:: js
40
41 [
42 {
43 "model": "myapp.person",
44 "pk": 1,
45 "fields": {
46 "first_name": "John",
47 "last_name": "Lennon"
48 }
49 },
50 {
51 "model": "myapp.person",
52 "pk": 2,
53 "fields": {
54 "first_name": "Paul",
55 "last_name": "McCartney"
56 }
57 }
58 ]
59
60 And here's that same fixture as YAML:
61
62 .. code-block:: yaml
63
64 - model: myapp.person
65 pk: 1
66 fields:
67 first_name: John
68 last_name: Lennon
69 - model: myapp.person
70 pk: 2
71 fields:
72 first_name: Paul
73 last_name: McCartney
74
75 You'll store this data in a ``fixtures`` directory inside your app.
76
77 You can load data by calling :djadmin:`manage.py loaddata <loaddata>`
78 ``<fixturename>``, where ``<fixturename>`` is the name of the fixture file
79 you've created. Each time you run :djadmin:`loaddata`, the data will be read
80 from the fixture and reloaded into the database. Note this means that if you
81 change one of the rows created by a fixture and then run :djadmin:`loaddata`
82 again, you'll wipe out any changes you've made.
83
84 Tell Django where to look for fixture files
85 -------------------------------------------
86
87 By default, Django looks for fixtures in the ``fixtures`` directory inside each
88 app, so the command ``loaddata sample`` will find the file
89 ``my_app/fixtures/sample.json``. This works with relative paths as well, so
90 ``loaddata my_app/sample`` will find the file
91 ``my_app/fixtures/my_app/sample.json``.
92
93 Django also looks for fixtures in the list of directories provided in the
94 :setting:`FIXTURE_DIRS` setting.
95
96 To completely prevent default search from happening, use an absolute path to
97 specify the location of your fixture file, e.g. ``loaddata /path/to/sample``.
98
99 .. admonition:: Namespace your fixture files
100
101 Django will use the first fixture file it finds whose name matches, so if
102 you have fixture files with the same name in different applications, you
103 will be unable to distinguish between them in your ``loaddata`` commands.
104 The easiest way to avoid this problem is by *namespacing* your fixture
105 files. That is, by putting them inside a directory named for their
106 application, as in the relative path example above.
107
108 .. seealso::
109
110 Fixtures are also used by the :ref:`testing framework
111 <topics-testing-fixtures>` to help set up a consistent test environment.