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 manage.py dumpdata command. Or, you can write fixtures by hand; fixtures can be written as XML, YAML, or JSON documents. The serialization documentation has more details about each of these supported serialization formats.

As an example, though, here’s what a fixture for a simple Person model might look like in JSON:

[
  {
    "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:

- 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 manage.py loaddata fixturename, where fixturename is the name of the fixture file you've created. Every time you run 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 loaddata again you'll wipe out any changes you've made.

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 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:

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 sqlcustom, sqlreset, sqlall and reset commands in manage.py. Refer to the manage.py documentation 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.