From f8297f63233ccf78f923a597ed7d8327f90230c2 Mon Sep 17 00:00:00 2001 From: Andrew Godwin Date: Thu, 25 Jul 2013 16:19:36 +0100 Subject: [PATCH] More migration docs, and conversion of all easy syncdb references --- docs/howto/legacy-databases.txt | 4 +- .../contributing/writing-documentation.txt | 4 +- docs/intro/overview.txt | 7 +- docs/intro/reusable-apps.txt | 2 +- docs/man/django-admin.1 | 9 +- docs/ref/contrib/comments/index.txt | 2 +- docs/ref/contrib/contenttypes.txt | 2 +- docs/ref/contrib/flatpages.txt | 4 +- docs/ref/contrib/index.txt | 2 +- docs/ref/contrib/redirects.txt | 4 +- docs/ref/contrib/sites.txt | 2 +- docs/ref/databases.txt | 6 +- docs/ref/django-admin.txt | 16 ++- docs/ref/models/options.txt | 12 +- docs/topics/auth/customizing.txt | 14 +-- docs/topics/auth/default.txt | 10 +- docs/topics/auth/index.txt | 2 +- docs/topics/db/models.txt | 7 +- docs/topics/http/sessions.txt | 2 +- docs/topics/install.txt | 6 +- docs/topics/migrations.txt | 112 +++++++++++++++++- docs/topics/serialization.txt | 2 +- docs/topics/testing/advanced.txt | 4 +- docs/topics/testing/overview.txt | 4 +- 24 files changed, 172 insertions(+), 67 deletions(-) diff --git a/docs/howto/legacy-databases.txt b/docs/howto/legacy-databases.txt index 0bea8b41c4..1cf8329e79 100644 --- a/docs/howto/legacy-databases.txt +++ b/docs/howto/legacy-databases.txt @@ -81,10 +81,10 @@ access to your precious data on a model by model basis. Install the core Django tables ============================== -Next, run the :djadmin:`syncdb` command to install any extra needed database +Next, run the :djadmin:`migrate` command to install any extra needed database records such as admin permissions and content types:: - python manage.py syncdb + python manage.py migrate Test and tweak ============== diff --git a/docs/internals/contributing/writing-documentation.txt b/docs/internals/contributing/writing-documentation.txt index 2944dea504..d2cfaddc89 100644 --- a/docs/internals/contributing/writing-documentation.txt +++ b/docs/internals/contributing/writing-documentation.txt @@ -165,9 +165,9 @@ __ http://sphinx.pocoo.org/markup/desc.html * ``django-admin`` commands:: - .. django-admin:: syncdb + .. django-admin:: migrate - To link, use ``:djadmin:`syncdb```. + To link, use ``:djadmin:`migrate```. * ``django-admin`` command-line options:: diff --git a/docs/intro/overview.txt b/docs/intro/overview.txt index 55366fb2c6..415e831faf 100644 --- a/docs/intro/overview.txt +++ b/docs/intro/overview.txt @@ -53,10 +53,11 @@ automatically: .. code-block:: bash - manage.py syncdb + manage.py migrate -The :djadmin:`syncdb` command looks at all your available models and creates -tables in your database for whichever tables don't already exist. +The :djadmin:`migrate` command looks at all your available models and creates +tables in your database for whichever tables don't already exist, as well as +optionally providing :doc:`much richer schema control `. Enjoy the free API ================== diff --git a/docs/intro/reusable-apps.txt b/docs/intro/reusable-apps.txt index 7fa1ffc8d9..51c1228cc1 100644 --- a/docs/intro/reusable-apps.txt +++ b/docs/intro/reusable-apps.txt @@ -155,7 +155,7 @@ this. For a small app like polls, this process isn't too difficult. url(r'^polls/', include('polls.urls')), - 3. Run `python manage.py syncdb` to create the polls models. + 3. Run `python manage.py migrate` to create the polls models. 4. Start the development server and visit http://127.0.0.1:8000/admin/ to create a poll (you'll need the Admin app enabled). diff --git a/docs/man/django-admin.1 b/docs/man/django-admin.1 index 4d937b488b..f1b568daf5 100644 --- a/docs/man/django-admin.1 +++ b/docs/man/django-admin.1 @@ -45,8 +45,7 @@ Outputs to standard output all data in the database associated with the named application(s). .TP .BI flush -Returns the database to the state it was in immediately after syncdb was -executed. +Removes all data from the database and then re-installs any initial data. .TP .B inspectdb Introspects the database tables in the database specified in settings.py and outputs a Django @@ -114,9 +113,9 @@ the current directory or the optional destination. Creates a Django project directory structure for the given project name in the current directory or the optional destination. .TP -.BI syncdb -Creates the database tables for all apps in INSTALLED_APPS whose tables -haven't already been created. +.BI migrate +Runs migrations for apps containing migrations, and just creates missing tables +for apps without migrations. .TP .BI "test [" "\-\-verbosity" "] [" "\-\-failfast" "] [" "appname ..." "]" Runs the test suite for the specified applications, or the entire project if diff --git a/docs/ref/contrib/comments/index.txt b/docs/ref/contrib/comments/index.txt index 6db69d8168..c08ac21d4e 100644 --- a/docs/ref/contrib/comments/index.txt +++ b/docs/ref/contrib/comments/index.txt @@ -31,7 +31,7 @@ To get started using the ``comments`` app, follow these steps: #. Install the comments framework by adding ``'django.contrib.comments'`` to :setting:`INSTALLED_APPS`. -#. Run ``manage.py syncdb`` so that Django will create the comment tables. +#. Run ``manage.py migrate`` so that Django will create the comment tables. #. Add the comment app's URLs to your project's ``urls.py``: diff --git a/docs/ref/contrib/contenttypes.txt b/docs/ref/contrib/contenttypes.txt index fcd66a5b03..89c4a88e00 100644 --- a/docs/ref/contrib/contenttypes.txt +++ b/docs/ref/contrib/contenttypes.txt @@ -86,7 +86,7 @@ The ``ContentType`` model Let's look at an example to see how this works. If you already have the :mod:`~django.contrib.contenttypes` application installed, and then add :mod:`the sites application ` to your -:setting:`INSTALLED_APPS` setting and run ``manage.py syncdb`` to install it, +:setting:`INSTALLED_APPS` setting and run ``manage.py migrate`` to install it, the model :class:`django.contrib.sites.models.Site` will be installed into your database. Along with it a new instance of :class:`~django.contrib.contenttypes.models.ContentType` will be diff --git a/docs/ref/contrib/flatpages.txt b/docs/ref/contrib/flatpages.txt index 11d74d75c3..be9fe0c636 100644 --- a/docs/ref/contrib/flatpages.txt +++ b/docs/ref/contrib/flatpages.txt @@ -55,14 +55,14 @@ or: 3. Add ``'django.contrib.flatpages.middleware.FlatpageFallbackMiddleware'`` to your :setting:`MIDDLEWARE_CLASSES` setting. -4. Run the command :djadmin:`manage.py syncdb `. +4. Run the command :djadmin:`manage.py migrate `. .. currentmodule:: django.contrib.flatpages.middleware How it works ============ -``manage.py syncdb`` creates two tables in your database: ``django_flatpage`` +``manage.py migrate`` creates two tables in your database: ``django_flatpage`` and ``django_flatpage_sites``. ``django_flatpage`` is a simple lookup table that simply maps a URL to a title and bunch of text content. ``django_flatpage_sites`` associates a flatpage with a site. diff --git a/docs/ref/contrib/index.txt b/docs/ref/contrib/index.txt index e5cea01ead..727fab01dc 100644 --- a/docs/ref/contrib/index.txt +++ b/docs/ref/contrib/index.txt @@ -15,7 +15,7 @@ those packages have. For most of these add-ons -- specifically, the add-ons that include either models or template tags -- you'll need to add the package name (e.g., ``'django.contrib.admin'``) to your :setting:`INSTALLED_APPS` setting and - re-run ``manage.py syncdb``. + re-run ``manage.py migrate``. .. _"batteries included" philosophy: http://docs.python.org/tutorial/stdlib.html#batteries-included diff --git a/docs/ref/contrib/redirects.txt b/docs/ref/contrib/redirects.txt index 0c0cb2a3c2..eefbb96721 100644 --- a/docs/ref/contrib/redirects.txt +++ b/docs/ref/contrib/redirects.txt @@ -18,12 +18,12 @@ To install the redirects app, follow these steps: 2. Add ``'django.contrib.redirects'`` to your :setting:`INSTALLED_APPS` setting. 3. Add ``'django.contrib.redirects.middleware.RedirectFallbackMiddleware'`` to your :setting:`MIDDLEWARE_CLASSES` setting. -4. Run the command :djadmin:`manage.py syncdb `. +4. Run the command :djadmin:`manage.py migrate `. How it works ============ -``manage.py syncdb`` creates a ``django_redirect`` table in your database. This +``manage.py migrate`` creates a ``django_redirect`` table in your database. This is a simple lookup table with ``site_id``, ``old_path`` and ``new_path`` fields. The ``RedirectFallbackMiddleware`` does all of the work. Each time any Django diff --git a/docs/ref/contrib/sites.txt b/docs/ref/contrib/sites.txt index 65838dfa3e..48f781310c 100644 --- a/docs/ref/contrib/sites.txt +++ b/docs/ref/contrib/sites.txt @@ -264,7 +264,7 @@ To enable the sites framework, follow these steps: SITE_ID = 1 -3. Run :djadmin:`syncdb`. +3. Run :djadmin:`migrate`. ``django.contrib.sites`` registers a :data:`~django.db.models.signals.post_syncdb` signal handler which creates a diff --git a/docs/ref/databases.txt b/docs/ref/databases.txt index 29f2f3972d..60153eb735 100644 --- a/docs/ref/databases.txt +++ b/docs/ref/databases.txt @@ -224,7 +224,7 @@ If you upgrade an existing project to MySQL 5.5.5 and subsequently add some tables, ensure that your tables are using the same storage engine (i.e. MyISAM vs. InnoDB). Specifically, if tables that have a ``ForeignKey`` between them use different storage engines, you may see an error like the following when -running ``syncdb``:: +running ``migrate``:: _mysql_exceptions.OperationalError: ( 1005, "Can't create table '\\db_name\\.#sql-4a8_ab' (errno: 150)" @@ -663,7 +663,7 @@ required. .. _`Oracle Database Server`: http://www.oracle.com/ .. _`cx_Oracle`: http://cx-oracle.sourceforge.net/ -In order for the ``python manage.py syncdb`` command to work, your Oracle +In order for the ``python manage.py migrate`` command to work, your Oracle database user must have privileges to run the following commands: * CREATE TABLE @@ -752,7 +752,7 @@ Oracle imposes a name length limit of 30 characters. To accommodate this, the backend truncates database identifiers to fit, replacing the final four characters of the truncated name with a repeatable MD5 hash value. -When running syncdb, an ``ORA-06552`` error may be encountered if +When running ``migrate``, an ``ORA-06552`` error may be encountered if certain Oracle keywords are used as the name of a model field or the value of a ``db_column`` option. Django quotes all identifiers used in queries to prevent most such problems, but this error can still diff --git a/docs/ref/django-admin.txt b/docs/ref/django-admin.txt index 73992623aa..05fc8a1191 100644 --- a/docs/ref/django-admin.txt +++ b/docs/ref/django-admin.txt @@ -242,10 +242,8 @@ flush .. django-admin:: flush -Returns the database to the state it was in immediately after :djadmin:`syncdb` -was executed. This means that all data will be removed from the database, any -post-synchronization handlers will be re-executed, and the ``initial_data`` -fixture will be re-installed. +Removes all data from the database, re-executes any post-synchronization +handlers, and reinstalls any initial data fixtures. The :djadminopt:`--noinput` option may be provided to suppress all user prompts. @@ -1293,7 +1291,7 @@ This command is only available if Django's :doc:`authentication system Creates a superuser account (a user who has all permissions). This is useful if you need to create an initial superuser account but did not -do so during ``syncdb``, or if you need to programmatically generate +do so during the first ``migrate``, or if you need to programmatically generate superuser accounts for your site(s). When run interactively, this command will prompt for a password for @@ -1379,7 +1377,7 @@ allows for the following options: Example usage:: - django-admin.py syncdb --pythonpath='/home/djangoprojects/myproject' + django-admin.py migrate --pythonpath='/home/djangoprojects/myproject' Adds the given filesystem path to the Python `import search path`_. If this isn't provided, ``django-admin.py`` will use the ``PYTHONPATH`` environment @@ -1394,7 +1392,7 @@ setting the Python path for you. Example usage:: - django-admin.py syncdb --settings=mysite.settings + django-admin.py migrate --settings=mysite.settings Explicitly specifies the settings module to use. The settings module should be in Python package syntax, e.g. ``mysite.settings``. If this isn't provided, @@ -1408,7 +1406,7 @@ Note that this option is unnecessary in ``manage.py``, because it uses Example usage:: - django-admin.py syncdb --traceback + django-admin.py migrate --traceback By default, ``django-admin.py`` will show a simple error message whenever an :class:`~django.core.management.CommandError` occurs, but a full stack trace @@ -1424,7 +1422,7 @@ will also output a full stack trace when a ``CommandError`` is raised. Example usage:: - django-admin.py syncdb --verbosity 2 + django-admin.py migrate --verbosity 2 Use ``--verbosity`` to specify the amount of notification and debug information that ``django-admin.py`` should print to the console. diff --git a/docs/ref/models/options.txt b/docs/ref/models/options.txt index d54af37e86..6eeed51b6f 100644 --- a/docs/ref/models/options.txt +++ b/docs/ref/models/options.txt @@ -106,9 +106,9 @@ Django quotes column and table names behind the scenes. .. attribute:: Options.managed Defaults to ``True``, meaning Django will create the appropriate database - tables in :djadmin:`syncdb` and remove them as part of a :djadmin:`flush` - management command. That is, Django *manages* the database tables' - lifecycles. + tables in :djadmin:`migrate` or as part of migrations and remove them as + part of a :djadmin:`flush` management command. That is, Django + *manages* the database tables' lifecycles. If ``False``, no database table creation or deletion operations will be performed for this model. This is useful if the model represents an existing @@ -192,9 +192,9 @@ Django quotes column and table names behind the scenes. .. admonition:: Changing order_with_respect_to ``order_with_respect_to`` adds an additional field/database column - named ``_order``, so be sure to handle that as you would any other - change to your models if you add or change ``order_with_respect_to`` - after your initial :djadmin:`syncdb`. + named ``_order``, so be sure to make and apply the appropriate + migrations if you add or change ``order_with_respect_to`` + after your initial :djadmin:`migrate`. ``ordering`` ------------ diff --git a/docs/topics/auth/customizing.txt b/docs/topics/auth/customizing.txt index e27f257f80..e92e775bda 100644 --- a/docs/topics/auth/customizing.txt +++ b/docs/topics/auth/customizing.txt @@ -275,7 +275,7 @@ can or cannot do with Task instances, specific to your application:: ) The only thing this does is create those extra permissions when you run -:djadmin:`manage.py syncdb `. Your code is in charge of checking the +:djadmin:`manage.py migrate `. Your code is in charge of checking the value of these permissions when an user is trying to access the functionality provided by the application (viewing tasks, changing the status of tasks, closing tasks.) Continuing the above example, the following checks if a user may @@ -380,14 +380,12 @@ use as your User model. Changing :setting:`AUTH_USER_MODEL` has a big effect on your database structure. It changes the tables that are available, and it will affect the construction of foreign keys and many-to-many relationships. If you intend - to set :setting:`AUTH_USER_MODEL`, you should set it before running - ``manage.py syncdb`` for the first time. + to set :setting:`AUTH_USER_MODEL`, you should set it before creating + any migrations or running ``manage.py migrate`` for the first time. - If you have an existing project and you want to migrate to using a custom - User model, you may need to look into using a migration tool like South_ - to ease the transition. - -.. _South: http://south.aeracode.org + Changing this setting after you have tables created is not supported + by :djadmin:`makemigrations` and will result in you having to manually + write a set of migrations to fix your schema. Referencing the User model -------------------------- diff --git a/docs/topics/auth/default.txt b/docs/topics/auth/default.txt index b7f679bf28..cfa3ec3cad 100644 --- a/docs/topics/auth/default.txt +++ b/docs/topics/auth/default.txt @@ -65,7 +65,7 @@ interactively `. Creating superusers ------------------- -:djadmin:`manage.py syncdb ` prompts you to create a superuser the +:djadmin:`manage.py migrate ` prompts you to create a superuser the first time you run it with ``'django.contrib.auth'`` in your :setting:`INSTALLED_APPS`. If you need to create a superuser at a later date, you can use a command line utility:: @@ -190,13 +190,13 @@ setting, it will ensure that three default permissions -- add, change and delete -- are created for each Django model defined in one of your installed applications. -These permissions will be created when you run :djadmin:`manage.py syncdb -`; the first time you run ``syncdb`` after adding +These permissions will be created when you run :djadmin:`manage.py migrate +`; the first time you run ``migrate`` after adding ``django.contrib.auth`` to :setting:`INSTALLED_APPS`, the default permissions will be created for all previously-installed models, as well as for any new models being installed at that time. Afterward, it will create default -permissions for new models each time you run :djadmin:`manage.py syncdb -`. +permissions for new models each time you run :djadmin:`manage.py migrate +`. Assuming you have an application with an :attr:`~django.db.models.Options.app_label` ``foo`` and a model named ``Bar``, diff --git a/docs/topics/auth/index.txt b/docs/topics/auth/index.txt index 8447d449ce..81b6996d00 100644 --- a/docs/topics/auth/index.txt +++ b/docs/topics/auth/index.txt @@ -67,7 +67,7 @@ and two items in your :setting:`MIDDLEWARE_CLASSES` setting: 2. :class:`~django.contrib.auth.middleware.AuthenticationMiddleware` associates users with requests using sessions. -With these settings in place, running the command ``manage.py syncdb`` creates +With these settings in place, running the command ``manage.py migrate`` creates the necessary database tables for auth related models, creates permissions for any models defined in your installed apps, and prompts you to create a superuser account the first time you run it. diff --git a/docs/topics/db/models.txt b/docs/topics/db/models.txt index 2b565758e7..b0011e1098 100644 --- a/docs/topics/db/models.txt +++ b/docs/topics/db/models.txt @@ -77,7 +77,8 @@ application by the :djadmin:`manage.py startapp ` script), ) When you add new apps to :setting:`INSTALLED_APPS`, be sure to run -:djadmin:`manage.py syncdb `. +:djadmin:`manage.py migrate `, optionally making migrations +for them first with :djadmin:`manage.py makemigrations `. Fields ====== @@ -956,7 +957,7 @@ The reverse name of the ``common.ChildA.m2m`` field will be reverse name of the ``rare.ChildB.m2m`` field will be ``rare_childb_related``. It is up to you how you use the ``'%(class)s'`` and ``'%(app_label)s`` portion to construct your related name, but if you forget to use it, Django will raise -errors when you validate your models (or run :djadmin:`syncdb`). +errors when you validate your models (or run :djadmin:`migrate`). If you don't specify a :attr:`~django.db.models.ForeignKey.related_name` attribute for a field in an abstract base class, the default reverse name will @@ -1049,7 +1050,7 @@ are putting those types of relations on a subclass of another model, you **must** specify the :attr:`~django.db.models.ForeignKey.related_name` attribute on each such field. If you forget, Django will raise an error when you run -:djadmin:`validate` or :djadmin:`syncdb`. +:djadmin:`validate` or :djadmin:`migrate`. For example, using the above ``Place`` class again, let's create another subclass with a :class:`~django.db.models.ManyToManyField`:: diff --git a/docs/topics/http/sessions.txt b/docs/topics/http/sessions.txt index 772ee122d5..0b818c4f5d 100644 --- a/docs/topics/http/sessions.txt +++ b/docs/topics/http/sessions.txt @@ -44,7 +44,7 @@ Using database-backed sessions If you want to use a database-backed session, you need to add ``'django.contrib.sessions'`` to your :setting:`INSTALLED_APPS` setting. -Once you have configured your installation, run ``manage.py syncdb`` +Once you have configured your installation, run ``manage.py migrate`` to install the single database table that stores session data. .. _cached-sessions-backend: diff --git a/docs/topics/install.txt b/docs/topics/install.txt index 9cf02d96de..5d88ed4f82 100644 --- a/docs/topics/install.txt +++ b/docs/topics/install.txt @@ -122,14 +122,12 @@ database bindings are installed. * If you're using an unofficial 3rd party backend, please consult the documentation provided for any additional requirements. -If you plan to use Django's ``manage.py syncdb`` command to automatically +If you plan to use Django's ``manage.py migrate`` command to automatically create database tables for your models (after first installing Django and creating a project), you'll need to ensure that Django has permission to create and alter tables in the database you're using; if you plan to manually create the tables, you can simply grant Django ``SELECT``, ``INSERT``, ``UPDATE`` and -``DELETE`` permissions. On some databases, Django will need ``ALTER TABLE`` -privileges during ``syncdb`` but won't issue ``ALTER TABLE`` statements on a -table once ``syncdb`` has created it. After creating a database user with these +``DELETE`` permissions. After creating a database user with these permissions, you'll specify the details in your project's settings file, see :setting:`DATABASES` for details. diff --git a/docs/topics/migrations.txt b/docs/topics/migrations.txt index e24a7ce085..60f83e497c 100644 --- a/docs/topics/migrations.txt +++ b/docs/topics/migrations.txt @@ -31,7 +31,7 @@ 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. @@ -111,3 +111,113 @@ 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. + +Workflow +-------- + +Working with migrations is simple. Make changes to your models - say, add +a field and remove a model - and then run :djadmin:`makemigrations`:: + + $ python manage.py makemigrations + Migrations for 'books': + 0003_auto.py: + - Alter field author on book + +Your models will be scanned and compared to the versions currently +contained in your migration files, and then a new set of migrations +will be written out. Make sure to read the output to see what +``makemigrations`` thinks you have changed - it's not perfect, and for +complex changes it might not be detecting what you expect. + +Once you have your new migration files, you should apply them to your +database to make sure they work as expected:: + + $ python manage.py migrate + Operations to perform: + Synchronize unmigrated apps: sessions, admin, messages, auth, staticfiles, contenttypes + Apply all migrations: books + Synchronizing apps without migrations: + Creating tables... + Installing custom SQL... + Installing indexes... + Installed 0 object(s) from 0 fixture(s) + Running migrations: + Applying books.0003_auto... OK + +The command runs in two stages; first, it synchronizes unmigrated apps +(performing the same functionality that ``syncdb`` used to provide), and +then it runs any migrations that have not yet been applied. + +Once the migration is applied, commit the migration and the models change +to your version control system as a single commit - that way, when other +developers (or your production servers) check out the code, they'll +get both the changes to your models and the accompanying migration at the +same time. + +Dependencies +------------ + +While migrations are per-app, the tables and relationships implied by +your models are too complex to be created for just one app at a time. When +you make a migration that requires something else to run - for example, +you add a ForeignKey in your ``books`` app to your ``authors`` app - the +resulting migration will contain a dependency on a migration in ``authors``. + +This means that when you run the migrations, the ``authors`` migration runs +first and creates the table the ForeignKey references, and then the migration +that makes the ForeignKey column runs afterwards and creates the constraint. +If this didn't happen, the migration would try to create the ForeignKey column +without the table it's referencing existing and your database would +throw an error. + +This dependency behaviour affects most migration operations where you +restrict to a single app. Restricting to a single app (either in +``makemigrations`` or ``migrate``) is a best-efforts promise, and not +a guarantee; any other apps that need to be used to get dependencies correct +will be. + +Migration files +--------------- + +Migrations are stored as an on-disk format, referred to here as +"migration files". These files are actually just normal Python files with +an agreed-upon object layout, written in a declarative style. + +A basic migration file looks like this:: + + from django.db import migrations, models + + class Migration(migrations.Migration): + + dependencies = [("migrations", "0001_initial")] + + operations = [ + migrations.DeleteModel("Tribble"), + migrations.AddField("Author", "rating", models.IntegerField(default=0)), + ] + +What Django looks for when it loads a migration file (as a Python module) is +a subclass of ``django.db.migrations.Migration`` called ``Migration``. It then +inspects this object for four attributes, only two of which are used +most of the time: + +* ``dependencies``, a list of migrations this one depends on. +* ``operations``, a list of Operation classes that define what this migration + does. + +The operations are the key; they are a set of declarative instructions which +tell Django what schema changes need to be made. Django scans them and +builds an in-memory representation of all of the schema changes to all apps, +and uses this to generate the SQL which makes the schema changes. + +That in-memory structure is also used to work out what the differences are +between your models and the current state of your migrations; Django runs +through all the changes, in order, on an in-memory set of models to come +up with the state of your models last time you ran ``makemigrations``. It +then uses these models to compare against the ones in your ``models.py`` files +to work out what you have changed. + +You should rarely, if ever, need to edit migration files by hand, but +it's entirely possible to write them manually if you need to. Some of the +more complex operations are not autodetectable and are only available via +a hand-written migration, so don't be scared about editing them if you have to. diff --git a/docs/topics/serialization.txt b/docs/topics/serialization.txt index e88e16029e..d3fda16479 100644 --- a/docs/topics/serialization.txt +++ b/docs/topics/serialization.txt @@ -296,7 +296,7 @@ serialize an object that refers to a content type, then you need to have a way to refer to that content type to begin with. Since ``ContentType`` objects are automatically created by Django during the database synchronization process, the primary key of a given content type isn't easy to predict; it will -depend on how and when :djadmin:`syncdb` was executed. This is true for all +depend on how and when :djadmin:`migrate` was executed. This is true for all models which automatically generate objects, notably including :class:`~django.contrib.auth.models.Permission`, :class:`~django.contrib.auth.models.Group`, and diff --git a/docs/topics/testing/advanced.txt b/docs/topics/testing/advanced.txt index 2417274ab5..4d7f22aaa2 100644 --- a/docs/topics/testing/advanced.txt +++ b/docs/topics/testing/advanced.txt @@ -278,7 +278,7 @@ testing behavior. This behavior involves: #. Creating the test databases. -#. Running ``syncdb`` to install models and initial data into the test +#. Running ``migrate`` to install models and initial data into the test databases. #. Running the tests that were found. @@ -469,7 +469,7 @@ can be useful during testing. .. function:: create_test_db([verbosity=1, autoclobber=False]) - Creates a new test database and runs ``syncdb`` against it. + Creates a new test database and runs ``migrate`` against it. ``verbosity`` has the same behavior as in ``run_tests()``. diff --git a/docs/topics/testing/overview.txt b/docs/topics/testing/overview.txt index 0380d6931b..dbeaf0fb00 100644 --- a/docs/topics/testing/overview.txt +++ b/docs/topics/testing/overview.txt @@ -1215,9 +1215,9 @@ documentation` for more details. .. note:: - If you've ever run :djadmin:`manage.py syncdb`, you've + If you've ever run :djadmin:`manage.py migrate`, you've already used a fixture without even knowing it! When you call - :djadmin:`syncdb` in the database for the first time, Django + :djadmin:`migrate` in the database for the first time, Django installs a fixture called ``initial_data``. This gives you a way of populating a new database with any initial data, such as a default set of categories.