Improve migrations/schema docs

1 files changed, 61 insertions, 0 deletions

diff --git a/docs/ref/schema-editor.txt b/docs/ref/schema-editor.txt
index 5cff1de6ac..aeebfbc62a 100644
--- a/docs/ref/schema-editor.txt
+++ b/docs/ref/schema-editor.txt
@@ -26,6 +26,15 @@ the order you wish changes to be applied. Some possible operations or types
 of change are not possible on all databases - for example, MyISAM does not
 support foreign key constraints.
 
+If you are writing or maintaining a third-party database backend for Django,
+you will need to provide a SchemaEditor implementation in order to work with
+1.7's migration functionality - however, as long as your database is relatively
+standard in its use of SQL and relational design, you should be able to
+subclass one of the built-in Django SchemaEditor classes and just tweak the
+syntax a little. Also note that there are a few new database features that
+migrations will look for: ``can_rollback_ddl`` and
+``supports_combined_alters`` are the most important.
+
 Methods
 =======
 
@@ -47,6 +56,9 @@ create_model
 
     create_model(model)
 
+Creates a new table in the database for the provided model, along with any
+unique constraints or indexes it requires.
+
 
 delete_model
 ------------
@@ -55,6 +67,9 @@ delete_model
 
     delete_model(model)
 
+Drops the model's table in the database along with any unique constraints
+or indexes it has.
+
 
 alter_unique_together
 ---------------------
@@ -63,6 +78,9 @@ alter_unique_together
 
     alter_unique_together(model, old_unique_together, new_unique_together)
 
+Changes a model's unique_together value; this will add or remove unique
+constraints from the model's table until they match the new value.
+
 
 alter_index_together
 --------------------
@@ -71,6 +89,9 @@ alter_index_together
 
     alter_index_together(model, old_index_together, new_index_together)
 
+Changes a model's index_together value; this will add or remove indexes
+from the model's table until they match the new value.
+
 
 alter_db_table
 --------------
@@ -79,6 +100,8 @@ alter_db_table
 
     alter_db_table(model, old_db_table, new_db_table)
 
+Renames the model's table from ``old_db_table`` to ``new_db_table``.
+
 
 alter_db_tablespace
 -------------------
@@ -87,6 +110,8 @@ alter_db_tablespace
 
     alter_db_tablespace(model, old_db_tablespace, new_db_tablespace)
 
+Moves the model's table from one tablespace to another.
+
 
 add_field
 ---------
@@ -95,6 +120,17 @@ add_field
 
     add_field(model, field)
 
+Adds a column (or sometimes multiple) to the model's table to represent the
+field. This will also add indexes or a unique constraint
+if the field has ``db_index=True`` or ``unique=True``.
+
+If the field is a ManyToManyField without a value for ``through``, instead of
+creating a column, it will make a table to represent the relationship. If
+``through`` is provided, it is a no-op.
+
+If the field is a ``ForeignKey``, this will also add the foreign key
+constraint to the column.
+
 
 remove_field
 ------------
@@ -103,6 +139,14 @@ remove_field
 
     remove_field(model, field)
 
+Removes the column(s) representing the field from the model's table, along
+with any unique constraints, foreign key constraints, or indexes caused by
+that field.
+
+If the field is a ManyToManyField without a value for ``through``, it will
+remove the table created to track the relationship. If
+``through`` is provided, it is a no-op.
+
 
 alter_field
 ------------
@@ -110,3 +154,20 @@ alter_field
 ::
 
     alter_field(model, old_field, new_field, strict=False)
+
+This transforms the field on the model from the old field to the new one. This
+includes changing the name of the column (the ``db_column`` attribute),
+changing the type of the field (if the field class changes), changing
+the ``NULL`` status of the field, adding or removing field-only unique
+constraints and indexes, changing primary key, and changing the destination
+of ForeignKey constraints.
+
+The most common transformation this cannot do is transforming a
+ManyToManyField into a normal Field or vice-versa; Django cannot do this
+without losing data, and so it will refuse to do it. Instead, ``remove_field``
+and ``add_field`` should be called separately.
+
+If the database has the ``supports_combined_alters``, Django will try and
+do as many of these in a single database call as possible; otherwise, it will
+issue a separate ALTER statement for each change, but will not issue ALTERs
+where no change is required (as South often did).