diff -r 5ff1fc726848 -r c6bca38c1cbf parts/django/docs/howto/initial-data.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/parts/django/docs/howto/initial-data.txt Sat Jan 08 11:20:57 2011 +0530 @@ -0,0 +1,142 @@ +================================= +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`_ + +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 ` command. +Or, you can write fixtures by hand; fixtures can be written as XML, YAML, or +JSON documents. The :doc:`serialization documentation ` +has more details about each of these supported :ref:`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 +`, 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. + +.. seealso:: + + Fixtures are also used by the :ref:`testing framework + ` 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/.sql``, +in your app directory, where ```` 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 +`. Refer to the :doc:`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. + +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 +``/sql/..sql``, where ```` is +your app directory, ```` is the model's name in lowercase +and ```` 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 +``/sql/.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``.