mirror of
https://github.com/django/django.git
synced 2024-12-23 01:25:58 +00:00
Small start to migrations documentation
This commit is contained in:
parent
00276e0414
commit
06103c8ef5
@ -71,6 +71,9 @@ manipulating the data of your Web application. Learn more about it below:
|
||||
:doc:`Instance methods <ref/models/instances>` |
|
||||
:doc:`Accessing related objects <ref/models/relations>`
|
||||
|
||||
* **Migrations:**
|
||||
:doc:`Introduction to Migrations<topics/migrations>`
|
||||
|
||||
* **Advanced:**
|
||||
:doc:`Managers <topics/db/managers>` |
|
||||
:doc:`Raw SQL <topics/db/sql>` |
|
||||
|
@ -572,6 +572,48 @@ Use the ``--keep-pot`` option to prevent django from deleting the temporary
|
||||
.pot file it generates before creating the .po file. This is useful for
|
||||
debugging errors which may prevent the final language files from being created.
|
||||
|
||||
makemigrations [<appname>]
|
||||
--------------------------
|
||||
|
||||
.. django-admin:: makemigrations
|
||||
|
||||
Creates new migrations based on the changes detected to your models.
|
||||
Migrations, their relationship with apps and more are covered in depth in
|
||||
:doc:`the migrations documentation</topics/migrations>`.
|
||||
|
||||
Providing one or more app names as arguments will limit the migrations created
|
||||
to the app specified and any dependencies needed (the table at the other end
|
||||
of a ForeignKey, for example)
|
||||
|
||||
.. django-admin-option:: --empty
|
||||
|
||||
The ``--empty`` option will cause ``makemigrations`` to output an empty
|
||||
migration for the specified apps, for manual editing. This option is only
|
||||
for advanced users and should not be used unless you are familiar with
|
||||
the migration format, migration operations and the dependencies between
|
||||
your migrations.
|
||||
|
||||
migrate [<appname> [<migrationname>]]
|
||||
-------------------------------------
|
||||
|
||||
.. django-admin:: migrate
|
||||
|
||||
Synchronises the database state with the current set of models and migrations.
|
||||
Migrations, their relationship with apps and more are covered in depth in
|
||||
:doc:`the migrations documentation</topics/migrations>`.
|
||||
|
||||
The behaviour of this command changes depending on the arguments provided:
|
||||
|
||||
* No arguments: All migrated apps have all of their migrations run,
|
||||
and all unmigrated apps are synchronized with the database,
|
||||
* ``<appname>``: The specified app has its migrations run, up to the most
|
||||
recent migration. This may involve running other apps' migrations too, due
|
||||
to dependencies.
|
||||
* ``<appname> <migrationname>``: Brings the database schema to a state where it
|
||||
would have just run the given migration, but no further - this may involve
|
||||
unapplying migrations if you have previously migrated past the named
|
||||
migration. Use the name `zero` to unapply all migrations for an app.
|
||||
|
||||
runfcgi [options]
|
||||
-----------------
|
||||
|
||||
@ -1107,47 +1149,13 @@ syncdb
|
||||
|
||||
.. django-admin:: syncdb
|
||||
|
||||
Creates the database tables for all apps in :setting:`INSTALLED_APPS` whose
|
||||
tables have not already been created.
|
||||
.. deprecated:: 1.7
|
||||
|
||||
Use this command when you've added new applications to your project and want to
|
||||
install them in the database. This includes any apps shipped with Django that
|
||||
might be in :setting:`INSTALLED_APPS` by default. When you start a new project,
|
||||
run this command to install the default apps.
|
||||
This command has been deprecated in favour of the :djadmin:`migrate`
|
||||
command, which performs both the old behaviour as well as executing
|
||||
migrations. It is now just an alias to that command.
|
||||
|
||||
.. admonition:: Syncdb will not alter existing tables
|
||||
|
||||
``syncdb`` will only create tables for models which have not yet been
|
||||
installed. It will *never* issue ``ALTER TABLE`` statements to match
|
||||
changes made to a model class after installation. Changes to model classes
|
||||
and database schemas often involve some form of ambiguity and, in those
|
||||
cases, Django would have to guess at the correct changes to make. There is
|
||||
a risk that critical data would be lost in the process.
|
||||
|
||||
If you have made changes to a model and wish to alter the database tables
|
||||
to match, use the ``sql`` command to display the new SQL structure and
|
||||
compare that to your existing table schema to work out the changes.
|
||||
|
||||
If you're installing the ``django.contrib.auth`` application, ``syncdb`` will
|
||||
give you the option of creating a superuser immediately.
|
||||
|
||||
``syncdb`` will also search for and install any fixture named ``initial_data``
|
||||
with an appropriate extension (e.g. ``json`` or ``xml``). See the
|
||||
documentation for ``loaddata`` for details on the specification of fixture
|
||||
data files.
|
||||
|
||||
The :djadminopt:`--noinput` option may be provided to suppress all user
|
||||
prompts.
|
||||
|
||||
The :djadminopt:`--database` option can be used to specify the database to
|
||||
synchronize.
|
||||
|
||||
--no-initial-data
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. versionadded:: 1.5
|
||||
|
||||
Use ``--no-initial-data`` to avoid loading the initial_data fixture.
|
||||
Alias for :djadmin:`migrate`.
|
||||
|
||||
test <app or test identifier>
|
||||
-----------------------------
|
||||
|
@ -12,6 +12,7 @@ Introductions to all the key parts of Django you'll need to know:
|
||||
forms/index
|
||||
templates
|
||||
class-based-views/index
|
||||
migrations
|
||||
files
|
||||
testing/index
|
||||
auth/index
|
||||
|
113
docs/topics/migrations.txt
Normal file
113
docs/topics/migrations.txt
Normal file
@ -0,0 +1,113 @@
|
||||
==========
|
||||
Migrations
|
||||
==========
|
||||
|
||||
.. module:: django.db.migrations
|
||||
:synopsis: Schema migration support for Django models
|
||||
|
||||
.. versionadded:: 1.7
|
||||
|
||||
Migrations are Django's way of propagating changes you make to your models
|
||||
(adding a field, deleting a model, etc.) into your database schema. They're
|
||||
designed to be mostly automatic, but you'll need to know when to make
|
||||
migrations, when to run them, and the common problems you might run into.
|
||||
|
||||
A Brief History
|
||||
---------------
|
||||
|
||||
Prior to version 1.7, Django only supported adding new models to the
|
||||
database; it was not possible to alter or remove existing models via the
|
||||
``syncdb`` command (the predecessor to ``migrate``).
|
||||
|
||||
Third-party tools, most notably `South <http://south.aeracode.org>`_,
|
||||
provided support for these additional types of change, but it was considered
|
||||
important enough that support was brought into core Django.
|
||||
|
||||
Two Commands
|
||||
------------
|
||||
|
||||
There are two commands which you will use to interact with migrations
|
||||
and Django's handling of database schema:
|
||||
|
||||
* :djadmin:`migrate`, which is responsible for applying migrations, as well as
|
||||
unapplying and listing their status.
|
||||
|
||||
* :djadmin:`makemigrations`, which is responsible for creating new migrations
|
||||
based on the changes you have made to your models.
|
||||
|
||||
It's worth noting that migrations are created and run on a per-app basis.
|
||||
In particular, it's possible to have apps that *do not use migrations* (these
|
||||
are referred to as "unmigrated" apps) - these apps will instead mimic the
|
||||
legacy behaviour of just adding new models.
|
||||
|
||||
You should think of migrations as a version control system for your database
|
||||
schema. ``makemigrations`` is responsible for packaging up your model changes
|
||||
into individual migration files - analagous to commits - and ``migrate`` is
|
||||
responsible for applying those to your database.
|
||||
|
||||
The migration files for each app live in a "migrations" directory inside
|
||||
of that app, and are designed to be committed to, and distributed as part
|
||||
of, its codebase. You should be making them once on your development machine
|
||||
and then running the same migrations on your colleagues' machines, your
|
||||
staging machines and eventually your production machines.
|
||||
|
||||
Migrations will run the same way every time and produce consistent results,
|
||||
meaning that what you see in development and staging is exactly what will
|
||||
happen in production - no unexpected surprises.
|
||||
|
||||
Backend Support
|
||||
---------------
|
||||
|
||||
Migrations are supported on all backends that Django ships with, as well
|
||||
as any third-party backends if they have programmed in support for schema
|
||||
alteration (done via the SchemaEditor class).
|
||||
|
||||
However, some databases are more capable than others when it comes to
|
||||
schema migrations; some of the caveats are covered below.
|
||||
|
||||
PostgreSQL
|
||||
~~~~~~~~~~
|
||||
|
||||
PostgreSQL is the most capable of all the databases here in terms of schema
|
||||
support; the only caveat is that adding columns with default values will
|
||||
lock a table for a time proportional to the number of rows in it.
|
||||
|
||||
For this reason, it's recommended you always create new columns with
|
||||
``null=True``, as this way they will be added immediately.
|
||||
|
||||
MySQL
|
||||
~~~~~
|
||||
|
||||
MySQL lacks support for transactions around schema alteration operations,
|
||||
meaning that if a migration fails to apply you will have to manually unpick
|
||||
the changes in order to try again (it's impossible to roll back to an
|
||||
earlier point).
|
||||
|
||||
In addition, MySQL will lock tables for almost every schema operation and
|
||||
generally takes a time proportional to the number of rows in the table to
|
||||
add or remove columns. On slower hardware this can be worse than a minute
|
||||
per million rows - adding a few columns to a table with just a few million
|
||||
rows could lock your site up for over ten minutes.
|
||||
|
||||
Finally, MySQL has reasonably small limits on name lengths for columns, tables
|
||||
and indexes, as well as a limit on the combined size of all columns an index
|
||||
covers. This means that indexes that are possible on other backends will
|
||||
fail to be created under MySQL.
|
||||
|
||||
SQLite
|
||||
~~~~~~
|
||||
|
||||
SQLite has very little built-in schema alteration support, and so Django
|
||||
attempts to emulate it by:
|
||||
|
||||
* Creating a new table with the new schema
|
||||
* Copying the data across
|
||||
* Dropping the old table
|
||||
* Renaming the new table to match the original name
|
||||
|
||||
This process generally works well, but it can be slow and occasionally
|
||||
buggy. It is not recommended that you run and migrate SQLite in a
|
||||
production environment unless you are very aware of the risks and
|
||||
its limitations; the support Django ships with is designed to allow
|
||||
developers to use SQLite on their local machines to develop less complex
|
||||
Django projects without the need for a full database.
|
Loading…
Reference in New Issue
Block a user