<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Providing initial data for models — Django 1.8.19 documentation</title>
<link rel="stylesheet" href="../_static/default.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '1.8.19',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="top" title="Django 1.8.19 documentation" href="../contents.html" />
<link rel="up" title="“How-to” guides" href="index.html" />
<link rel="next" title="Running Django on Jython" href="jython.html" />
<link rel="prev" title="Error reporting" href="error-reporting.html" />
<script type="text/javascript" src="../templatebuiltins.js"></script>
<script type="text/javascript">
(function($) {
if (!django_template_builtins) {
// templatebuiltins.js missing, do nothing.
return;
}
$(document).ready(function() {
// Hyperlink Django template tags and filters
var base = "../ref/templates/builtins.html";
if (base == "#") {
// Special case for builtins.html itself
base = "";
}
// Tags are keywords, class '.k'
$("div.highlight\\-html\\+django span.k").each(function(i, elem) {
var tagname = $(elem).text();
if ($.inArray(tagname, django_template_builtins.ttags) != -1) {
var fragment = tagname.replace(/_/, '-');
$(elem).html("<a href='" + base + "#" + fragment + "'>" + tagname + "</a>");
}
});
// Filters are functions, class '.nf'
$("div.highlight\\-html\\+django span.nf").each(function(i, elem) {
var filtername = $(elem).text();
if ($.inArray(filtername, django_template_builtins.tfilters) != -1) {
var fragment = filtername.replace(/_/, '-');
$(elem).html("<a href='" + base + "#" + fragment + "'>" + filtername + "</a>");
}
});
});
})(jQuery);
</script>
</head>
<body role="document">
<div class="document">
<div id="custom-doc" class="yui-t6">
<div id="hd">
<h1><a href="../index.html">Django 1.8.19 documentation</a></h1>
<div id="global-nav">
<a title="Home page" href="../index.html">Home</a> |
<a title="Table of contents" href="../contents.html">Table of contents</a> |
<a title="Global index" href="../genindex.html">Index</a> |
<a title="Module index" href="../py-modindex.html">Modules</a>
</div>
<div class="nav">
« <a href="error-reporting.html" title="Error reporting">previous</a>
|
<a href="index.html" title="&#8220;How-to&#8221; guides" accesskey="U">up</a>
|
<a href="jython.html" title="Running Django on Jython">next</a> »</div>
</div>
<div id="bd">
<div id="yui-main">
<div class="yui-b">
<div class="yui-g" id="howto-initial-data">
<div class="section" id="s-providing-initial-data-for-models">
<span id="providing-initial-data-for-models"></span><h1>Providing initial data for models<a class="headerlink" href="#providing-initial-data-for-models" title="Permalink to this headline">¶</a></h1>
<p>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 <a class="reference internal" href="#providing-initial-data-with-fixtures">initial data via fixtures</a>, or
you can provide <a class="reference internal" href="#providing-initial-sql-data">initial data as SQL</a>.</p>
<p>In general, using a fixture is a cleaner method since it’s database-agnostic,
but initial SQL is also quite a bit more flexible.</p>
<div class="section" id="s-providing-initial-data-with-fixtures">
<span id="s-id1"></span><span id="providing-initial-data-with-fixtures"></span><span id="id1"></span><h2>Providing initial data with fixtures<a class="headerlink" href="#providing-initial-data-with-fixtures" title="Permalink to this headline">¶</a></h2>
<p>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 <a class="reference internal" href="../ref/django-admin.html#django-admin-dumpdata"><code class="xref std std-djadmin docutils literal"><span class="pre">manage.py</span> <span class="pre">dumpdata</span></code></a> command.
Or, you can write fixtures by hand; fixtures can be written as JSON, XML or YAML
(with <a class="reference external" href="http://www.pyyaml.org/">PyYAML</a> installed) documents. The <a class="reference internal" href="../topics/serialization.html"><span class="doc">serialization documentation</span></a> has more details about each of these supported
<a class="reference internal" href="../topics/serialization.html#serialization-formats"><span class="std std-ref">serialization formats</span></a>.</p>
<p>As an example, though, here’s what a fixture for a simple <code class="docutils literal"><span class="pre">Person</span></code> model might
look like in JSON:</p>
<div class="highlight-js"><div class="highlight"><pre><span></span><span class="p">[</span>
<span class="p">{</span>
<span class="s2">"model"</span><span class="o">:</span> <span class="s2">"myapp.person"</span><span class="p">,</span>
<span class="s2">"pk"</span><span class="o">:</span> <span class="mi">1</span><span class="p">,</span>
<span class="s2">"fields"</span><span class="o">:</span> <span class="p">{</span>
<span class="s2">"first_name"</span><span class="o">:</span> <span class="s2">"John"</span><span class="p">,</span>
<span class="s2">"last_name"</span><span class="o">:</span> <span class="s2">"Lennon"</span>
<span class="p">}</span>
<span class="p">},</span>
<span class="p">{</span>
<span class="s2">"model"</span><span class="o">:</span> <span class="s2">"myapp.person"</span><span class="p">,</span>
<span class="s2">"pk"</span><span class="o">:</span> <span class="mi">2</span><span class="p">,</span>
<span class="s2">"fields"</span><span class="o">:</span> <span class="p">{</span>
<span class="s2">"first_name"</span><span class="o">:</span> <span class="s2">"Paul"</span><span class="p">,</span>
<span class="s2">"last_name"</span><span class="o">:</span> <span class="s2">"McCartney"</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="p">]</span>
</pre></div>
</div>
<p>And here’s that same fixture as YAML:</p>
<div class="highlight-none"><div class="highlight"><pre><span></span>- model: myapp.person
pk: 1
fields:
first_name: John
last_name: Lennon
- model: myapp.person
pk: 2
fields:
first_name: Paul
last_name: McCartney
</pre></div>
</div>
<p>You’ll store this data in a <code class="docutils literal"><span class="pre">fixtures</span></code> directory inside your app.</p>
<p>Loading data is easy: just call <a class="reference internal" href="../ref/django-admin.html#django-admin-loaddata"><code class="xref std std-djadmin docutils literal"><span class="pre">manage.py</span> <span class="pre">loaddata</span></code></a>
<code class="docutils literal"><span class="pre"><fixturename></span></code>, where <code class="docutils literal"><span class="pre"><fixturename></span></code> is the name of the fixture file
you’ve created. Each time you run <a class="reference internal" href="../ref/django-admin.html#django-admin-loaddata"><code class="xref std std-djadmin docutils literal"><span class="pre">loaddata</span></code></a>, the data will be read
from the fixture and re-loaded into the database. Note this means that if you
change one of the rows created by a fixture and then run <a class="reference internal" href="../ref/django-admin.html#django-admin-loaddata"><code class="xref std std-djadmin docutils literal"><span class="pre">loaddata</span></code></a>
again, you’ll wipe out any changes you’ve made.</p>
<div class="section" id="s-automatically-loading-initial-data-fixtures">
<span id="automatically-loading-initial-data-fixtures"></span><h3>Automatically loading initial data fixtures<a class="headerlink" href="#automatically-loading-initial-data-fixtures" title="Permalink to this headline">¶</a></h3>
<div class="deprecated">
<p><span class="versionmodified">Deprecated since version 1.7: </span>If an application uses migrations, there is no automatic loading of
fixtures. Since migrations will be required for applications in Django 1.9,
this behavior is considered deprecated. If you want to load initial data
for an app, consider doing it in a <a class="reference internal" href="../topics/migrations.html#data-migrations"><span class="std std-ref">data migration</span></a>.</p>
</div>
<p>If you create a fixture named <code class="docutils literal"><span class="pre">initial_data.[xml/yaml/json]</span></code>, that fixture will
be loaded every time you run <a class="reference internal" href="../ref/django-admin.html#django-admin-migrate"><code class="xref std std-djadmin docutils literal"><span class="pre">migrate</span></code></a>. This is extremely convenient,
but be careful: remember that the data will be refreshed <em>every time</em> you run
<a class="reference internal" href="../ref/django-admin.html#django-admin-migrate"><code class="xref std std-djadmin docutils literal"><span class="pre">migrate</span></code></a>. So don’t use <code class="docutils literal"><span class="pre">initial_data</span></code> for data you’ll want to edit.</p>
</div>
<div class="section" id="s-where-django-finds-fixture-files">
<span id="where-django-finds-fixture-files"></span><h3>Where Django finds fixture files<a class="headerlink" href="#where-django-finds-fixture-files" title="Permalink to this headline">¶</a></h3>
<p>By default, Django looks in the <code class="docutils literal"><span class="pre">fixtures</span></code> directory inside each app for
fixtures. You can set the <a class="reference internal" href="../ref/settings.html#std:setting-FIXTURE_DIRS"><code class="xref std std-setting docutils literal"><span class="pre">FIXTURE_DIRS</span></code></a> setting to a list of
additional directories where Django should look.</p>
<p>When running <a class="reference internal" href="../ref/django-admin.html#django-admin-loaddata"><code class="xref std std-djadmin docutils literal"><span class="pre">manage.py</span> <span class="pre">loaddata</span></code></a>, you can also
specify a path to a fixture file, which overrides searching the usual
directories.</p>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last">Fixtures are also used by the <a class="reference internal" href="../topics/testing/tools.html#topics-testing-fixtures"><span class="std std-ref">testing framework</span></a> to help set up a consistent test environment.</p>
</div>
</div>
</div>
<div class="section" id="s-providing-initial-sql-data">
<span id="s-initial-sql"></span><span id="providing-initial-sql-data"></span><span id="initial-sql"></span><h2>Providing initial SQL data<a class="headerlink" href="#providing-initial-sql-data" title="Permalink to this headline">¶</a></h2>
<div class="deprecated">
<p><span class="versionmodified">Deprecated since version 1.7: </span>If an application uses migrations, there is no loading of initial SQL data
(including backend-specific SQL data). Since migrations will be required
for applications in Django 1.9, this behavior is considered deprecated.
If you want to use initial SQL for an app, consider doing it in a
<a class="reference internal" href="../topics/migrations.html#data-migrations"><span class="std std-ref">data migration</span></a>.</p>
</div>
<p>Django provides a hook for passing the database arbitrary SQL that’s executed
just after the CREATE TABLE statements when you run <a class="reference internal" href="../ref/django-admin.html#django-admin-migrate"><code class="xref std std-djadmin docutils literal"><span class="pre">migrate</span></code></a>. You can
use this hook to populate default records, or you could also create SQL
functions, views, triggers, etc.</p>
<p>The hook is simple: Django just looks for a file called <code class="docutils literal"><span class="pre">sql/<modelname>.sql</span></code>,
in your app directory, where <code class="docutils literal"><span class="pre"><modelname></span></code> is the model’s name in lowercase.</p>
<p>So, if you had a <code class="docutils literal"><span class="pre">Person</span></code> model in an app called <code class="docutils literal"><span class="pre">myapp</span></code>, you could add
arbitrary SQL to the file <code class="docutils literal"><span class="pre">sql/person.sql</span></code> inside your <code class="docutils literal"><span class="pre">myapp</span></code> directory.
Here’s an example of what the file might contain:</p>
<div class="highlight-sql"><div class="highlight"><pre><span></span><span class="k">INSERT</span> <span class="k">INTO</span> <span class="n">myapp_person</span> <span class="p">(</span><span class="n">first_name</span><span class="p">,</span> <span class="n">last_name</span><span class="p">)</span> <span class="k">VALUES</span> <span class="p">(</span><span class="s1">'John'</span><span class="p">,</span> <span class="s1">'Lennon'</span><span class="p">);</span>
<span class="k">INSERT</span> <span class="k">INTO</span> <span class="n">myapp_person</span> <span class="p">(</span><span class="n">first_name</span><span class="p">,</span> <span class="n">last_name</span><span class="p">)</span> <span class="k">VALUES</span> <span class="p">(</span><span class="s1">'Paul'</span><span class="p">,</span> <span class="s1">'McCartney'</span><span class="p">);</span>
</pre></div>
</div>
<p>Each SQL file, if given, is expected to contain valid SQL statements
which will insert the desired data (e.g., properly-formatted
<code class="docutils literal"><span class="pre">INSERT</span></code> statements separated by semicolons).</p>
<p>The SQL files are read by the <a class="reference internal" href="../ref/django-admin.html#django-admin-sqlcustom"><code class="xref std std-djadmin docutils literal"><span class="pre">sqlcustom</span></code></a> and <a class="reference internal" href="../ref/django-admin.html#django-admin-sqlall"><code class="xref std std-djadmin docutils literal"><span class="pre">sqlall</span></code></a>
commands in <a class="reference internal" href="../ref/django-admin.html"><span class="doc">manage.py</span></a>. Refer to the <a class="reference internal" href="../ref/django-admin.html"><span class="doc">manage.py
documentation</span></a> for more information.</p>
<p>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.</p>
<div class="admonition-initial-sql-data-and-testing admonition">
<p class="first admonition-title">Initial SQL data and testing</p>
<p>This technique <em>cannot</em> 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.</p>
<p class="last">If you require data for a test case, you should add it using
either a <a class="reference internal" href="../topics/testing/tools.html#topics-testing-fixtures"><span class="std std-ref">test fixture</span></a>, or
programmatically add it during the <code class="docutils literal"><span class="pre">setUp()</span></code> of your test case.</p>
</div>
<div class="section" id="s-database-backend-specific-sql-data">
<span id="database-backend-specific-sql-data"></span><h3>Database-backend-specific SQL data<a class="headerlink" href="#database-backend-specific-sql-data" title="Permalink to this headline">¶</a></h3>
<p>There’s also a hook for backend-specific SQL data. For example, you
can have separate initial-data files for PostgreSQL and SQLite. For
each app, Django looks for a file called
<code class="docutils literal"><span class="pre"><app_label>/sql/<modelname>.<backend>.sql</span></code>, where <code class="docutils literal"><span class="pre"><app_label></span></code> is
your app directory, <code class="docutils literal"><span class="pre"><modelname></span></code> is the model’s name in lowercase
and <code class="docutils literal"><span class="pre"><backend></span></code> is the last part of the module name provided for the
<a class="reference internal" href="../ref/settings.html#std:setting-DATABASE-ENGINE"><code class="xref std std-setting docutils literal"><span class="pre">ENGINE</span></code></a> in your settings file (e.g., if you have
defined a database with an <a class="reference internal" href="../ref/settings.html#std:setting-DATABASE-ENGINE"><code class="xref std std-setting docutils literal"><span class="pre">ENGINE</span></code></a> value of
<code class="docutils literal"><span class="pre">django.db.backends.sqlite3</span></code>, Django will look for
<code class="docutils literal"><span class="pre"><app_label>/sql/<modelname>.sqlite3.sql</span></code>).</p>
<p>Backend-specific SQL data is executed before non-backend-specific SQL
data. For example, if your app contains the files <code class="docutils literal"><span class="pre">sql/person.sql</span></code>
and <code class="docutils literal"><span class="pre">sql/person.sqlite3.sql</span></code> and you’re installing the app on
SQLite, Django will execute the contents of
<code class="docutils literal"><span class="pre">sql/person.sqlite3.sql</span></code> first, then <code class="docutils literal"><span class="pre">sql/person.sql</span></code>.</p>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="yui-b" id="sidebar">
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="../contents.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Providing initial data for models</a><ul>
<li><a class="reference internal" href="#providing-initial-data-with-fixtures">Providing initial data with fixtures</a><ul>
<li><a class="reference internal" href="#automatically-loading-initial-data-fixtures">Automatically loading initial data fixtures</a></li>
<li><a class="reference internal" href="#where-django-finds-fixture-files">Where Django finds fixture files</a></li>
</ul>
</li>
<li><a class="reference internal" href="#providing-initial-sql-data">Providing initial SQL data</a><ul>
<li><a class="reference internal" href="#database-backend-specific-sql-data">Database-backend-specific SQL data</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<h3>Browse</h3>
<ul>
<li>Prev: <a href="error-reporting.html">Error reporting</a></li>
<li>Next: <a href="jython.html">Running Django on Jython</a></li>
</ul>
<h3>You are here:</h3>
<ul>
<li>
<a href="../index.html">Django 1.8.19 documentation</a>
<ul><li><a href="index.html">“How-to” guides</a>
<ul><li>Providing initial data for models</li></ul>
</li></ul>
</li>
</ul>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/howto/initial-data.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<form class="search" action="../search.html" method="get">
<div><input type="text" name="q" /></div>
<div><input type="submit" value="Go" /></div>
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<h3>Last update:</h3>
<p class="topless">Mar 10, 2018</p>
</div>
</div>
<div id="ft">
<div class="nav">
« <a href="error-reporting.html" title="Error reporting">previous</a>
|
<a href="index.html" title="&#8220;How-to&#8221; guides" accesskey="U">up</a>
|
<a href="jython.html" title="Running Django on Jython">next</a> »</div>
</div>
</div>
<div class="clearer"></div>
</div>
</body>
</html>
