1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
|
=================================
Providing initial data for models
=================================
It's sometimes useful to pre-populate your database with hard-coded data when
you're first setting up an app. There's a couple of ways you can have Django
automatically create this data: you can provide `initial data via fixtures`_, or
you can provide `initial data as SQL`_.
In general, using a fixture is a cleaner method since it's database-agnostic,
but initial SQL is also quite a bit more flexible.
.. _initial data as sql: `providing initial sql data`_
.. _initial data via fixtures: `providing initial data with fixtures`_
.. _initial-data-via-fixtures:
Providing initial data with 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 XML, YAML, or
JSON documents. The :doc:`serialization documentation </topics/serialization>`
has more details about each of these supported :ref:`serialization formats
<serialization-formats>`.
As an example, though, here's what a fixture for a simple ``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:: none
- 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.
Loading data is easy: just call :djadmin:`manage.py loaddata <fixturename>
<loaddata>`, where ``<fixturename>`` is the name of the fixture file you've
created. Every time you run :djadmin:`loaddata` the data will be read from the
fixture and re-loaded into the database. Note that 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.
Automatically loading initial data fixtures
-------------------------------------------
If you create a fixture named ``initial_data.[xml/yaml/json]``, that fixture will
be loaded every time you run :djadmin:`syncdb`. This is extremely convenient,
but be careful: remember that the data will be refreshed *every time* you run
:djadmin:`syncdb`. So don't use ``initial_data`` for data you'll want to edit.
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 an absolute 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.
.. _initial-sql:
Providing initial SQL data
==========================
Django provides a hook for passing the database arbitrary SQL that's executed
just after the CREATE TABLE statements when you run :djadmin:`syncdb`. You can
use this hook to populate default records, or you could also create SQL
functions, views, triggers, etc.
The hook is simple: Django just looks for a file called ``sql/<modelname>.sql``,
in your app directory, where ``<modelname>`` is the model's name in lowercase.
So, if you had a ``Person`` model in an app called ``myapp``, you could add
arbitrary SQL to the file ``sql/person.sql`` inside your ``myapp`` directory.
Here's an example of what the file might contain:
.. code-block:: sql
INSERT INTO myapp_person (first_name, last_name) VALUES ('John', 'Lennon');
INSERT INTO myapp_person (first_name, last_name) VALUES ('Paul', 'McCartney');
Each SQL file, if given, is expected to contain valid SQL statements
which will insert the desired data (e.g., properly-formatted
``INSERT`` statements separated by semicolons).
The SQL files are read by the :djadmin:`sqlcustom`, :djadmin:`sqlreset`,
:djadmin:`sqlall` and :djadmin:`reset` commands in :doc:`manage.py
</ref/django-admin>`. Refer to the :doc:`manage.py documentation
</ref/django-admin>` for more information.
Note that if you have multiple SQL data files, there's no guarantee of
the order in which they're executed. The only thing you can assume is
that, by the time your custom data files are executed, all the
database tables already will have been created.
.. admonition:: Initial SQL data and testing
This technique *cannot* be used to provide initial data for
testing purposes. Django's test framework flushes the contents of
the test database after each test; as a result, any data added
using the custom SQL hook will be lost.
If you require data for a test case, you should add it using
either a :ref:`test fixture <topics-testing-fixtures>`, or
programatically add it during the ``setUp()`` of your test case.
Database-backend-specific SQL data
----------------------------------
There's also a hook for backend-specific SQL data. For example, you
can have separate initial-data files for PostgreSQL and MySQL. For
each app, Django looks for a file called
``<appname>/sql/<modelname>.<backend>.sql``, where ``<appname>`` is
your app directory, ``<modelname>`` is the model's name in lowercase
and ``<backend>`` is the last part of the module name provided for the
:setting:`ENGINE` in your settings file (e.g., if you have defined a
database with an :setting:`ENGINE` value of
``django.db.backends.postgresql``, Django will look for
``<appname>/sql/<modelname>.postgresql.sql``).
Backend-specific SQL data is executed before non-backend-specific SQL
data. For example, if your app contains the files ``sql/person.sql``
and ``sql/person.postgresql.sql`` and you're installing the app on
PostgreSQL, Django will execute the contents of
``sql/person.postgresql.sql`` first, then ``sql/person.sql``.
|
