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